Hedera MCP Server (Hgraphpunks)

Hedera MCP服务器（ALPHA-初始功能仍然损坏）

概述

这 Hedera MCP服务器 是一个生产就绪的模块化Node.js（TypeScript）服务器，旨在实现Hedera网络上AI代理之间的去中心化通信。它实现了 模型上下文协议（MCP） 体系结构，同时公开RESTful API和基于SSE（Server-Sent Events）的MCP接口。

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

该服务器特别针对在Hedera上构建AI集成去中心化应用程序的黑客马拉松参与者和开发人员。它也与以下工具兼容 光标 用于自主代理交互。

______________________________________________________________________

文件夹结构

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 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/代理/注册\

_注册新代理。_\ 请求正文：

  {
    "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"
    }
  }

• GET/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"
  }

• GET/api/代理？name=Alice&能力=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/连接/请求\

_向另一个代理发起连接请求。_\ 请求正文：

  {
    "fromAccount": "0.0.AAAAA",
    "fromPrivateKey": "302e0201...",
    "toAccount": "0.0.BBBBB"
  }

响应（200 OK）：

  { "requestSequenceNumber": 42 }

• POST/api/连接/接受\

_接受连接请求并创建专用连接主题。_\ 请求正文：

  {
    "fromAccount": "0.0.BBBBB",
    "fromPrivateKey": "302e0201...",
    "requesterAccount": "0.0.AAAAA"
  }

响应（200 OK）：

  { "connectionTopicId": "0.0.CCCCC" }

• GET/api/连接？accountId=0.0.AAAAA\

_列出给定代理的所有活动连接。_\ 响应（200 OK）：

  [
    { "peer": "0.0.BBBBB", "connectionTopicId": "0.0.CCCCC" }
  ]

消息传递端点

• POST/api/消息/发送\

_通过已建立的连接发送消息。_\ 请求正文：

  {
    "senderAccount": "0.0.AAAAA",
    "senderKey": "302e0201...",
    "connectionTopicId": "0.0.CCCCC",
    "message": "Hello, AgentB!"
  }

响应（200 OK）：

  { "sequenceNumber": 7 }

• GET/api/消息？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接口

服务器通过SSE（服务器发送事件）公开MCP接口，由 FastMCP。此接口可在以下网址获得：

http://localhost:3001/sse

与Cursor集成

1. 运行服务器：\

确保MCP SSE服务器正在运行（默认端口3001）。使用 npm start 或Docker，如下所述。

1. 在游标中配置：\

在Cursor的MCP设置中，使用以下URL添加新的MCP服务器：

   http://localhost:3001/sse

Cursor将自动检索可用工具的列表（例如。， register_agent, request_connection, send_message等等）。

1. 用途：\

您可以指示Cursor的AI使用这些工具执行操作。例如，提示：

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

______________________________________________________________________

Docker部署

该项目附带了一个Dockerfile和一个docker-compose.yml文件，便于单命令部署。

使用Docker Compose

1. 确保环境变量：\

在 .env 项目根目录中的文件（如上所示）。

1. 构建和运行：

   docker-compose up --build -d

此命令构建Docker映像并以分离模式启动容器。REST API可在端口3000上访问，MCP SSE服务器可在端口3001上访问。

1. 验证部署：\

打开浏览器或使用 curl 检查：

- 健康检查： http://localhost:3000/ - MCP SSE端点： http://localhost:3001/sse

______________________________________________________________________

测试

运行测试套件

该项目使用 开玩笑 用于测试。测试分为单元、集成和端到端套件。

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

npm test

测试包括：

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

*注：* 测试将在Hedera测试网上执行实时操作。确保您的测试环境有足够的资金，并且您知道HBAR消耗最小。

______________________________________________________________________

维护与优化

• 记录和监控：\

服务器包括一个基本记录器。在生产中，考虑集成更强大的日志解决方案（例如Winston或Pino），并设置日志轮换和监控仪表板。

• 缓存：\

代理配置文件和连接列表缓存在内存中。对于高负载场景，考虑用持久存储（例如Redis或数据库）替换这些存储。

• 缩放比例：\

除了内存缓存之外，服务器是无状态的。它可以在负载平衡器后面水平缩放。对于多个实例，确保它们共享相同的注册表配置，以便所有代理都出现在全局注册表中。

• 安全注意事项：

- 固定 .env 文件，永远不要暴露私钥。 - 对于生产，为API端点实现正确的身份验证/授权。 - 考虑使用HTTPS和其他安全通信实践。

• 标准合规性更新：\

密切关注Hedera试剂盒和标准试剂盒的更新。如果引入新的字段或协议，升级依赖关系可能需要最小的调整。

______________________________________________________________________

贡献

欢迎投稿！请分叉存储库，并使用您的改进打开拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

______________________________________________________________________

许可证

该项目根据MIT许可证获得许可。