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等工具，用于自主代理交互。

Related MCP server: HashPilot

文件夹结构

hedera-mcp-server/
├── src/
│   ├── config/
│   │   └── config.ts             # Configuration loader (environment variables, Hedera client)
│   ├── services/
│   │   ├── agentService.ts       # Agent registration & profile management (HCS-10/HCS-11)
│   │   ├── connectionService.ts  # Connection request, acceptance & messaging (HCS-10)
│   │   ├── fileService.ts        # File storage for large messages (HCS-1 & HCS-3)
│   │   ├── logger.ts             # Logging utility
│   │   └── profileUtil.ts        # Helper for serializing agent profiles
│   ├── routes/
│   │   ├── agentRoutes.ts        # API endpoints for agent registration & query
│   │   ├── connectionRoutes.ts   # API endpoints for connection and messaging
│   │   └── index.ts              # Route aggregator for the REST API
│   ├── mcp/
│   │   └── mcpServer.ts          # MCP server (SSE interface) definition using FastMCP and Zod
│   └── index.ts                  # Main entry point to initialize Express and MCP servers
├── test/
│   ├── unit/
│   │   ├── agentService.test.ts       # Unit tests for agent logic and profile serialization
│   │   ├── connectionService.test.ts  # Unit tests for connection and message formatting
│   │   └── fileService.test.ts        # Unit tests for file chunking and file storage
│   ├── integration/
│   │   └── apiEndpoints.test.ts       # Integration tests for REST API endpoints
│   └── e2e/
│       └── agentCommunication.e2e.ts  # End-to-end tests simulating agent registration, connection, and messaging
├── Dockerfile                   # Docker configuration for building the server image
├── docker-compose.yml           # One-command deployment configuration for Docker
├── package.json                 # Project metadata and scripts
└── README.md                    # This file

特征

• 代理人注册及简介（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.克隆存储库

git clone https://github.com/hgraphpunks/hedera-mcp-server.git
cd hedera-mcp-server

2.安装依赖项

npm install

3.配置环境变量

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

# .env
HEDERA_NETWORK=testnet
HEDERA_OPERATOR_ID=0.0.12345
HEDERA_OPERATOR_KEY=302e0201...
REGISTRY_TOPIC_ID=        # (optional – if not provided, a new registry topic will be created)
PORT=3000
SSE_PORT=3001

4. 构建项目

将 TypeScript 代码编译为 JavaScript：

npm run build

5. 本地运行服务器

启动 REST API 和 MCP SSE 服务器：

npm start

您应该会看到以下日志：

• REST API 正在监听http://localhost:3000

• MCP SSE 服务器地址为http://localhost:3001/sse

6.开发模式

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

npm run dev

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 接口。该接口位于：

http://localhost:3001/sse

与 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进行测试。测试分为单元、集成和端到端套件。

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

npm test

测试包括：

• **单元测试：**验证各个服务中的逻辑（例如， 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 许可。