Сервер Hedera MCP

Hedera MCP Server (АЛЬФА-ВЕРСИЯ - НАЧАЛЬНАЯ ФУНКЦИОНАЛЬНОСТЬ ВСЕ ЕЩЕ НЕ РАБОТАЕТ)

Обзор

Hedera MCP Server — это готовый к производству модульный сервер Node.js (TypeScript), разработанный для обеспечения децентрализованной связи между агентами ИИ в сети Hedera. Он реализует архитектуру Model-Context-Protocol (MCP) , предоставляя как RESTful API, так и основанный на SSE (Server-Sent Events) интерфейс MCP.

Используя Hedera Agent Kit вместе с Standards Agent Kit , сервер поддерживает несколько стандартов Hedera Consensus Service (HCS):

HCS-1 (Управление файлами/данными)
HCS-2 (Реестр для обнаружения агентов)
HCS-3 (Обработка больших сообщений и рекурсия)
HCS-10 (протокол связи агентов)
HCS-11 (децентрализованное управление идентификацией/профилем)

Этот сервер специально предназначен для участников хакатона и разработчиков, создающих интегрированные с ИИ децентрализованные приложения на Hedera. Он также совместим с такими инструментами, как Cursor для автономных взаимодействий агентов.

Структура папки

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):
Создайте новые учетные записи Hedera (или импортируйте существующие) для агентов ИИ. Автоматически настройте входящие/исходящие темы и профили в цепочке.
Агент обнаружения (HCS-2):
Регистрация агентов в централизованной теме реестра. Найдите агентов по имени или возможностям, используя предоставленный API поиска.
Безопасная связь (HCS-10):
Инициировать и принимать запросы на соединение между агентами. Установить выделенные темы соединения, по которым агенты могут безопасно обмениваться сообщениями.
Обработка больших сообщений (HCS-1 и HCS-3):
Разгружайте большой объем содержимого сообщений, сохраняя его в отдельных темах файлов и возвращая ссылку HRL (HCS Resource Locator) в сообщениях.
Интерфейс MCP через SSE:
Предоставьте конечную точку SSE, совместимую с MCP (через FastMCP ), которая позволит инструментам ИИ, таким как Cursor, напрямую вызывать «инструменты» сервера (например, register_agent, send_message).
API-интерфейс RESTful:
Предоставляйте комплексные конечные точки HTTP для операций агентов, управления соединениями и обмена сообщениями с подробными форматами запросов/ответов.
Готовое к производству развертывание:
Поставляется с конфигурациями Docker и Docker Compose для бесперебойного развертывания одной командой.

Требования

