mcp-graphql-enhanced

Ein erweiterter MCP-Server (Model Context Protocol) für GraphQL, der reale Interoperabilitätsprobleme zwischen LLMs und GraphQL-APIs behebt.

Drop-in-Ersatz für mcp-graphql — mit dynamischen Headern, robuster Variablen-Analyse und ohne Breaking Changes.

💬 Community & Support

Schließen Sie sich der Unterhaltung an! Wenn Sie Fragen zur Verwendung dieser Brücke mit Neo4j, Discord-Datengraphen oder GraphQL im Allgemeinen haben, kommen Sie vorbei:

• Discord-Kanal: #mcp-graphql-enhanced

• Server: Der offizielle GraphQL Discord

Dies ist der beste Ort, um Ihr Feedback zu teilen, Probleme zu melden oder neue „erweiterte“ Funktionen für die Brücke vorzuschlagen.

Related MCP server: mcp-graphql-schema

✨ Wichtige Erweiterungen

• ✅ Integrierte GraphiQL-IDE — Visuelle Spielwiese unter http://localhost:MCP_PORT/ (oder /graphiql) mit vorkonfigurierten Headern.

• ✅ Dualer Transport — Unterstützt sowohl STDIO (für lokale CLI/Client-Tools) als auch HTTP/JSON-RPC (für externe/Browser-Clients).

• ✅ Dynamische Header — Übergeben Sie Authorization, X-API-Key usw. über Tool-Argumente (kein Neustart der Konfiguration erforderlich)

• ✅ Robuste Variablen-Analyse — behebt den Fehler “Query variables must be a null or an object”

• ✅ Gefilterte Introspektion — fordern Sie nur bestimmte Typen an (z. B. typeNames: ["Query", "User"]), um das Rauschen im LLM-Kontext zu reduzieren

• ✅ Volle MCP-Kompatibilität — funktioniert mit Claude Desktop, Cursor, Glama

• ✅ Standardmäßig sicher — Mutationen sind deaktiviert, sofern sie nicht explizit aktiviert werden

• ✅ Dynamische Schema-Evolution — Intelligente Diagnosen und Lückenanalysen für Server, die GraphQL-Typen spontan neu generieren (wie Neo4j).

• ✅ Tiefe Beobachtbarkeit — Automatische Cypher-Extraktion und Bereinigung aus GraphQL-Erweiterungen.

🚀 Multi-Endpoint-Broadcast (Experimentell ab v3.9.0+)

Ab v3.9.0 unterstützt der Server das gleichzeitige Abfragen mehrerer GraphQL-Endpunkte. Dies wurde ursprünglich entwickelt, um Mutationen über verschiedene Umgebungen hinweg zu synchronisieren (z. B. Node.js- und Python-Backends), eröffnet aber mächtige Möglichkeiten für die Datenaggregation.

• Keine Breaking Changes: Wenn Sie eine einzelne URL in ENDPOINT angeben, verhält sich der Server genau wie zuvor.

• Intelligente Aggregation: Wenn mehrere durch Kommas getrennte URLs angegeben werden, sendet der Server die Abfrage an alle und führt die resultierenden Arrays zusammen.

• Free-Tier-Limits umgehen: Perfekt für Nutzer von „Free-Tier“-Cloud-Datenbanken (wie Neo4j Aura). Sie können Ihre Daten auf mehrere kostenlose Instanzen aufteilen und diese Brücke verwenden, um sie als einen einzigen, vereinheitlichten Graphen abzufragen, wodurch Entitätsanzahl-Beschränkungen effektiv umgangen werden.

• Deduplizierung: Die Brücke entfernt automatisch doppelte Objekte basierend auf ihren eindeutigen Feldern, um das Kontextfenster der KI sauber zu halten.

⚠️ Nutzung auf eigene Gefahr: Dieses Feature setzt voraus, dass alle Endpunkte dasselbe (oder ein sehr ähnliches) GraphQL-Schema teilen. Die Introspektion wird gegen den ersten Endpunkt in der Liste durchgeführt.

💡 Anwendungsfall: Überbrückung von WSL und Windows (PowerShell)

Eine häufige Herausforderung für Windows-Entwickler ist die Netzwerkisolierung zwischen dem Windows Subsystem for Linux (WSL) und dem Host-Betriebssystem. Dieses Feature ermöglicht es Ihnen, diese beiden Welten zu einem „Unified Nervous System“ zu verbinden.

Beispielkonfiguration für Claude Desktop:

{
  "ENDPOINT": "http://DESKTOP-NAME.local:2311/graphql,http://127.0.0.1:4000/graphql"
}

• Hybrides Ökosystem: Nahtloses Abfragen und Aggregieren von Daten über Windows-native Prozesse (PowerShell) und Linux-basierte Umgebungen (WSL) hinweg.

