内容
# kaspa-node-mcp
用于通过WebSocket与任何[rusty-kaspa](https://github.com/kaspanet/rusty-kaspa)节点进行交互的MCP服务器。
为AI代理（Claude Code、OpenClaw等）提供查询Kaspa区块链、管理钱包和提交交易（包括在链上锚定和验证KPM有效载荷）的能力。
## 功能
- **任意网络**：主网、testnet-10、testnet-11、testnet-12、开发网
- **完整钱包**：BIP39助记词生成、BIP44派生、加密持久化
- **交易**：通过WASM生成器（符合KIP-9）构建、签名和提交
- **KPM感知**：自动解析KPM锚定有效载荷（`KPM1 || mode || hash`）
- **加密钱包**：AES-256-GCM，带有scrypt KDF，存储在`~/.kaspa-mcp/wallet.enc`
- **两种传输方式**：stdio（Claude Code）或HTTP（OpenClaw / 远程）
- **延迟连接**：服务器立即启动，在第一次工具调用时连接到节点
## 工具
### 只读区块链查询
| 工具 | 目的 |
|------|---------|
| `kaspa_get_info` | 节点健康状况（同步状态、内存池、版本） |
| `kaspa_get_server_info` | 网络ID、RPC版本、DAA分数 |
| `kaspa_get_block_dag_info` | DAG状态（提示、难度、区块数量） |
| `kaspa_get_block` | 按哈希获取区块，可选交易 |
| `kaspa_get_balance` | 地址余额（sompi和KAS） |
| `kaspa_get_utxos` | 最多100个地址的UTXO集合 |
| `kaspa_find_transaction_in_block` | 在特定区块中查找和解析交易 |
| `kaspa_search_blocks_for_transaction` | 广度优先搜索最近区块中的交易ID |
| `kaspa_verify_kpm_anchor` | 验证链上KPM锚定有效载荷 |
| `kaspa_get_coin_supply` | 流通和最大供应量 |
### 钱包管理
| 工具 | 目的 |
|------|---------|
| `kaspa_generate_mnemonic` | 生成BIP39助记词，自动激活钱包 |
| `kaspa_get_my_address` | 显示活动钱包地址和网络 |
| `kaspa_save_wallet` | 将助记词加密到`~/.kaspa-mcp/wallet.enc` |
| `kaspa_load_wallet` | 解密并激活会话钱包 |
| `kaspa_estimate_fee` | 从连接的节点估计手续费 |
### 交易
| 工具 | 目的 |
|------|---------|
| `kaspa_send_transaction` | 构建、签名、提交KAS转账（可选有效载荷） |
## 先决条件
- Node.js 20+
- 运行中的rusty-kaspa节点，启用wRPC Borsh
```bash
# Testnet-12
supertypo/rusty-kaspad --testnet --netsuffix=12 --utxoindex
# 主网
kaspad --utxoindex
```
## 安装
```bash
git clone https://github.com/27inator/Kaspa-node-mcp.git
cd kaspa-node-mcp
npm install
npm run build
```
## 使用
### 与Claude Code（stdio）一起使用
将以下内容添加到您的Claude Code MCP设置中：
```json
{
"mcpServers": {
"kaspa-node": {
"command": "node",
"args": ["/path/to/kaspa-node-mcp/dist/index.js"],
"env": {
"KASPA_ENDPOINT": "ws://localhost:17210"
}
}
}
}
```
### 与OpenClaw（HTTP）一起使用
```bash
KASPA_ENDPOINT=ws://localhost:17210 TRANSPORT=http PORT=3001 node dist/index.js
```
然后在OpenClaw中注册为MCP端点，网址为`http://localhost:3001/mcp`。
## 钱包设置
### 首次使用
```
1. 使用kaspa_generate_mnemonic → 钱包自动激活，显示地址
2. 使用kaspa_save_wallet(password) → 加密到 ~/.kaspa-mcp/wallet.enc
3. 使用测试网KAS资助地址
```
### 每次会话后
```
服务器启动 → "发现加密钱包。使用kaspa_load_wallet解锁。"
1. 使用kaspa_load_wallet(password) → 钱包解锁，准备使用
```
不需要环境变量。助记词在静止状态下使用AES-256-GCM（scrypt密钥派生，N=65536，r=8，p=1）加密。文件权限：`0600`。
### 替代方案：环境变量
如果您更喜欢环境变量而不是加密文件：
```bash
KASPA_MNEMONIC="您的24个单词的助记词短语"
# 或
KASPA_PRIVATE_KEY="十六进制私钥"
```
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `KASPA_ENDPOINT` | `ws://localhost:17210` | wRPC Borsh WebSocket URL |
| `KASPA_NETWORK` | *(自动检测)* | 网络：主网、testnet-10、testnet-11、testnet-12 |
| `KASPA_MNEMONIC` | | BIP39助记词短语（如果使用加密钱包，则可选） |
| `KASPA_PRIVATE_KEY` | | 十六进制私钥，助记词的替代品 |
| `KASPA_ACCOUNT_INDEX` | `0` | BIP44账户索引 |
| `TRANSPORT` | `stdio` | 传输方式：`stdio`或`http` |
| `PORT` | `3000` | HTTP端口（仅限http传输） |
## 默认端口（按网络划分）
| 网络 | wRPC Borsh | wRPC JSON |
|---------|-----------|-----------|
| 主网 | 17110 | 18110 |
| Testnet-10 | 17210 | 18210 |
| Testnet-11 | 17310 | 18310 |
| Testnet-12 | 17210 | 18210 |
该服务器使用**wRPC Borsh**（17xxx端口），不支持JSON。
## KPM锚定验证
`kaspa_verify_kpm_anchor`工具解析KPM的链上有效载荷格式：
```
字节："KPM1"（4字节）|| modeByte（1字节）|| hash（32字节）
总计：37字节
modeByte 0x01 = INDIVIDUAL（单个事件哈希）
modeByte 0x02 = MERKLE（Merkle根）
```
验证流程：
1. KPM在区块B中锚定数据，交易ID为T
2. 调用`kaspa_verify_kpm_anchor`，区块哈希=B，交易ID=T，预期哈希=X
3. 工具获取区块，找到交易，解析KPM有效载荷
4. 如果链上哈希匹配，则返回`verified: true`
## 开发
```bash
npm run dev # 监视模式（tsc --watch）
npm run build # 编译到dist/
npm start # 运行服务器
```
### 测试
```bash
node test-wallet-store.mjs # 加密钱包：34个断言
node test-full-workflow.mjs # 端到端：生成 → 保存 → 加载
node test-smoke.mjs # 节点集成（需要运行的TN12节点）
```
## 许可证
MIT
