Hedera MCP Server

Hedera MCP-Server (ALPHA – URSACHE FUNKTIONALITÄT IMMER NOCH DEFEKT)

Überblick

Der Hedera MCP Server ist ein produktionsreifer, modularer Node.js (TypeScript)-Server, der die dezentrale Kommunikation zwischen KI-Agenten im Hedera-Netzwerk ermöglicht. Er implementiert die Model-Context-Protocol (MCP) -Architektur und bietet sowohl eine RESTful-API als auch eine SSE-basierte (Server-Sent Events) MCP-Schnittstelle.

Durch die Verwendung des Hedera Agent Kit zusammen mit dem Standards Agent Kit unterstützt der Server mehrere Hedera Consensus Service (HCS)-Standards:

HCS-1 (Datei-/Datenverwaltung)
HCS-2 (Registrierung für Agentenerkennung)
HCS-3 (Verarbeitung großer Nachrichten und Rekursion)
HCS-10 (Agentenkommunikationsprotokoll)
HCS-11 (Dezentrales Identitäts-/Profilmanagement)

Dieser Server richtet sich insbesondere an Hackathon-Teilnehmer und Entwickler, die KI-integrierte dezentrale Anwendungen auf Hedera erstellen. Er ist außerdem mit Tools wie Cursor für autonome Agenteninteraktionen kompatibel.

Ordnerstruktur

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

Merkmale

Agentenregistrierung und -profile (HCS-11):
Erstellen Sie neue Hedera-Konten (oder importieren Sie vorhandene) für KI-Agenten. Richten Sie automatisch eingehende/ausgehende Themen und On-Chain-Profile ein.
Agentenerkennung (HCS-2):
Registrieren Sie Agenten in einem zentralen Registrierungsthema. Suchen Sie Agenten nach Namen oder Funktion mithilfe der bereitgestellten Such-API.
Sichere Kommunikation (HCS-10):
Initiieren und akzeptieren Sie Verbindungsanfragen zwischen Agenten. Richten Sie dedizierte Verbindungsthemen ein, über die Agenten sicher Nachrichten austauschen können.
Handhabung großer Nachrichten (HCS-1 und HCS-3):
Entladen Sie große Nachrichteninhalte, indem Sie sie in dedizierten Dateithemen speichern und innerhalb der Nachrichten einen HRL-Verweis (HCS Resource Locator) zurückgeben.
MCP-Schnittstelle über SSE:
Stellen Sie einen MCP-kompatiblen SSE-Endpunkt (über FastMCP ) bereit, mit dem KI-Tools wie Cursor Server-„Tools“ (z. B. register_agent, send_message) direkt aufrufen können.
RESTful-API:
Stellen Sie umfassende HTTP-Endpunkte für Agentenvorgänge, Verbindungsverwaltung und Messaging mit detaillierten Anforderungs-/Antwortformaten bereit.
Produktionsbereite Bereitstellung:
Wird mit Docker- und Docker Compose-Konfigurationen für eine nahtlose Bereitstellung mit einem Befehl geliefert.

Anforderungen

Node.js ≥ 18 (LTS empfohlen)
npm (wird mit Node geliefert)
Docker und Docker Compose (für die Containerbereitstellung)
Ein Hedera Testnet (oder Mainnet)-Konto mit ausreichend Guthaben für Transaktionen
(Legen Sie die folgenden Umgebungsvariablen fest: HEDERA_OPERATOR_ID und HEDERA_OPERATOR_KEY .)

Erste Schritte

1. Klonen Sie das Repository

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

2. Abhängigkeiten installieren

npm install

3. Umgebungsvariablen konfigurieren

Erstellen Sie im Projektstamm eine .env Datei mit dem folgenden Inhalt (passen Sie diese an Ihre tatsächlichen Anmeldeinformationen an):

# .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. Erstellen Sie das Projekt

Kompilieren Sie den TypeScript-Code in JavaScript:

npm run build

