使用说明

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

概述

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

使用 Hedera特工Kit 旁边标准试剂盒，服务器支持多种Hedera共识服务（HCS）标准：

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集成

运行服务器：
确保MCP SSE服务器正在运行（默认端口3001）。使用 npm start 或Docker，如下所述。
在游标中配置：
在Cursor的MCP设置中，使用以下URL添加新的MCP服务器：
```
http://localhost:3001/sse
```
Cursor将自动检索可用工具的列表（例如。， register_agent, request_connection, send_message等等）。
用途：
您可以指示Cursor的AI使用这些工具执行操作。例如，提示：

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

Docker部署

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

使用Docker Compose

确保环境变量：
在 .env 项目根目录中的文件（如上所示）。
构建和运行：
```
docker-compose up --build -d
```
此命令构建Docker映像并以分离模式启动容器。REST API可在端口3000上访问，MCP SSE服务器可在端口3001上访问。
验证部署：
打开浏览器或使用 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许可证获得许可。

使用说明

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

概述

文件夹结构

特性

需求

入门指南

1.克隆存储库

2.安装依赖项

3.配置环境变量

4.建设项目

5.在本地运行服务器

6.发展模式

API文档

代理端点

连接端点

消息传递端点

MCP SSE接口

与Cursor集成

Docker部署

使用Docker Compose

测试

运行测试套件

维护与优化

贡献

许可证

相关 MCP

网页抓取与搜索MCP服务器

用户名搜索MCP服务器

Jupyter笔记本MCP服务器

Claude Code开发工具包

区块链交互服务器

语言服务器协议模型上下文协议