• mDNS-Unterstützung: Durch die Verwendung von .local-Adressen löst die Brücke automatisch die IP des Host-Rechners innerhalb der WSL-Umgebung auf.

• Transparente Aggregation: Der KI-Assistent interagiert mit einem einzigen, vereinheitlichten Schema, ohne zu wissen, dass die Daten gleichzeitig von verschiedenen Betriebssystemen abgerufen werden.

🔍 Erweiterte Beobachtbarkeit & Cypher

Die Brücke bietet tiefe Einblicke in die Art und Weise, wie das LLM mit Ihrer Graph-Datenbank interagiert.

🕸️ Automatisierte Cypher-Extraktion

Für GraphQL-Server-Implementierungen, die Abfrageausführungspläne zurückgeben (wie @neo4j/graphql), führt die Brücke automatisch Folgendes aus:

1. Erkennt extensions.cypher in der Antwort.

2. Bereinigt die Ausgabe durch Entfernen interner Header (wie CYPHER 5 oder leere PARAMS).

3. Injiziert einen sauberen Cypher-Block direkt in die Ausgabe des Tools, damit die KI ihn analysieren kann.

Hinweis: Dieses Feature erfordert, dass Ihr GraphQL-Server so konfiguriert ist, dass Debug-Informationen in den Antwort-Erweiterungen enthalten sind.

🎨 Visuelles Command Center (GraphiQL)

Im Gegensatz zu Standard-MCP-Servern bietet dieser eine visuelle Schnittstelle für Menschen. Wenn Sie mit ENABLE_HTTP=true ausführen, können Sie eine voll ausgestattete GraphiQL-IDE in Ihrem Browser öffnen.

• Endpunkt: http://localhost:6274/ (oder /graphiql)

• Header-Synchronisierung: Alle in Ihrer Umgebung gesetzten Header (wie GitHub-Token) werden automatisch in den „Headers“-Tab von GraphiQL für sofortige Tests injiziert.

💻 HTTP / Dualer Transport

Dieser Server läuft jetzt im Dual-Transport-Modus und unterstützt sowohl die Standard-STDIO-Kommunikation (die von den meisten MCP-Clients verwendet wird) als auch einen neuen HTTP JSON-RPC-Endpunkt auf Port 6274.

Dies ermöglicht externen Systemen, Webanwendungen und direkten curl-Befehlen den Zugriff auf die Tools des Servers mit Live-Anfrage-Protokollierung in Ihrem Terminal ([HTTP-RPC]-Logs).

Automatische Port-Auswahl

