内容
# kaspa-agent-mcp
基于 Agent 的 Kaspa MCP 服务器。fork 自 [kaspa-node-mcp](https://github.com/27inator/Kaspa-node-mcp)，并围绕三个原则重新定位：
1. **零偏见** — 影响资金和共识的参数是必需的，但绝不默认。策略存在于调用者中，而非服务器。
2. **实时** — wRPC 订阅（`blockAdded`、`virtualChainChanged`、`utxosChanged`、`finalityConflict`）作为 MCP 资源以 `subscribe`/`notifications/resources/updated` 接口呈现，因此代理会做出反应而不是轮询。
3. **一步到位** — 声明式工具（`submit_payment`、`query_dag`、`await_condition`）在服务器端组合多步骤工作流，并通过 MCP 的进度通知通道流式传输进度。
构建在与上游服务器相同的 wRPC Borsh + kaspa-wasm 基础上；工具表面是变化的内容。
## 功能
- **任意网络**：主网、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
```
然后在 `http://localhost:3001/mcp` 处注册为 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
