内容
# mcp4kas - Kaspa MCP 服务器
> [!CAUTION]
> **这是一个实验性项目。 不应认为它对钱包操作是安全的。 请自担风险。 不要与您无法承受损失的资金的钱包一起使用。**
一个用 Rust 编写的 [MCP（模型上下文协议）](https://modelcontextprotocol.io/) 服务器，通过 stdio 传输暴露 Kaspa L1 区块链 RPC 工具。 允许任何兼容 MCP 的 AI 客户端（Claude Desktop、Claude Code 等）查询 Kaspa DAG、检查区块和交易、检查余额，并使用可选的 `wallet` 功能管理 HD 钱包和发送交易。
## 快速开始
```bash
# 只读模式（默认）
cargo build
cargo run
# 启用钱包管理
cargo build --features wallet
cargo run --features wallet
```
服务器通过 wRPC 连接到 Kaspa 节点，并通过 stdin/stdout 与 MCP 客户端通信。
## 客户端配置
在构建完成后，配置您的 AI 应用程序以运行服务器二进制文件。 以下是流行的 MCP 兼容客户端的示例。 请根据您构建二进制文件的位置调整路径。
> [!TIP]
> 如果您没有设置 `KASPA_WRPC_URL`，服务器将使用公共解析器。 为了可靠性，请将其指向您自己的节点（例如 `ws://127.0.0.1:17110`）。
### Claude Desktop
编辑 `claude_desktop_config.json`：
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
```
要启用钱包工具，请使用 `cargo build --release --features wallet` 构建，并使用该二进制文件。
### Claude Code（CLI）
将以下内容添加到项目的 `.mcp.json` 或全局 `~/.claude/settings.json` 中：
```json
{
"mcpServers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
```
或交互式添加：
```bash
claude mcp add kaspa /path/to/mcp4kas -e KASPA_WRPC_URL=ws://127.0.0.1:17110
```
### Cursor
打开 **设置 → MCP** 并添加新服务器，或编辑项目根目录中的 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
```
### Windsurf
编辑 `~/.codeium/windsurf/mcp_config.json`：
```json
{
"mcpServers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
```
### VS Code（Copilot）
将以下内容添加到用户或工作区 `settings.json` 中：
```json
{
"mcp": {
"servers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
}
```
或在项目中添加 `.vscode/mcp.json` 文件：
```json
{
"servers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
```
### Continue（VS Code / JetBrains）
编辑 `~/.continue/config.yaml`：
```yaml
mcpServers:
- name: kaspa
command: /path/to/mcp4kas
env:
KASPA_WRPC_URL: "ws://127.0.0.1:17110"
```
### Cline（VS Code）
打开 **Cline → MCP Servers → Configure** 或编辑 `cline_mcp_settings.json`：
```json
{
"mcpServers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
```
> [!NOTE]
> 所有客户端都使用 stdio 传输 - 不需要为 MCP 连接设置端口或 URL。 `KASPA_WRPC_URL` 环境变量是 Kaspa 节点端点，而不是 MCP 传输。
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `KASPA_WRPC_URL` | *(公共解析器)* | 直接 wRPC 端点（例如 `ws://127.0.0.1:17110`）。 如果未设置，则使用默认公共解析器。 |
| `KASPA_NETWORK` | `mainnet` | 网络 ID。 接受 `mainnet`、`testnet-10`、`testnet-11` 等。 |
## 测试
```bash
# 运行所有测试（仅只读 RPC 工具）
cargo test
# 运行所有测试，包括钱包测试
cargo test --features wallet
# 按名称运行特定测试
cargo test test_name
# 运行测试并显示输出
cargo test -- --nocapture
```
### 测试内容
测试 **不** 需要运行的 Kaspa 节点。 它们验证：
- **服务器元数据** - 名称、版本、功能和说明是否正确设置
- **工具路由器注册** - 所有预期的工具是否注册，数量是否准确
- **输入验证** - 地址数量限制、哈希解析、地址解析（有效主网、空、无效、错误消息）
- **参数反序列化** - 每个参数结构体是否能从 JSON 正确反序列化，包括可选字段和缺少必填字段拒绝
- **JSON 模式生成** - 模式是否具有预期的属性、描述和正确的必填/可选字段分类
- **路由器合并**（钱包功能）- RPC 和钱包路由器是否正确合并，无工具丢失
## MCP 工具参考
### RPC 工具（始终可用）
这些是只读工具，查询连接的 Kaspa 节点。
#### DAG 和网络状态
| 工具 | 描述 |
|---|---|
| `get_block_dag_info` | 获取 DAG 状态信息，包括提示哈希、难度和网络统计 |
| `get_current_network` | 获取活动网络（主网/测试网） |
| `get_sync_status` | 获取节点同步状态 |
| `get_server_info` | 获取连接节点服务器信息（版本、网络、同步状态） |
| `get_node_info` | 获取常规节点信息（P2P ID、内存池大小、服务器版本等） |
| `get_system_info` | 获取系统信息（CPU 数量、版本、内存） |
| `get_coin_supply` | 获取流通和最大货币供应 |
| `get_sink` | 获取当前虚拟的选择父节点（sink）哈希 |
| `get_sink_blue_score` | 获取虚拟的选择父节点（sink）的蓝色分数 |
| `ping` | 乒乓连接的 Kaspa 节点 |
#### 区块和头部
| 工具 | 描述 |
|---|---|
| `get_block` | 按哈希获取区块数据 |
| `get_blocks` | 从低哈希开始获取多个区块 |
| `get_block_count` | 获取当前区块数量（头部数量和区块数量） |
| `get_headers` | 从给定哈希开始获取区块头部 |
| `get_virtual_chain_from_block` | 从特定区块哈希获取虚拟链 |
| `get_current_block_color` | 获取给定区块哈希的区块颜色（蓝色/红色） |
#### 余额和 UTXO
| 工具 | 描述 |
|---|---|
| `get_balance_by_address` | 获取单个 Kaspa 地址的余额（需要带有 `--utxoindex` 的节点） |
| `get_balances_by_addresses` | 获取多个 Kaspa 地址的余额（最多 100 个） |
| `get_utxos_by_addresses` | 获取给定 Kaspa 地址的 UTXO（需要带有 `--utxoindex` 的节点，最多 100 个地址） |
| `get_utxo_return_address` | 获取交易的 UTXO 返回地址 |
#### 内存池
| 工具 | 描述 |
|---|---|
| `get_mempool_entries` | 获取内存池条目 |
| `get_mempool_entry` | 按交易 ID 获取单个内存池条目 |
| `get_mempool_entries_by_addresses` | 按地址过滤获取内存池条目（最多 100 个） |
#### 对等节点和连接
| 工具 | 描述 |
|---|---|
| `get_connected_peer_info` | 获取连接的对等节点详细信息 |
| `get_peer_addresses` | 获取当前网络中已知的对等节点地址 |
| `get_connections` | 获取连接数量和可选配置文件数据 |
#### 费用和指标
| 工具 | 描述 |
|---|---|
| `get_fee_estimate` | 获取当前费用估计 |
| `get_fee_estimate_experimental` | 获取实验性费用估计，带有可选的详细数据 |
| `get_metrics` | 获取节点指标（进程、连接、带宽、共识、存储、自定义） |
| `estimate_network_hashes_per_second` | 估计每秒网络哈希 |
#### 杂项
| 工具 | 描述 |
|---|---|
| `get_subnetwork` | 按子网络 ID 获取子网络信息 |
| `get_daa_score_timestamp_estimate` | 将 DAA 分数转换为估计的时间戳（最多 100 个分数） |
### 钱包工具（需要 `--features wallet`）
> [!CAUTION]
> **这是一个实验性项目。 不应认为它对钱包操作是安全的。 请自担风险。 不要与您无法承受损失的资金的钱包一起使用。**
这些工具需要 `wallet` 功能标志。 钱包文件使用 XChaCha20-Poly1305 + Argon2 进行静态加密。
#### 钱包生命周期
| 工具 | 描述 |
|---|---|
| `wallet_create` | 创建一个新的加密钱包文件，带有默认 BIP-32 账户。 返回钱包描述符（不是助记词）。 |
| `wallet_open` | 打开现有的加密钱包文件并启动钱包运行时 |
| `wallet_close` | 关闭当前打开的钱包 |
| `wallet_status` | 获取当前钱包状态（打开/关闭，账户数量） |
| `wallet_list` | 列出磁盘上可用的钱包文件 |
| `wallet_export_mnemonic` | 导出钱包的 BIP-39 助记词（种子短语）用于备份 |
| `wallet_import` | 从 BIP-39 助记词导入现有钱包 |
| `wallet_hint` | 设置或删除钱包钓鱼提示 |
#### 账户管理
| 工具 | 描述 |
|---|---|
| `accounts_create` | 在打开的钱包中创建新的 BIP-32 账户 |
| `accounts_list` | 列出打开的钱包中的所有账户 |
| `account_details` | 获取详细的账户信息，包括扩展公钥（xpub）和接收地址 |
| `account_balance` | 获取特定账户的余额（以 sompi 为单位；1 KAS = 100,000,000 sompi） |
| `account_new_address` | 为账户导出新的接收地址 |
| `account_rename` | 重命名账户或删除其名称 |
| `account_import_mnemonic` | 将账户从 BIP-39 助记词导入当前打开的钱包 |
| `account_watch_bip32` | 从扩展公钥（xpub）创建只读 BIP-32 账户 |
| `account_scan` | 扫描账户的扩展地址派生链 |
| `account_sweep` | 将账户的所有 UTXO 汇总到其自己的变更地址 |
#### 交易
| 工具 | 描述 |
|---|---|
| `account_send` | 从账户发送 KAS。 构建、签名并提交交易。 |
| `account_transfer` | 在同一钱包中的账户之间转移 KAS |
| `account_estimate` | 在不实际发送的情况下估计交易费用 |
#### 交易历史
| 工具 | 描述 |
|---|---|
| `history_list` | 列出账户的近期交易历史 |
| `history_details` | 列出具有完整 UTXO 详细信息的近期交易历史 |
| `history_lookup` | 从钱包的本地存储中查找特定交易 ID |
#### 消息签名
| 工具 | 描述 |
|---|---|
| `message_sign` | 使用与 Kaspa 地址对应的私钥签名消息 |
| `message_verify` | 验证消息签名是否与 Kaspa 地址匹配 |
## 安全说明
- **默认只读** - 没有 `wallet` 功能， 只暴露读取/查询 RPC。
- **静态加密** - 钱包文件使用 XChaCha20-Poly1305 + Argon2 密钥派生。
- **创建时没有助记词** - `wallet_create` 不返回助记词。 请显式使用 `wallet_export_mnemonic`。
- **响应中没有私钥** - 私钥从不出现在工具输出中。
- **通过参数传递秘密** - 钱包密码和助记词作为工具参数传递（固有的 MCP/stdio 限制）。
## 架构
```
src/
main.rs 服务器引导、wRPC 客户端、MCP 服务器设置、stdio 传输
rpc.rs 只读 MCP 工具实现（31 个工具）
wallet/
mod.rs 模块根（取决于 `wallet` 功能）
params.rs 钱包工具的参数结构体
tools.rs 钱包工具实现（25 个工具）
```
## 许可证
请参阅 [LICENSE](LICENSE) 获取详细信息。
