Hedera MCP Server

Hedera MCP 服务器

概述

Hedera MCP 服务器是一个可立即投入生产的模块化 Node.js（TypeScript）服务器，旨在实现 Hedera 网络上 AI 代理之间的去中心化通信。它实现了**模型-上下文-协议 (MCP)**架构，并公开了 RESTful API 和基于 SSE（服务器发送事件）的 MCP 接口。

通过使用Hedera 代理套件和标准代理套件，该服务器支持多种 Hedera 共识服务 (HCS) 标准：

• HCS-1（文件/数据管理）
• HCS-2（代理发现注册表）
• HCS-3（大消息处理和递归）
• HCS-10（代理通信协议）
• HCS-11（去中心化身份/配置文件管理）

该服务器专门面向黑客马拉松参赛者和在 Hedera 上构建集成 AI 的去中心化应用程序的开发者。它还兼容Cursor等工具，用于自主代理交互。

文件夹结构

特征

• 代理人注册及简介（HCS-11）：
  为 AI 代理创建新的 Hedera 帐户（或导入现有帐户）。自动设置入站/出站主题和链上配置文件。
• 代理发现（HCS-2）：
  在集中式注册主题中注册代理。使用提供的搜索 API，按名称或功能查找代理。
• 安全通信（HCS-10）：
  发起并接受代理之间的连接请求。建立专用的连接主题，以便代理可以安全地交换消息。
• 大消息处理（HCS-1 和 HCS-3）：
  通过将大型消息内容存储在专用文件主题中并在消息中返回 HRL（HCS 资源定位器）引用来卸载大型消息内容。
• 通过 SSE 的 MCP 接口：
  公开一个符合 MCP 的 SSE 端点（通过FastMCP ），让 Cursor 等 AI 工具直接调用服务器“工具”（例如，register_agent、send_message）。
• RESTful API：
  通过详细的请求/响应格式，公开代理操作、连接管理和消息传递的综合 HTTP 端点。
• 生产就绪部署：
  配备 Docker 和 Docker Compose 配置，可实现无缝的单命令部署。

要求

• Node.js ≥ 18（建议使用 LTS）
• npm （Node 附带）
• Docker和Docker Compose （用于容器部署）
• 具有足够资金用于交易的 Hedera 测试网（或主网）账户
  （设置以下环境变量： HEDERA_OPERATOR_ID和HEDERA_OPERATOR_KEY 。）

入门

1.克隆存储库

2.安装依赖项

3.配置环境变量

在项目根目录中创建一个.env文件，其中包含以下内容（根据您的实际凭据进行调整）：

4. 构建项目

将 TypeScript 代码编译为 JavaScript：

5. 本地运行服务器

启动 REST API 和 MCP SSE 服务器：

您应该会看到以下日志：

• REST API 正在监听http://localhost:3000
• MCP SSE 服务器地址为http://localhost:3001/sse

6.开发模式

为了通过自动重建进行快速开发，请使用：

API 文档

代理端点

