Servidor MCP de Hedera

Descripción general

El servidor MCP de Hedera es un servidor Node.js (TypeScript) modular, listo para producción, diseñado para permitir la comunicación descentralizada entre agentes de IA en la red Hedera. Implementa la arquitectura Modelo-Contexto-Protocolo (MCP) , exponiendo tanto una API RESTful como una interfaz MCP basada en SSE (Eventos Enviados por el Servidor).

Al utilizar el Hedera Agent Kit junto con el Standards Agent Kit , el servidor admite varios estándares de Hedera Consensus Service (HCS):

HCS-1 (Gestión de archivos/datos)
HCS-2 (Registro para el descubrimiento de agentes)
HCS-3 (Manejo de mensajes grandes y recursión)
HCS-10 (Protocolo de comunicación del agente)
HCS-11 (Gestión descentralizada de identidades y perfiles)

Este servidor está especialmente dirigido a participantes de hackatones y desarrolladores que crean aplicaciones descentralizadas con IA integrada en Hedera. También es compatible con herramientas como Cursor para la interacción con agentes autónomos.

Estructura de carpetas

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

Características

Registro y perfiles de agentes (HCS-11):
Cree nuevas cuentas de Hedera (o importe las existentes) para agentes de IA. Configure automáticamente temas de entrada y salida y perfiles en cadena.
Descubrimiento de agentes (HCS-2):
Registre agentes en un tema de registro centralizado. Descubra agentes por nombre o capacidad mediante la API de búsqueda proporcionada.
Comunicación segura (HCS-10):
Iniciar y aceptar solicitudes de conexión entre agentes. Establecer temas de conexión dedicados a través de los cuales los agentes puedan intercambiar mensajes de forma segura.
Manejo de mensajes grandes (HCS-1 y HCS-3):
Descargue contenido de mensajes grandes almacenándolos en temas de archivos dedicados y devolviendo una referencia HRL (Localizador de recursos HCS) dentro de los mensajes.
Interfaz MCP a través de SSE:
Exponer un punto final SSE compatible con MCP (a través de FastMCP ) que permita que herramientas de IA como Cursor invoquen directamente “herramientas” del servidor (por ejemplo, register_agent, send_message).
API RESTful:
Exponga puntos finales HTTP completos para operaciones de agentes, gestión de conexiones y mensajería, con formatos detallados de solicitud/respuesta.
Implementación lista para producción:
Viene con configuraciones de Docker y Docker Compose para una implementación perfecta con un solo comando.

Requisitos

Node.js ≥ 18 (se recomienda LTS)
npm (viene con Node)
Docker y Docker Compose (para implementación de contenedores)
Una cuenta de Hedera Testnet (o Mainnet) con fondos suficientes para transacciones
(Establezca las siguientes variables de entorno: HEDERA_OPERATOR_ID y HEDERA_OPERATOR_KEY .)

Empezando

1. Clonar el repositorio

git clone https://github.com/hgraphpunks/hedera-mcp-server.git
cd hedera-mcp-server

2. Instalar dependencias

npm install

3. Configurar variables de entorno

Cree un archivo .env en la raíz del proyecto con el siguiente contenido (ajústelo con sus credenciales reales):

# .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. Construir el proyecto

Compilar el código TypeScript en JavaScript:

npm run build

5. Ejecute el servidor localmente

Inicie la API REST y los servidores SSE de MCP:

npm start

Debería ver registros que indiquen que:

La API REST está escuchando en http://localhost:3000
El servidor SSE de MCP está disponible en http://localhost:3001/sse

6. Modo de desarrollo

Para un desarrollo rápido con reconstrucciones automáticas, utilice:

npm run dev

Documentación de la API

Puntos finales del agente

POST /api/agentes/registrarse
Registra un nuevo agente.
Cuerpo de la solicitud:
{ "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" }
Respuesta (201 creados):
{ "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" } }
OBTENER /api/agents/{accountId}
Recupera el perfil de un agente por ID de cuenta.
Respuesta (200 OK):
{ "name": "AliceAgent", "inboundTopicId": "0.0.444444", "outboundTopicId": "0.0.444445", "type": 1, "capabilities": [0, 4], "model": "gpt-4", "creator": "Alice" }
OBTENER /api/agents?nombre=Alice&capacidad=0
Busque agentes por nombre y/o capacidad.
Respuesta (200 OK):
[ { "name": "AliceAgent", "inboundTopicId": "0.0.444444", "outboundTopicId": "0.0.444445", "type": 1, "capabilities": [0, 4], "model": "gpt-4", "creator": "Alice" } ]

Puntos finales de conexión

POST /api/conexiones/solicitud
Inicia una solicitud de conexión a otro agente.
Cuerpo de la solicitud:
{ "fromAccount": "0.0.AAAAA", "fromPrivateKey": "302e0201...", "toAccount": "0.0.BBBBB" }
Respuesta (200 OK):
{ "requestSequenceNumber": 42 }
POST /api/connections/accept
Acepta una solicitud de conexión y crea un tema de conexión dedicado.
Cuerpo de la solicitud:
{ "fromAccount": "0.0.BBBBB", "fromPrivateKey": "302e0201...", "requesterAccount": "0.0.AAAAA" }
Respuesta (200 OK):
{ "connectionTopicId": "0.0.CCCCC" }
OBTENER /api/connections?accountId=0.0.AAAAA
Enumera todas las conexiones activas para un agente determinado.
Respuesta (200 OK):
[ { "peer": "0.0.BBBBB", "connectionTopicId": "0.0.CCCCC" } ]