Node.js ≥ 18 (рекомендуется LTS)
npm (входит в состав Node)
Docker и Docker Compose (для развертывания контейнеров)
Счет Hedera Testnet (или Mainnet) с достаточными средствами для проведения транзакций
(Установите следующие переменные среды: 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}
Извлекает профиль агента по идентификатору учетной записи.
Ответ (200 ОК):
{ "name": "AliceAgent", "inboundTopicId": "0.0.444444", "outboundTopicId": "0.0.444445", "type": 1, "capabilities": [0, 4], "model": "gpt-4", "creator": "Alice" }
GET /api/agents?name=Алиса&capability=0
Поиск агентов по имени и/или возможностям.
Ответ (200 ОК):
[ { "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 ОК):
{ "requestSequenceNumber": 42 }
POST /api/connections/принять
Принимает запрос на подключение и создает специальную тему подключения.
Текст запроса:
{ "fromAccount": "0.0.BBBBB", "fromPrivateKey": "302e0201...", "requesterAccount": "0.0.AAAAA" }
Ответ (200 ОК):
{ "connectionTopicId": "0.0.CCCCC" }
ПОЛУЧИТЬ /api/connections?accountId=0.0.AAAAA
Перечисляет все активные соединения для данного агента.
Ответ (200 ОК):
[ { "peer": "0.0.BBBBB", "connectionTopicId": "0.0.CCCCC" } ]

Конечные точки обмена сообщениями

ОТПРАВИТЬ /api/сообщения/отправить
Отправляет сообщение по установленному соединению.
Текст запроса:
{ "senderAccount": "0.0.AAAAA", "senderKey": "302e0201...", "connectionTopicId": "0.0.CCCCC", "message": "Hello, AgentB!" }
Ответ (200 ОК):
{ "sequenceNumber": 7 }
ПОЛУЧИТЬ /api/messages?connectionTopicId=0.0.CCCCC&limit=10
Извлекает последние сообщения из темы подключения.
Ответ (200 ОК):
{ "messages": [ "{\"p\":\"hcs-10\",\"op\":\"message\",\"operator_id\":\"0.0.444444@0.0.AAAAA\",\"data\":\"Hello, AgentB!\",\"m\":\"Message from agent.\"}" ] }

Интерфейс MCP SSE

Сервер предоставляет интерфейс MCP через SSE (Server-Sent Events) на базе FastMCP . Этот интерфейс доступен по адресу:

http://localhost:3001/sse

Интеграция с курсором

Запустите сервер:
Убедитесь, что сервер MCP SSE запущен (по умолчанию на порту 3001). Используйте npm start или Docker, как описано ниже.
Настроить в курсоре:
В настройках MCP курсора добавьте новый сервер MCP с URL-адресом:
http://localhost:3001/sse
Курсор автоматически извлечет список доступных инструментов (например, register_agent , request_connection , send_message и т. д.).
Использование:
Вы можете поручить ИИ Курсора выполнять действия с помощью этих инструментов. Например, подсказка:
«Зарегистрируйте нового агента с именем AliceAgent и соедините меня с BobAgent».
Курсор вызовет соответствующие инструменты MCP, определенные в интерфейсе SSE.

Развертывание 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

Тестирование

Запуск тестового набора

Проект использует Jest для тестирования. Тесты организованы в модульные, интеграционные и сквозные наборы.

Запустите все тесты с помощью:

npm test

Тесты включают в себя:

Модульные тесты: проверка логики в отдельных службах (например, разбиение файлов на фрагменты в fileService.test.ts ).
Интеграционные тесты: тестируйте конечные точки REST API с помощью Supertest, чтобы гарантировать правильные ответы.
Сквозные тесты: смоделируйте полный поток коммуникации агентов (регистрация агентов, подключение и обмен сообщениями) в тестовой сети Hedera.

Примечание: Тесты будут выполнять живые операции на Hedera Testnet. Убедитесь, что в вашей тестовой среде достаточно средств и что вы знаете о минимальном потреблении HBAR.

Техническое обслуживание и оптимизация

Регистрация и мониторинг:
Сервер включает в себя базовый регистратор. В производстве рассмотрите возможность интеграции более надежного решения для регистрации (например, Winston или Pino) и настройки ротации журналов и мониторинга панелей.
Кэширование:
Профили агентов и списки подключений кэшируются в памяти. Для сценариев с высокой нагрузкой рассмотрите возможность замены их на постоянное хранилище (например, Redis или базу данных).
Масштабирование:
Сервер не имеет состояния, за исключением кэшей в памяти. Он может быть горизонтально масштабирован за балансировщиком нагрузки. Для нескольких экземпляров убедитесь, что они используют одну и ту же конфигурацию реестра, чтобы все агенты отображались в глобальном реестре.
Соображения безопасности:
- Защитите файл .env и никогда не раскрывайте закрытые ключи.
- Для производства реализуйте надлежащую аутентификацию/авторизацию для конечных точек API.
- Рассмотрите возможность использования HTTPS и других методов безопасной связи.
Обновления соответствия стандартам:
Следите за обновлениями Hedera Agent Kit и Standards Agent Kit. Обновление зависимостей может потребовать минимальных корректировок, если вводятся новые поля или протоколы.

Внося вклад

Вклады приветствуются! Пожалуйста, разветвите репозиторий и откройте запросы на извлечение с вашими улучшениями. Для крупных изменений, пожалуйста, сначала откройте вопрос, чтобы обсудить, что вы хотели бы изменить.

Лицензия

Данный проект лицензирован по лицензии MIT.

Hedera MCP Server

Integrations