• POST /api/agents/register
  注册新的代理。
  请求正文：
  { "name": "AliceAgent", "accountId": "0.0.ABCDE", // optional – leave empty to generate a new account "privateKey": "302e0201...", // optional – required if accountId is provided "capabilities": [0, 4], "model": "gpt-4", "creator": "Alice" }
  响应（201 创建）：
  { "accountId": "0.0.789123", "privateKey": "302e0201... (if new)", "profile": { "name": "AliceAgent", "inboundTopicId": "0.0.444444", "outboundTopicId": "0.0.444445", "type": 1, "capabilities": [0, 4], "model": "gpt-4", "creator": "Alice" } }
• 获取/api/agents/{accountId}
  通过帐户 ID 检索代理的个人资料。
  响应（200 OK）：
  { "name": "AliceAgent", "inboundTopicId": "0.0.444444", "outboundTopicId": "0.0.444445", "type": 1, "capabilities": [0, 4], "model": "gpt-4", "creator": "Alice" }
• 获取 /api/agents?name=Alice&capability=0
  按姓名和/或能力搜索代理。
  响应（200 OK）：
  [ { "name": "AliceAgent", "inboundTopicId": "0.0.444444", "outboundTopicId": "0.0.444445", "type": 1, "capabilities": [0, 4], "model": "gpt-4", "creator": "Alice" } ]

连接端点

• POST /api/connections/请求
  向另一个代理发起连接请求。
  请求正文：
  { "fromAccount": "0.0.AAAAA", "fromPrivateKey": "302e0201...", "toAccount": "0.0.BBBBB" }
  响应（200 OK）：
  { "requestSequenceNumber": 42 }
• POST /api/connections/accept
  接受连接请求并创建专用连接主题。
  请求正文：
  { "fromAccount": "0.0.BBBBB", "fromPrivateKey": "302e0201...", "requesterAccount": "0.0.AAAAA" }
  响应（200 OK）：
  { "connectionTopicId": "0.0.CCCCC" }
• 获取/api/connections?accountId=0.0.AAAAA
  列出给定代理的所有活动连接。
  响应（200 OK）：
  [ { "peer": "0.0.BBBBB", "connectionTopicId": "0.0.CCCCC" } ]

消息传递端点

• POST /api/messages/send
  通过已建立的连接发送消息。
  请求正文：
  { "senderAccount": "0.0.AAAAA", "senderKey": "302e0201...", "connectionTopicId": "0.0.CCCCC", "message": "Hello, AgentB!" }
  响应（200 OK）：
  { "sequenceNumber": 7 }
• 获取 /api/messages?connectionTopicId=0.0.CCCCC&limit=10
  从连接主题检索最新消息。
  响应（200 OK）：
  { "messages": [ "{\"p\":\"hcs-10\",\"op\":\"message\",\"operator_id\":\"0.0.444444@0.0.AAAAA\",\"data\":\"Hello, AgentB!\",\"m\":\"Message from agent.\"}" ] }

MCP SSE 接口

服务器通过FastMCP支持的 SSE (Server-Sent Events) 公开了一个 MCP 接口。该接口位于：

与 Cursor 集成

1. 运行服务器：
   确保 MCP SSE 服务器正在运行（默认端口 3001）。使用npm start或 Docker 启动，具体方法如下。
2. 在游标中配置：
   在 Cursor 的 MCP 设置中，添加一个新的 MCP 服务器，其 URL 为：
   http://localhost:3001/sse
   Cursor 将自动检索可用工具的列表（例如， register_agent 、 request_connection 、 send_message等）。
3. 用法：
   你可以使用这些工具来指示 Cursor 的 AI 执行操作。例如，提示：

   “注册一个名为 AliceAgent 的新代理并将我连接到 BobAgent。”
   Cursor 将调用 SSE 接口中定义的各个 MCP 工具。

Docker 部署

该项目附带一个 Dockerfile 和一个 docker-compose.yml 文件，可轻松进行单命令部署。

使用 Docker Compose

1. 确保环境变量：
   在项目根目录中的.env文件中设置环境变量（如上所示）。
2. 构建并运行：
   docker-compose up --build -d
   此命令将构建 Docker 镜像并以分离模式启动容器。REST API 将通过端口 3000 访问，MCP SSE 服务器将通过端口 3001 访问。
3. 验证部署：
   打开浏览器或者使用curl检查：
   • 健康检查： http://localhost:3000/
   • MCP SSE 端点： http://localhost:3001/sse

测试

运行测试套件

该项目使用Jest进行测试。测试分为单元、集成和端到端套件。

使用以下命令运行所有测试：

测试包括：

• **单元测试：**验证各个服务中的逻辑（例如， fileService.test.ts中的文件分块）。
• **集成测试：**使用 Supertest 测试 REST API 端点以确保正确的响应。
• **端到端测试：**在 Hedera 测试网上模拟完整的代理通信流程（代理注册、连接和消息传递）。

*注意：*测试将在 Hedera 测试网上进行实时操作。请确保您的测试环境拥有充足的资金，并了解最低 HBAR 消耗。

维护与优化

• 日志记录和监控：
  该服务器包含一个基本的日志记录器。在生产环境中，可以考虑集成更强大的日志记录解决方案（例如 Winston 或 Pino），并设置日志轮换和监控仪表板。
• 缓存：
  代理配置文件和连接列表缓存在内存中。对于高负载场景，可以考虑使用持久化存储（例如 Redis 或数据库）来替换它们。
• 缩放：
  除内存缓存外，服务器是无状态的。它可以在负载均衡器后进行水平扩展。对于多个实例，请确保它们共享相同的注册表配置，以便所有代理都出现在全局注册表中。
• 安全注意事项：
  • 保护.env文件，切勿泄露私钥。
  • 对于生产，请为 API 端点实施适当的身份验证/授权。
  • 考虑使用 HTTPS 和其他安全通信实践。
• 标准合规性更新：
  请密切关注 Hedera Agent Kit 和 Standards Agent Kit 的更新。如果引入新的字段或协议，升级依赖项可能需要进行少量调整。

贡献

欢迎贡献代码！请 fork 代码库并提交 Pull Request 以包含您的改进内容。对于重大更改，请先提交 Issue 讨论您想要修改的内容。

执照

该项目已获得 MIT 许可。