区块链交互服务器

ResilientDB MCP服务器

用于与高性能区块链平台ResilientDB交互的模型上下文协议（MCP）服务器。该服务器允许像Claude这样的大型语言模型（LLM）通过GraphQL查询和HTTPRESTneneneba API与ResilietDB交互。

概述

此MCP服务器通过提供以下标准化接口弥合了AI代理（如Claude Desktop）和ResilientDB之间的差距：

• GraphQL操作：区块链上的资产交易（端口8000）
• HTTP REST API操作：键值存储操作（端口18000-Crow服务器）

注： 中期而言，此实现侧重于GraphQL和HTTPRESTneneneba API集成。智能合约操作（ResContract CLI）暂时禁用。

特性

GraphQL操作（端口8000）

• createAccount：在ResilientDB中创建新帐户（如果支持）
• getTransaction：按ID检索资产交易详细信息（区块链交易）
• postTransaction：将新的资产交易发布到区块链（需要带有加密密钥的PrepareAsset）
• updateTransaction：更新现有交易（注意：区块链交易通常是不可变的）

键-值操作（端口18000-HTTP REST API）

• get：使用HTTP REST API按键检索值（Crow服务器）
• set：使用HTTP REST API存储密钥-值对（Crow服务器）

注： 对于中期，智能合约操作（编译、部署、执行）将被临时删除。重点是GraphQL和HTTPRESTneneneba API集成。

重要架构说明：

• GraphQL（端口8000）：用于区块链资产交易
• HTTP/Crow（端口18000）：用于键值操作

安装

先决条件

• Python 3.11或更高版本
• ResilientDB实例正在运行（请参阅 ResilientDB安装)
• 已安装ResContract CLI（用于智能合约操作）
• 访问ResilientDB GraphQL端点

本地安装

1. 克隆存储库：

git clone https://github.com/rahulkanagaraj786/ResilientDB-MCP.git
cd ResilientDB-MCP

2. 安装依赖项：

pip install -r requirements.txt

3. 配置环境变量：

cp .env.example .env
# Edit .env with your ResilientDB configuration

4. 更新 .env 使用您的设置文件：

RESILIENTDB_GRAPHQL_URL=http://localhost:8000/graphql
RESILIENTDB_HTTP_URL=http://localhost:18000

Docker安装

1. 构建Docker镜像：

docker build -t mcp/resilientdb -f Dockerfile .

2. 运行容器：

docker run -i --rm mcp/resilientdb

配置

环境变量

重要提示：

• GraphQL（端口8000）用于 资产交易 （区块链）
• HTTP/Crow（端口18000）用于 关键价值操作 （简单存储）

使用Claude Desktop

将MCP服务器添加到您的Claude Desktop配置中：

1. 打开克劳德桌面设置
2. 编辑MCP服务器配置文件（通常 claude_desktop.json)
3. 添加以下配置：

对于本地安装：

{
  "mcpServers": {
    "resilientdb": {
      "command": "python",
      "args": ["/path/to/ResilientDB-MCP/server.py"],
      "env": {
        "RESILIENTDB_GRAPHQL_URL": "http://localhost:8000/graphql",
        "RESILIENTDB_HTTP_URL": "http://localhost:18000"
      }
    }
  }
}

对于Docker安装：

{
  "mcpServers": {
    "resilientdb": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/resilientdb"]
    }
  }
}

4. 重新启动克劳德桌面

可用工具

创建帐户

在ResilientDB中创建新帐户。

参数：

• accountId （可选）：帐户ID。如果没有提供，服务器将生成一个。

例子：

{
  "accountId": "my-account-123"
}

getTransaction

通过事务ID（GraphQL-端口8000）获取资产事务详细信息。

参数：

• transactionId （必填）：要检索的交易ID

例子：

{
  "transactionId": "tx-123456"
}

注： 这是针对区块链资产交易，而不是KV交易。

交易后

将新的资产交易发布到ResilientDB（GraphQL-端口8000）。

参数：

• data （必填）：预付资产格式的交易数据，带有加密密钥和签名

例子：

{
  "data": {
    "operation": "CREATE",
    "asset": {
      "data": {...}
    },
    "outputs": [...],
    "inputs": [...]
  }
}

注： 这需要带有加密密钥的PrepareAsset格式。对于简单的KV操作，请使用 set 工具代替。

左

更新现有交易。

参数：

• transactionId （必填）：要更新的交易ID
• data （必填）：更新交易数据

例子：

{
  "transactionId": "tx-123456",
  "data": {
    "status": "completed"
  }
}

得到

通过键（HTTP REST API-端口18000）从ResilietDB检索值。

参数：