5. Führen Sie den Server lokal aus

Starten Sie die REST-API und die MCP SSE-Server:

npm start

Sie sollten Protokolle sehen, die Folgendes anzeigen:

Die REST-API lauscht auf http://localhost:3000
Der MCP SSE-Server ist verfügbar unter http://localhost:3001/sse

6. Entwicklungsmodus

Verwenden Sie für eine schnelle Entwicklung mit automatischen Neuerstellungen:

npm run dev

API-Dokumentation

Agent-Endpunkte

POST /api/agents/register
Registriert einen neuen Agenten.
Anforderungstext:
{ "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" }
Antwort (201 erstellt):
{ "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}
Ruft das Profil eines Agenten anhand der Konto-ID ab.
Antwort (200 OK):
{ "name": "AliceAgent", "inboundTopicId": "0.0.444444", "outboundTopicId": "0.0.444445", "type": 1, "capabilities": [0, 4], "model": "gpt-4", "creator": "Alice" }
GET /api/agents?name=Alice&capability=0
Suchen Sie nach Agenten nach Name und/oder Fähigkeit.
Antwort (200 OK):
[ { "name": "AliceAgent", "inboundTopicId": "0.0.444444", "outboundTopicId": "0.0.444445", "type": 1, "capabilities": [0, 4], "model": "gpt-4", "creator": "Alice" } ]

Verbindungsendpunkte

POST /api/connections/request
Initiiert eine Verbindungsanfrage an einen anderen Agenten.
Anforderungstext:
{ "fromAccount": "0.0.AAAAA", "fromPrivateKey": "302e0201...", "toAccount": "0.0.BBBBB" }
Antwort (200 OK):
{ "requestSequenceNumber": 42 }
POST /api/connections/accept
Akzeptiert eine Verbindungsanfrage und erstellt ein dediziertes Verbindungsthema.
Anforderungstext:
{ "fromAccount": "0.0.BBBBB", "fromPrivateKey": "302e0201...", "requesterAccount": "0.0.AAAAA" }
Antwort (200 OK):
{ "connectionTopicId": "0.0.CCCCC" }
GET /api/connections?accountId=0.0.AAAAA
Listet alle aktiven Verbindungen für einen bestimmten Agenten auf.
Antwort (200 OK):
[ { "peer": "0.0.BBBBB", "connectionTopicId": "0.0.CCCCC" } ]

Messaging-Endpunkte

POST /api/messages/send
Sendet eine Nachricht über eine bestehende Verbindung.
Anforderungstext:
{ "senderAccount": "0.0.AAAAA", "senderKey": "302e0201...", "connectionTopicId": "0.0.CCCCC", "message": "Hello, AgentB!" }
Antwort (200 OK):
{ "sequenceNumber": 7 }
GET /api/messages?connectionTopicId=0.0.CCCCC&limit=10
Ruft aktuelle Nachrichten aus einem Verbindungsthema ab.
Antwort (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-Schnittstelle

Der Server stellt eine MCP-Schnittstelle über SSE (Server-Sent Events) bereit, die von FastMCP unterstützt wird. Diese Schnittstelle ist verfügbar unter:

http://localhost:3001/sse

Integration mit Cursor

Führen Sie den Server aus:
Stellen Sie sicher, dass der MCP SSE-Server läuft (standardmäßig auf Port 3001). Verwenden Sie npm start oder Docker wie unten beschrieben.
Im Cursor konfigurieren:
Fügen Sie in den MCP-Einstellungen von Cursor einen neuen MCP-Server mit der folgenden URL hinzu:
http://localhost:3001/sse
Der Cursor ruft automatisch die Liste der verfügbaren Tools ab (z. B. register_agent , request_connection , send_message usw.).
Verwendung:
Sie können die KI von Cursor anweisen, mithilfe dieser Tools Aktionen auszuführen. Beispiel:
„Registrieren Sie einen neuen Agenten namens AliceAgent und verbinden Sie mich mit BobAgent.“
Der Cursor ruft die entsprechenden MCP-Tools auf, die in der SSE-Schnittstelle definiert sind.

Docker-Bereitstellung

Das Projekt wird mit einer Docker-Datei und einer Docker-Compose.yml-Datei für eine einfache Bereitstellung mit einem Befehl geliefert.

Verwenden von Docker Compose

Umgebungsvariablen sicherstellen:
Legen Sie Ihre Umgebungsvariablen in einer .env Datei im Projektstamm fest (wie oben gezeigt).
Erstellen und Ausführen:
docker-compose up --build -d
Dieser Befehl erstellt das Docker-Image und startet die Container im Detached-Modus. Die REST-API ist über Port 3000 und der MCP SSE-Server über Port 3001 erreichbar.
Bereitstellung überprüfen:
Öffnen Sie Ihren Browser oder verwenden Sie curl , um Folgendes zu überprüfen:
- Gesundheitscheck: http://localhost:3000/
- MCP SSE-Endpunkt: http://localhost:3001/sse

Testen

Ausführen der Testsuite

Das Projekt verwendet Jest zum Testen. Die Tests sind in Unit-, Integrations- und End-to-End-Suiten organisiert.

Führen Sie alle Tests mit aus:

npm test

Zu den Tests gehören:

Unit-Tests: Validieren Sie die Logik in einzelnen Diensten (z. B. Datei-Chunking in fileService.test.ts ).
Integrationstests: Testen Sie REST-API-Endpunkte mit Supertest, um korrekte Antworten sicherzustellen.
End-to-End-Tests: Simulieren Sie einen vollständigen Agenten-Kommunikationsfluss (Agentenregistrierung, Verbindung und Nachrichtenübermittlung) im Hedera-Testnetz.

Hinweis: Tests führen Live-Operationen im Hedera-Testnetz aus. Stellen Sie sicher, dass Ihre Testumgebung über ausreichende Mittel verfügt und dass Sie sich des minimalen HBAR-Verbrauchs bewusst sind.

Wartung & Optimierung

Protokollierung und Überwachung:
Der Server enthält einen Basis-Logger. Erwägen Sie in der Produktion die Integration einer robusteren Protokollierungslösung (z. B. Winston oder Pino) sowie die Einrichtung von Protokollrotation und Überwachungs-Dashboards.
Zwischenspeicherung:
Agentenprofile und Verbindungslisten werden im Speicher zwischengespeichert. Bei hoher Auslastung empfiehlt es sich, diese durch einen persistenten Speicher (z. B. Redis oder eine Datenbank) zu ersetzen.
Skalierung:
Der Server ist, abgesehen von In-Memory-Caches, zustandslos. Er kann hinter einem Load Balancer horizontal skaliert werden. Stellen Sie bei mehreren Instanzen sicher, dass sie dieselbe Registrierungskonfiguration verwenden, damit alle Agenten in der globalen Registrierung angezeigt werden.
Sicherheitsüberlegungen:
- Sichern Sie die .env Datei und geben Sie niemals private Schlüssel preis.
- Implementieren Sie für die Produktion eine ordnungsgemäße Authentifizierung/Autorisierung für API-Endpunkte.
- Erwägen Sie die Verwendung von HTTPS und anderen sicheren Kommunikationspraktiken.
Aktualisierungen zur Einhaltung von Standards:
Behalten Sie Updates für das Hedera Agent Kit und das Standards Agent Kit im Auge. Die Aktualisierung von Abhängigkeiten kann minimale Anpassungen erfordern, wenn neue Felder oder Protokolle eingeführt werden.

Beitragen

Beiträge sind willkommen! Bitte forken Sie das Repository und öffnen Sie Pull Requests mit Ihren Verbesserungen. Bei größeren Änderungen öffnen Sie bitte zunächst ein Issue, um Ihre Änderungswünsche zu besprechen.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.

Hedera MCP Server

Integrations