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

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):
  Создайте новые учетные записи 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

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

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 для тестирования. Тесты организованы в модульные, интеграционные и сквозные наборы.

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

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.