• key （必填）：要检索的密钥

例子：

{
  "key": "my-key"
}

注： 这使用HTTP REST API（Crow服务器在18000端口上）。

集

在弹性数据库（HTTP REST API-端口18000）中存储一个密钥-值对。

参数：

• key （必填）：存储密钥
• value （必填）：要存储的值（可以是任何JSON可序列化值）

例子：

{
  "key": "my-key",
  "value": "my-value"
}

注： 这使用HTTP REST API（Crow服务器在18000端口上）。

建筑

MCP服务器充当MCP主机（Claude Desktop）和ResilientDB后端服务之间的中介：

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│ Claude      │────────▶│ MCP Server   │────────▶│ ResilientDB │
│ Desktop     │         │ (Python)     │         │ Backend     │
└─────────────┘         └──────────────┘         └─────────────┘
                              │
                              ├──▶ GraphQL Client (port 8000)
                              │    (Asset Transactions only)
                              │
                              └──▶ HTTP REST Client (port 18000)
                                   (Key-Value Operations)

路由逻辑

服务器会自动将请求路由到相应的服务：

• 资产交易 → GraphQL API（端口8000）

  • getTransaction：检索资产交易记录
  • postTransaction：资产交易后（需要预付资产）
  • createAccount：创建帐户（如果支持）
  • updateTransaction：更新交易记录（如果支持）

• 关键价值操作 → HTTP REST API（端口18000-Crow服务器）

  • get：检索键值对
  • set：存储键值对

重要提示： KV操作使用HTTP REST API（端口18000）。

发展

项目结构

ResilientDB-MCP/
├── server.py              # Main MCP server implementation
├── graphql_client.py      # GraphQL client for ResilientDB
├── rescontract_client.py  # ResContract CLI client
├── config.py              # Configuration management
├── requirements.txt       # Python dependencies
├── Dockerfile             # Docker configuration
└── README.md              # This file

运行测试

# Install test dependencies
pip install pytest pytest-asyncio

# Run tests
pytest

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 提交拉取请求

故障排除

找不到ResContract CLI

如果您收到关于找不到ResContract CLI的错误：

1. 确保已安装ResContract CLI
2. 将其添加到您的路径中，或
3. 集 RESCONTRACT_CLI_PATH 将环境变量转换为完整路径

GraphQL连接错误

如果遇到GraphQL连接错误：

1. 验证ResilientDB是否正在运行
2. 检查 RESILIENTDB_GRAPHQL_URL 正确（应该是端口8000，而不是9000）
3. 确保与GraphQL端点的网络连接
4. 检查防火墙设置
5. 验证GraphQL服务器是否可访问： curl http://localhost:8000/graphql

HTTP连接错误

如果您在KV操作中遇到HTTP连接错误：

1. 验证Crow HTTP服务器是否在端口18000上运行
2. 检查 RESILIENTDB_HTTP_URL 是正确的
3. 测试HTTP端点： curl http://localhost:18000/v1/transactions/test
4. 确保HTTP服务器可访问

关键价值操作不起作用

如果KV操作（获取/设置）失败：

1. 验证您使用的是HTTP REST API（端口18000），而不是GraphQL
2. 检查Crow HTTP服务器是否正在运行
3. 卷曲测试：
   复制

   # Set a value
   curl -X POST -d '{"id":"test","value":"hello"}' http://localhost:18000/v1/transactions/commit
   
   # Get a value
   curl http://localhost:18000/v1/transactions/test
   

4. 验证HTTP REST API（端口18000）是否可用于KV操作

交易超时

如果事务超时：

1. 增加 REQUEST_TIMEOUT 在 .env
2. 检查ResilientDB区块链状态
3. 验证网络延迟

关键架构见解

服务分离

ResilientDB为不同的操作使用不同的服务：

1. GraphQL服务器（端口8000）

   • 目的：区块链资产交易
   • 操作： getTransaction, postTransaction （含预付资产）

2. HTTP/Crow服务器（端口18000）

   • 用途：简单的键值存储
   • 操作： get, set （通过REST API）
   • 终点：
     • POST /v1/transactions/commit （用于套装）
     • GET /v1/transactions/{key} （获取）

为什么这很重要

• KV操作使用HTTP REST API （18000端口） set/get 运营
• 资产交易使用GraphQL （端口8000），需要PrepareAsset格式
• 端口号错误 （例如，9000而不是8000）将导致连接错误

参考文献

• 弹性数据库 GitHub
• ResilientDB文档
• 弹性DB GraphQL API
• ResilientDB快速入门
• MCP协议文件

许可证

Apache 2.0许可证

作者

团队10-ECS 265项目