Der Server verwendet standardmäßig Port 6274. Wenn Sie auf einen EADDRINUSE-Fehler stoßen, findet der Server automatisch den nächsten verfügbaren Port. Überprüfen Sie die Server-Logs auf den endgültig gebundenen Port (z. B. [HTTP] Started server on http://localhost:6275).

Auflösen von Port-Konflikten (EADDRINUSE) und automatische Port-Auswahl

Der Server verwendet standardmäßig Port 6274. Wenn Sie auf einen EADDRINUSE: address already in use :::6274-Fehler stoßen (häufig bei der lokalen Entwicklung aufgrund veralteter Prozesse), findet der Server automatisch den nächsten verfügbaren Port (bis zu 10 Versuche, ohne mehrere Server zu starten).

Dies stellt sicher, dass der Server erfolgreich startet, auch wenn der Standard blockiert ist. Überprüfen Sie immer die Server-Logs auf den endgültig gebundenen Port (z. B. [HTTP] Started server on http://localhost:6275), falls Ihr curl oder Client-Tool am Standard 6274 scheitert.

Um einen bestimmten Port zu erzwingen (z. B. für garantierte externe Firewall-Einstellungen), können Sie weiterhin explizit die Umgebungsvariable MCP_PORT setzen:

Testen des HTTP-Endpunkts

Sie können den Endpunkt mit curl testen, solange der Server läuft (z. B. über npm run dev):

# Test the health check (assuming the server bound to the default or found the next available port)
curl http://localhost:6274/health

# Example: Test the query tool via JSON-RPC (using port 6275 if 6274 was busy)
curl -X POST http://localhost:6275/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"query-graphql","params":{"query":"query { __typename }"},"id":1}'

## 🔍 Filtered Introspection
Avoid 50k-line schema dumps. Ask for only what you need:
`@introspect-schema typeNames ["Query", "User"]`
## 🔍 Debug & Inspect
Use the official MCP Inspector to test your server live:
```bash
npx @modelcontextprotocol/inspector \
  -e ENDPOINT=https://api.example.com/graphql \
  npx @letoribo/mcp-graphql-enhanced

Umgebungsvariablen (Breaking Change in 1.0.0)

Hinweis: Ab Version 1.0.0 wurden Befehlszeilenargumente durch Umgebungsvariablen ersetzt.

• auto (Standard): Aktiviert HTTP automatisch nur, wenn es im MCP Inspector läuft...

• true: HTTP-Server immer aktivieren

• false: HTTP-Server vollständig deaktivieren

Beispiele

# Basic usage
ENDPOINT=http://localhost:3000/graphql npx @letoribo/mcp-graphql-enhanced
# With auth header
ENDPOINT=https://api.example.com/graphql \
HEADERS='{"Authorization":"Bearer xyz"}' \
npx @letoribo/mcp-graphql-enhanced
# Enable mutations
ENDPOINT=http://localhost:3000/graphql \
ALLOW_MUTATIONS=true \
npx @letoribo/mcp-graphql-enhanced
# Use local schema file
ENDPOINT=http://localhost:3000/graphql \
SCHEMA=./schema.graphql \
npx @letoribo/mcp-graphql-enhanced
# Change the HTTP port
MCP_PORT=8080 npx @letoribo/mcp-graphql-enhanced
# Disable HTTP transport (fastest, recommended for Claude Desktop)
ENABLE_HTTP=false npx @letoribo/mcp-graphql-enhanced
# Test the surgical precision and the IDE immediately:
ENDPOINT=https://api.github.com/graphql \
HEADERS='{"Authorization":"Bearer YOUR_GITHUB_TOKEN"}' \
ENABLE_HTTP=true \
npx @letoribo/mcp-graphql-enhanced

# Then visit http://localhost:6274/graphiql

🖥️ Claude Desktop Konfigurationsbeispiele

Sie können Claude Desktop mit Ihrer GraphQL-API verbinden, entweder über das npx-Paket (empfohlen für Einfachheit) oder das Docker-Image (ideal für Reproduzierbarkeit und Isolierung).

✅ Option 1: Verwendung von npx

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "npx",
      "args": ["@letoribo/mcp-graphql-enhanced"],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql"
      }
    }
  }
}

🐳 Option 2: Verwendung von Docker (Auto-Pull unterstützt)

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "sh",
      "args": [
        "-c",
        "docker run --rm -i -e ENDPOINT=$ENDPOINT -e HEADERS=$HEADERS -e ALLOW_MUTATIONS=$ALLOW_MUTATIONS ghcr.io/letoribo/mcp-graphql-enhanced:main"
      ],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql",
        "HEADERS": "{\"Authorization\": \"Bearer YOUR_TOKEN\"}",
        "ALLOW_MUTATIONS": "false"
      }
    }
  }
}

🧪 Option 3: Verwendung von node mit lokalem Build (für die Entwicklung)

Wenn Sie das Repo geklont und das Projekt gebaut haben (npm run build → Ausgabe nach dist/):

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql",
        "ALLOW_MUTATIONS": "true"
      }
    }
  }
}

Ressourcen

• graphql-schema: Der Server stellt das GraphQL-Schema als Ressource bereit, auf die Clients zugreifen können. Dies ist entweder die lokale Schemadatei, eine unter einer URL gehostete Schemadatei oder basiert auf einer Introspektionsabfrage.

Verfügbare Tools

Der Server bietet zwei Haupttools:

1. introspect-schema: Dieses Tool ruft das GraphQL-Schema oder eine gefilterte Teilmenge (über typeNames) ab. Verwenden Sie dies zuerst, wenn Sie keinen Zugriff auf das Schema als Ressource haben. Dies verwendet entweder die lokale Schemadatei, eine unter einer URL gehostete Schemadatei oder eine Introspektionsabfrage. Gefilterte Introspektion (typeNames) ist nur verfügbar, wenn ein Live-GraphQL-Endpunkt verwendet wird (nicht mit SCHEMA-Datei oder URL).

2. query-graphql: Führen Sie GraphQL-Abfragen gegen den Endpunkt aus. Standardmäßig sind Mutationen deaktiviert, sofern ALLOW_MUTATIONS nicht auf true gesetzt ist.

Sicherheitsüberlegungen

Mutationen sind standardmäßig deaktiviert, um unbeabsichtigte Datenänderungen zu verhindern. Validieren Sie HEADERS- und SCHEMA-Eingaben in der Produktion immer. Verwenden Sie nach Möglichkeit HTTPS-Endpunkte und kurzlebige Token.

Anpassen für Ihren eigenen Server

Dies ist eine sehr generische Implementierung, die eine vollständige Introspektion ermöglicht und es Ihren Benutzern erlaubt, alles zu tun (einschließlich Mutationen). Wenn Sie eine spezifischere Implementierung benötigen, würde ich vorschlagen, einfach Ihr eigenes MCP zu erstellen und den Tool-Aufruf für Clients so einzuschränken, dass nur bestimmte Abfragefelder und/oder Variablen eingegeben werden können. Sie können dies als Referenz verwenden.