Puntos finales de mensajería

POST /api/mensajes/enviar
Envía un mensaje a través de una conexión establecida.
Cuerpo de la solicitud:
{ "senderAccount": "0.0.AAAAA", "senderKey": "302e0201...", "connectionTopicId": "0.0.CCCCC", "message": "Hello, AgentB!" }
Respuesta (200 OK):
{ "sequenceNumber": 7 }
OBTENER /api/messages?connectionTopicId=0.0.CCCCC&limit=10
Recupera mensajes recientes de un tema de conexión.
Respuesta (200 OK):
{ "messages": [ "{\"p\":\"hcs-10\",\"op\":\"message\",\"operator_id\":\"0.0.444444@0.0.AAAAA\",\"data\":\"Hello, AgentB!\",\"m\":\"Message from agent.\"}" ] }

Interfaz MCP SSE

El servidor expone una interfaz MCP mediante SSE (Eventos enviados por el servidor) con tecnología FastMCP . Esta interfaz está disponible en:

http://localhost:3001/sse

Integración con Cursor

Ejecutar el servidor:
Asegúrese de que el servidor MCP SSE esté en ejecución (el puerto predeterminado es el 3001). Use npm start o Docker como se describe a continuación.
Configurar en Cursor:
En la configuración de MCP de Cursor, agregue un nuevo servidor MCP con la URL:
http://localhost:3001/sse
El cursor recuperará automáticamente la lista de herramientas disponibles (por ejemplo, register_agent , request_connection , send_message , etc.).
Uso:
Puedes indicarle a la IA de Cursor que realice acciones con estas herramientas. Por ejemplo, indica:
"Registra un nuevo agente llamado AliceAgent y conéctame con BobAgent".
El cursor llamará a las respectivas herramientas MCP definidas en la interfaz SSE.

Implementación de Docker

El proyecto viene con un Dockerfile y un archivo docker-compose.yml para una fácil implementación con un solo comando.

Uso de Docker Compose

Asegurar las variables de entorno:
Establezca sus variables de entorno en un archivo .env en la raíz del proyecto (como se muestra arriba).
Construir y ejecutar:
docker-compose up --build -d
Este comando crea la imagen de Docker e inicia los contenedores en modo independiente. La API REST estará disponible en el puerto 3000 y el servidor SSE de MCP en el puerto 3001.
Verificar la implementación:
Abra su navegador o utilice curl para comprobarlo:
- Comprobación del estado: http://localhost:3000/
- Punto final SSE de MCP: http://localhost:3001/sse

Pruebas

Ejecución del conjunto de pruebas

El proyecto utiliza Jest para las pruebas. Las pruebas se organizan en suites unitarias, de integración y de extremo a extremo.

Ejecute todas las pruebas con:

npm test

Las pruebas incluyen:

Pruebas unitarias: validar la lógica en servicios individuales (por ejemplo, fragmentación de archivos en fileService.test.ts ).
Pruebas de integración: pruebe los puntos finales de la API REST utilizando Supertest para garantizar respuestas adecuadas.
Pruebas de extremo a extremo: simule un flujo de comunicación completo del agente (registro del agente, conexión y mensajería) en Hedera Testnet.

Nota: Las pruebas se ejecutarán en vivo en la red de pruebas de Hedera. Asegúrese de que su entorno de pruebas tenga fondos suficientes y de que el consumo de HBAR sea mínimo.

Mantenimiento y optimización

Registro y monitoreo:
El servidor incluye un registrador básico. En producción, considere integrar una solución de registro más robusta (p. ej., Winston o Pino) y configurar paneles de rotación y monitorización de registros.
Almacenamiento en caché:
Los perfiles de agente y las listas de conexiones se almacenan en caché. En situaciones de alta carga, considere reemplazarlos con un almacenamiento persistente (por ejemplo, Redis o una base de datos).
Escalada:
El servidor no tiene estado, salvo por las cachés en memoria. Se puede escalar horizontalmente con un balanceador de carga. Para varias instancias, asegúrese de que compartan la misma configuración de registro para que todos los agentes aparezcan en el registro global.
Consideraciones de seguridad:
- Proteja el archivo .env y nunca exponga claves privadas.
- Para la producción, implemente la autenticación/autorización adecuada para los puntos finales de API.
- Considere utilizar HTTPS y otras prácticas de comunicación seguras.
Actualizaciones de cumplimiento de normas:
Manténgase al tanto de las actualizaciones del Kit de Agente de Hedera y del Kit de Agente de Estándares. Actualizar las dependencias puede requerir ajustes mínimos si se introducen nuevos campos o protocolos.

Contribuyendo

¡Agradecemos sus contribuciones! Por favor, bifurquen el repositorio y abran solicitudes de incorporación de cambios con sus mejoras. Para cambios importantes, primero abran una incidencia para comentar qué desean cambiar.

Licencia

Este proyecto está licenciado bajo la licencia MIT.

Hedera MCP Server

Integrations