Rootstock MCP Server

RSK MCP 服务 - Rootstock 区块链工具

Rootstock MCP 服务 是一种模型上下文协议（MCP）服务，提供用于与 Rootstock（RSK）区块链交互的高级工具。此项目使 AI 客户端能够无缝连接并执行区块链操作。

🚀 主要功能

• 💼 钱包管理：创建、导入、切换和管理多个钱包
• 💰 余额查询：查询 rBTC 和 ERC20 代币余额
• 💸 转账：向其他地址发送 rBTC 和代币
• 🔍 交易跟踪：通过哈希验证交易状态
• 🚀 合约部署：在 Rootstock 上部署智能合约
• ✅ 合约验证：验证已部署的合约
• 📄 合约交互：读取已验证合约中的数据
• 📊 历史记录：查询交易历史
• 🎯 证明：使用 RAS（Rootstock Attestation Service）创建、验证和管理证明
• 🏗️ 模式管理：创建和管理证明模式
• 📝 证明查询：按各种条件列出和筛选证明

🧰 可用工具

此服务提供 22 个 MCP 工具。你无需直接调用这些工具——连接 MCP 后，AI 客户端会根据你的提示词选择合适的工具。

类别	工具	描述
会话	start-interaction	开始使用 Rootstock CLI 函数进行交互
会话	list-pending-operations	列出等待确认的待处理操作（部署、转账）
会话	confirm-operation	按 ID 确认并执行待处理操作
会话	cancel-operation	按 ID 取消待处理操作
钱包	start-wallet-interaction	显示可用的钱包管理操作
钱包	create-wallet	创建、导入、列出、切换或删除钱包
钱包	use-wallet-from-creation	重新使用之前 create-wallet 结果中的钱包数据，无需重新上传
余额	check-balance	查询 rBTC 或 ERC20 代币余额
转账	transfer-tokens	在钱包之间转移 rBTC 或 ERC20 代币
交易	check-transaction	按哈希查询交易状态和详情
交易	check-transaction-history	通过 Alchemy API 查询钱包的交易历史
合约	deploy-contract	使用 ABI 和字节码部署智能合约
合约	verify-contract	验证已部署合约的源代码
合约	read-contract	调用已验证合约的 view/pure 函数
证明	issue-attestation	通过 RAS（Rootstock Attestation Service）签发新证明
证明	verify-attestation	按 UID 验证已有证明
证明	revoke-attestation	按 UID 撤销已有证明
证明	list-attestations	按事件日志查询证明（需要自定义 RPC URL）
证明	create-schema	注册新的证明模式
证明	attest-deployment	使用 RAS 默认模式证明合约部署
证明	attest-verification	使用 RAS 默认模式证明合约验证
证明	attest-transfer	使用 RAS 默认模式证明代币转账

参数和示例请参阅下文的详细功能。

📋 前置条件

• Node.js v18 或更高版本
• npm 或 yarn
• TypeScript（包含在开发依赖中）

注意： 你将通过兼容 MCP 标准的大模型客户端（例如 Cursor、Claude、Warp 等）使用此 Model Context Protocol 服务。请注意，此处需要完成两个步骤：

1. 安装和构建
2. AI 客户端配置

重要：必须完成这两项设置，才能在客户端中正确使用 MCP。

🛠️ 安装和构建

1. 克隆代码库

git clone https://github.com/rsksmart/rsk-mcp-server
cd rsk-mcp-server

2. 安装依赖

npm install

3. 构建项目

npm run build

此命令将：

• 将 TypeScript 编译为 JavaScript，并输出到 build/ 文件夹
• 将主文件设为可执行文件（build/index.js）

4. 验证安装

node build/index.js

重要说明： 在本地运行此 MCP 时，客户端会指向构建后在 build 文件夹中生成的 index.js 文件。

⚙️ AI 客户端配置

🏠 远程配置

对于 Cursor IDE

在 Cursor 中，前往“设置”>“Cursor 设置”>“工具和集成”

你会看到 Add Custom MCP 选项

并添加到 JSON 文件中：

{
  "mcpServers": {
    "rsk-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@rsksmart/rsk-mcp-server"
      ]
    }
  }
}
// The Args field contains the path to the index.js file created by the build.

注意： 有关 Cursor 的安装参考，请按照此处的说明进行操作。

