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 для автономных взаимодействий агентов.

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

Функции

• Регистрация и профили агентов (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) с достаточными средствами для проведения транзакций
  (Установите следующие переменные среды:

Начиная

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}
  Извлекает профиль агента по идентификатору учетной записи.
  Ответ (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 . Этот интерфейс доступен по адресу:

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

1. Запустите сервер:
   Убедитесь, что сервер MCP SSE запущен (по умолчанию на порту 3001). Используйте npm start или Docker, как описано ниже.

2. Настроить в курсоре:
   В настройках MCP курсора добавьте новый сервер MCP с URL-адресом:

   http://localhost:3001/sse

   Курсор автоматически извлечет список доступных инструментов (например, register_agent , request_connection , send_message и т. д.).

3. Использование:
   Вы можете поручить ИИ Курсора выполнять действия с помощью этих инструментов. Например, подсказка:

   «Зарегистрируйте нового агента с именем AliceAgent и соедините меня с BobAgent».
   Курсор вызовет соответствующие инструменты MCP, определенные в интерфейсе SSE.

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

• Интеграционные тесты: тестируйте конечные точки REST API с помощью Supertest, чтобы гарантировать правильные ответы.

• Сквозные тесты: смоделируйте полный поток коммуникации агентов (регистрация агентов, подключение и обмен сообщениями) в тестовой сети Hedera.

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

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

• Регистрация и мониторинг:
  Сервер включает в себя базовый регистратор. В производстве рассмотрите возможность интеграции более надежного решения для регистрации (например, Winston или Pino) и настройки ротации журналов и мониторинга панелей.

• Кэширование:
  Профили агентов и списки подключений кэшируются в памяти. Для сценариев с высокой нагрузкой рассмотрите возможность замены их на постоянное хранилище (например, Redis или базу данных).

• Масштабирование:
  Сервер не имеет состояния, за исключением кэшей в памяти. Он может быть горизонтально масштабирован за балансировщиком нагрузки. Для нескольких экземпляров убедитесь, что они используют одну и ту же конфигурацию реестра, чтобы все агенты отображались в глобальном реестре.

• Соображения безопасности:

  • Защитите файл .env и никогда не раскрывайте закрытые ключи.

  • Для производства реализуйте надлежащую аутентификацию/авторизацию для конечных точек API.

  • Рассмотрите возможность использования HTTPS и других методов безопасной связи.

• Обновления соответствия стандартам:
  Следите за обновлениями Hedera Agent Kit и Standards Agent Kit. Обновление зависимостей может потребовать минимальных корректировок, если вводятся новые поля или протоколы.

Внося вклад

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

Лицензия

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