在 Cursor 中安装后，你应该会看到类似以下的界面：

绿色圆点表示安装成功。

对于 Claude Desktop（Anthropic）

编辑 Claude Desktop 配置文件：

打开 Claude 客户端，然后点击“设置/开发者”

点击“Edit Config”按钮打开配置文件，并添加以下配置：

注意： 如果配置文件不存在，此操作会创建一个新文件；如果已存在，则会打开现有配置文件。文件位于：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "rsk-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@rsksmart/rsk-mcp-server"
      ]
    }
  }
}
// The Args field contains the path to the index.js file created by the build.

注意： 有关 Claude 的安装参考，请按照此处的说明进行操作。

在 Claude 客户端中安装此 MCP 后，点击 Web 搜索选项下的 Search and tools 选项即可看到它（见下图）

🏠 本地配置

对于 Cursor IDE

在 Cursor 中，前往“设置”>“Cursor 设置”>“工具和集成”

你会看到 Add Custom MCP 选项

并添加到 JSON 文件中：

{
  "mcpServers": {
    "rsk-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/rsk-mcp-server/build/index.js"]
    }
  }
}
// The Args field contains the path to the index.js file created by the build.

注意： 有关 Cursor 的安装参考，请按照此处的说明进行操作。

在 Cursor 中安装后，你应该会看到类似以下的界面：

绿色圆点表示安装成功。

适用于 Claude Desktop（Anthropic）

编辑 Claude Desktop 配置文件：

打开 Claude 客户端，然后点击 Settings/Developer

点击“Edit Config”按钮，打开配置文件并添加以下配置：

注意： 如果配置文件不存在，此操作会创建一个新文件；如果已存在，则会打开现有配置文件。文件位于：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "rsk-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/rsk-mcp-server/build/index.js"],
      "env": {}
    }
  }
}
// The Args field contains the path to the index.js file created by the build.

注意： 有关 Claude 的安装参考，请按照以下说明操作 此处

在 Claude 客户端上安装此 MCP 后，点击 Web search 选项下的 Search and tools选项即可看到它（见下图）

适用于其他 MCP 实现

任何兼容 MCP 的客户端都可以通过以下方式连接：

node /path/to/project/rsk-mcp-server/build/index.js

🌐 远程配置（URL）

注意： 将服务部署到公共端点后，即可使用此功能。

远程客户端配置

{
  "mcpServers": {
    "rsk-mcp": {
      "url": "https://your-server.com/mcp-endpoint",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

🔧 详细功能

在客户端安装此 MCP 后，您可以通过聊天框输入提示词与其交互。例如，可以输入以下提示词来开始与此 MCP 交互： I would like to start interacting with Rootstock

接下来，系统会要求您授予使用 MCP 工具的权限。点击接受后，它应该会给出类似以下的回答：

Perfect! The Rootstock CLI is now active and ready to help you interact with the Rootstock blockchain. Here are the available options:
Available Rootstock Operations:
💼 wallet - Manage your wallet (create new, use existing, or import)
💰 balance - Check wallet balances
💸 transfer - Transfer RBTC or ERC20 tokens
🔍 tx - Check transaction status
🚀 deploy - Deploy a smart contract
✅ verify - Verify a contract
📄 contract - Interact with a contract
📊 history - Check transaction history
❓ help - Display help
What would you like to do? If you don't have a wallet yet, I'd recommend starting with option 1 (wallet management) to create or import a wallet first. Then you can proceed with other operations like checking balances, transferring tokens, or deploying contracts.
Which option interests you?

您可以根据需要继续此流程。

1. 🧭 会话与交互

可用工具：

• start-interaction：入口工具——用户首次询问 Rootstock 时，从这里开始。列出所有可用操作。
• list-pending-operations：列出等待确认的操作（合约部署、代币转账）
• confirm-operation：使用操作 ID 确认并执行待处理操作
• cancel-operation：使用操作 ID 取消并丢弃待处理操作

为什么需要确认： deploy-contract 和 transfer-tokens 等关键操作在每次调用时都需要 confirmAction 布尔值——省略该值会导致架构验证失败。传入 confirmAction: false 会创建待处理操作（5 分钟后过期），而不是执行操作；在通过 confirm-operation 确认之前，链上不会发生任何操作。首次调用时传入 confirmAction: true 会完全跳过待处理步骤——工具描述本身会指示 AI Agent 在真人明确批准操作之前不要这样做，因此应将其视为已获批准的自动化流程的特殊选项，而不是默认流程。

列出待处理操作

{} // no parameters

确认操作

{
  operationId: "op_1700000000000_abc123xyz" // ID returned when the operation was created
}

取消操作

{
  operationId: "op_1700000000000_abc123xyz"
}

2. 💼 钱包管理

可用工具：

• start-wallet-interaction：初始化钱包管理
• create-wallet：创建／导入／管理钱包
• use-wallet-from-creation：复用之前 create-wallet 结果中的钱包数据，无需重新上传

支持的操作：

🆕 创建新钱包

// Creates a wallet with secure password
{
  walletOption: "🆕 Create a new wallet",
  walletName: "MyWallet",
  walletPassword: "secure_password",
  replaceCurrentWallet: false
}

🔑 导入现有钱包

// Import using private key
{
  walletOption: "🔑 Import existing wallet",
  walletName: "ImportedWallet",
  privateKey: "0x...",
  walletPassword: "secure_password"
}

🔍 列出已保存的钱包

// List all available wallets
{
  walletOption: "🔍 List saved wallets",
  walletData: "my-wallets.json_content"
}

🔁 切换当前钱包

// Switch to another wallet
{
  walletOption: "🔁 Switch wallet", 
  newMainWallet: "WalletName"
}

♻️ 复用之前创建的钱包

// Skips re-uploading wallet data by referencing the create-wallet result
{
  testnet: true,
  token: "rBTC",
  walletCreationResult: "{\"walletsData\":{...}}" // the full JSON string returned by create-wallet, not a parsed object
}

3. 💰 余额查询

工具：check-balance

支持的代币：

• rBTC - Rootstock 原生代币
• USDT - Tether USD
• DOC - Dollar on Chain
• BPRO - BitPro
• RIF - RIF Token
• FISH - Fish Token
• 自定义代币 - 任意 ERC20 代币

示例：

{
  testnet: true, // true for testnet, false for mainnet
  token: "rBTC",
  walletName: "MyWallet" // optional, uses current wallet if not specified
}

自定义代币：

{
  testnet: true,
  token: "Custom Token",
  customTokenAddress: "0x...", // token contract address
  walletName: "MyWallet"
}

4. 💸 代币转账

工具：transfer-tokens

在钱包之间转移 rBTC 或 ERC20 代币。与 deploy-contract 一样，每次调用都必须使用 confirmAction：传入 false 可返回待处理操作，该操作必须先通过 confirm-operation 确认才会执行；只有在真人批准转账后，才能传入 true。

要求：

• 收款地址
• 金额（数字，而非字符串）
• 余额充足的钱包
• 代币合约地址（可选；转移原生 rBTC 时省略）

示例：

{
  testnet: true,
  toAddress: "0x...", // recipient address
  value: 0.01, // amount to transfer (number)
  tokenAddress: "0x...", // optional, omit for native rBTC transfers
  walletData: "my-wallets.json_content",
  walletPassword: "wallet_password",
  confirmAction: false // required on every call; false requires confirm-operation, true executes immediately
}

5. 🔍 交易跟踪

工具：check-transaction

{
  testnet: true, // network to check
  txid: "0x..." // transaction hash (with or without 0x prefix)
}

返回信息：

• 交易状态（待处理／已确认／失败）
• 区块编号
• 已使用的 Gas
• 转账详情
• 时间戳

6. 📊 交易历史

工具：check-transaction-history

使用 Alchemy API 查询钱包的交易历史。

要求：

• Alchemy API 密钥（可选；省略时会回退使用已存储的密钥）

示例：

{
  testnet: true,
  apiKey: "your-alchemy-api-key", // optional, uses a stored key if omitted
  number: "10", // number of transactions to retrieve (string)
  walletData: "my-wallets.json_content"
}

7. 🚀 合约部署

工具：deploy-contract

要求：

• 合约 ABI（JSON）
• 编译后的字节码（十六进制）
• 构造函数参数（可选）
• 余额充足的钱包

示例：

{
  testnet: true,
  abiContent: `[{"inputs":[],"name":"myFunction"...}]`, // complete ABI
  bytecodeContent: "0x608060405234801561001057600080fd5b50...", // bytecode
  constructorArgs: ["arg1", "arg2"], // constructor arguments
  walletData: "my-wallets.json_content",
  walletPassword: "wallet_password"
}

8. ✅ 合约验证

工具：verify-contract

要求：

• 已部署的合约地址
• Solidity 源代码
• 编译元数据（JSON Standard Input）
• 使用的构造函数参数

示例：

{
  testnet: true,
  contractAddress: "0x...", // contract address
  contractName: "MyContract", // exact name in source code
  jsonContent: `{"language":"Solidity","sources":{...}}`, // compilation metadata
  constructorArgs: ["arg1", "arg2"] // arguments used in deployment
}

9. 📄 合约读取

列出可用函数：

{
  testnet: true,
  contractAddress: "0x..." // must be a verified contract
}

调用函数：

{
  testnet: true,
  contractAddress: "0x...",
  functionName: "balanceOf", // view/pure function name
  functionArgs: ["0x..."] // function arguments
}

10. 🌐 支持的网络

Rootstock 主网

• RPC URL： https://public-node.rsk.co
• Chain ID： 30
• 区块浏览器： https://explorer.rootstock.io

Rootstock 测试网

• RPC URL： https://public-node.testnet.rsk.co
• Chain ID： 31
• 区块浏览器： https://explorer.testnet.rootstock.io

11. 🎯 证明管理

可用的证明工具：

• issue-attestation：使用原始架构和编码数据创建新证明
• verify-attestation：通过 UID 验证现有证明
• revoke-attestation：撤销证明
• list-attestations：通过事件日志查询证明（需要自定义 RPC URL）
• create-schema：注册新的证明架构
• attest-deployment：使用 RAS 默认架构创建部署证明
• attest-verification：使用 RAS 默认架构创建合约验证证明
• attest-transfer：使用 RAS 默认架构创建转账证明

🎯 签发证明

{
  testnet: true,
  recipient: "0x...", // recipient address
  schema: "0x...", // schema UID
  data: "encoded_data", // schema-encoded data
  expirationTime: 0, // optional timestamp
  revocable: true // optional
}

🔍 验证证明

{
  testnet: true,
  uid: "0x..." // attestation UID
}

❌ 撤销证明

{
  testnet: true,
  uid: "0x...", // attestation UID
  walletData: {}, // wallet configuration
  walletPassword: "password"
}

📋 列出证明

注意： RSK 公共节点不支持 eth_getLogs。必须使用来自 Alchemy 或 GetBlock 等服务提供商的自定义 rpcUrl。

{
  testnet: true,
  rpcUrl: "https://rsk-mainnet.g.alchemy.com/v2/YOUR_KEY", // required
  recipient: "0x...", // optional filter
  attester: "0x...", // optional filter
  schema: "0x...", // optional filter
  limit: 10 // optional, default 10
}

🏗️ 创建架构

{
  testnet: true,
  schema: "uint256 tokenId, string name", // schema definition
  revocable: true,
  resolverAddress: "0x...", // optional, defaults to zero address
  walletData: {}, // wallet configuration
  walletPassword: "password"
}

🏗️ 创建部署证明

使用 RAS 默认部署架构创建部署证明。如果未提供 schemaUID，则使用 DEFAULT_SCHEMA_UIDS.testnet.deployment。

{
  testnet: true,
  contractAddress: "0x...",
  contractName: "MyContract",
  deployer: "0x...",
  blockNumber: 1000000,
  transactionHash: "0x...",
  timestamp: 1700000000,
  abiHash: "0x...", // optional
  bytecodeHash: "0x...", // optional
  schemaUID: "0x...", // optional, uses default RAS schema
  recipient: "0x...", // optional
  walletData: {}, // wallet configuration
  walletPassword: "password"
}

✅ 创建验证证明

使用 RAS 默认验证架构创建合约验证证明。

{
  testnet: true,
  contractAddress: "0x...",
  contractName: "MyContract",
  verifier: "0x...",
  sourceCodeHash: "0x...",
  compilationTarget: "contracts/MyContract.sol:MyContract",
  compilerVersion: "v0.8.17+commit.8df45f5f",
  optimizationUsed: true,
  timestamp: 1700000000,
  verificationTool: "hardhat",
  schemaUID: "0x...", // optional, uses default RAS schema
  recipient: "0x...", // optional
  walletData: {}, // wallet configuration
  walletPassword: "password"
}

💸 创建转账证明

使用 RAS 默认转账架构创建转账证明。

{
  testnet: true,
  sender: "0x...",
  recipient: "0x...",
  amount: "0.001",
  tokenSymbol: "RBTC", // optional, defaults to RBTC
  tokenAddress: "0x...", // optional, for ERC20
  transactionHash: "0x...",
  blockNumber: 1000000,
  timestamp: 1700000000,
  transferType: "native", // e.g. "native" or "erc20"
  reason: "payment", // optional
  schemaUID: "0x...", // optional, uses default RAS schema
  walletData: {}, // wallet configuration
  walletPassword: "password"
}

📁 项目结构

rsk-mcp-server/
├── src/
│   ├── handlers/
│   │   └── responsesHandler.ts    # MCP response handling
│   ├── services/
│   │   ├── AttestationService.ts  # Attestation operations
│   │   ├── ContractDeploymentService.ts # Contract deployment
│   │   ├── ContractReadService.ts # Contract reading
│   │   ├── ContractVerificationService.ts # Contract verification
│   │   ├── HistoryService.ts      # Transaction history
│   │   ├── TransferService.ts     # Token transfers
│   │   └── WalletService.ts       # Wallet management
│   ├── tools/
│   │   ├── constants.ts           # Constants and options
│   │   ├── handlers.ts            # Auxiliary handlers
│   │   ├── schemas.ts             # Zod validation schemas
│   │   └── types.ts               # TypeScript types
│   ├── utils/
│   │   └── responses.ts           # Response utilities
│   ├── server-config.ts           # MCP server configuration
│   ├── index.ts                   # Main entry point
│   └── rsk-cli.d.ts               # Ambient type declarations for rsk-cli
├── scripts/
│   └── test-attestations.mjs      # Attestation integration tests
├── build/                         # Compiled code (generated)
├── package.json                   # Project configuration
├── tsconfig.json                  # TypeScript configuration
└── README.md                      # This documentation

🔐 安全

私钥管理

• 使用 AES-256 加密存储私钥
• 每个钱包都有唯一的 IV（初始化向量）
• 密码绝不会以明文形式存储

最佳实践

• 使用强度高且唯一的密码
• 妥善备份 my-wallets.json
• 不要共享配置文件
• 使用测试网进行测试

🐛 故障排除

错误：“Module not found”

npm install
npm run build

MCP 连接错误

• 验证配置中的绝对路径
• 确保项目已编译
• 检查 MCP 客户端日志

钱包问题

• 确认 my-wallets.json 的格式
• 检查 password.json 中的密码（如果你将密码保存在文件中）
• 确保有足够的资金用于交易

贡献

我们欢迎社区贡献。请 fork 此代码库，并提交包含更改的拉取请求。请确保你的代码符合项目的主要目标。

支持

如有任何问题或需要支持，请在代码库中提交 issue，或联系维护者。

免责声明

此 GitHub 代码库提供的软件按“原样”提供，不附带任何形式的明示或暗示保证，包括但不限于适销性、特定用途适用性和不侵权的保证。

• 测试： 此软件未经任何形式的测试，因此不保证其功能、准确性、可靠性或对任何用途的适用性。
• 使用风险自负： 用户须自行承担使用此软件所产生的所有风险。即使已被告知可能发生此类损害，此软件的作者也不对因使用或无法使用此软件而导致的任何损害承担责任，包括但不限于直接、间接、附带、特殊、后果性或惩罚性损害。
• 不承担责任： 此软件的作者不对因使用或无法使用此软件而导致的任何损失或损害承担责任，包括但不限于利润损失、业务中断、信息或数据丢失或其他金钱损失。
• 责任自负： 用户确认，自己须对使用此软件的结果承担全部责任，包括基于软件输出或功能所作的任何决策或采取的任何行动。
• 不构成认可： 提及任何特定产品、服务或组织，均不构成或暗示此软件的作者对其表示认可。
• 修改和分发： 可根据随软件提供的许可证条款修改和分发此软件。修改或分发此软件即表示你同意受许可证条款约束。
• 风险承担： 使用此软件即表示用户确认并同意，自己已阅读、理解并接受本免责声明的条款，并自行承担与使用此软件相关的所有风险。