GraphQL Schema Embedder MCP-Server

Python MCP-Server für LLMs, der ein GraphQL-Schema indiziert, Embeddings pro type->field über einen Embeddings-Endpunkt speichert und schnelles Nachschlagen sowie die Ausführung von run_query ermöglicht, sobald relevante Typen identifiziert wurden, um Daten von Ihrem GraphQL-Endpunkt abzurufen.

Architektur

• GraphQL-Schema: Stellen Sie eine Schema-Datei (SDL) bereit, um das Parsen und Indizieren zu testen.

• Indexer: schema_indexer.py erstellt einen Navigationsindex von GraphQL-Feldknoten, einschließlich Feld-Metadaten, Fuzzy-Search-Aliasen und Query-Root-Koordinaten, bettet dann den generierten Suchtext ein und speichert ihn in data/metadata.json + data/vectors.npz.

• Server: server.py stellt die MCP-Tools list_types und run_query bereit. Der Server stellt beim Start sicher, dass der Schema-Index existiert; er ruft den Embeddings-Endpunkt nur bei einer Neuindizierung oder beim Einbetten einer neuen Abfrage auf.

• Persistenz: data/ ist in .gitignore enthalten, sodass Sie lokal neu generieren können, ohne das Repo zu verschmutzen.

Einrichtung

Setzen Sie die Umgebungsvariablen. Sie können mit .env.example beginnen.

Umgebungskonfiguration:

• GRAPHQL_EMBED_API_KEY (oder OPENAI_API_KEY)

• GRAPHQL_EMBEDDINGS_URL (vollständige Embeddings-URL)

• GRAPHQL_EMBED_MODEL

• GRAPHQL_EMBED_API_KEY_HEADER / GRAPHQL_EMBED_API_KEY_PREFIX

• GRAPHQL_EMBED_HEADERS (JSON-Objekt-String für zusätzliche Header) Endpunkt-Authentifizierung (bei Verwendung von GRAPHQL_ENDPOINT_URL):

• GRAPHQL_ENDPOINT_HEADERS (JSON-Objekt-String, zusammengeführt mit allen --header-Flags)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 src/server.py

Den MCP-Server ausführen

python3 src/server.py                # SSE on 127.0.0.1:8000/sse by default
python3 src/server.py --transport sse     # explicit SSE
python3 src/server.py --transport streamable-http  # Streamable HTTP on 127.0.0.1:8000/mcp
# Or: point at a live GraphQL endpoint (requires introspection enabled)
python3 src/server.py --endpoint https://api.example.com/graphql
# Endpoint auth headers (repeat --header)
python3 src/src/server.py --endpoint https://api.example.com/graphql --header "Authorization: Bearer $TOKEN"
# Options: --host 0.0.0.0 --port 9000 --log-level DEBUG --mount-path /myapp

Lokaler Endpunkt-Test (Beispiel-Server im Repo):

# Terminal 1
python3 examples/graphql_test_server/server.py

# Terminal 2
python3 src/server.py --transport sse --endpoint http://127.0.0.1:4000/graphql

Tools:

• list_types(query, limit=5) – Ähnlichkeitssuche mittels Embeddings über GraphQL-Feldknoten. Die Ergebnisse werden nach Kosinus-Ähnlichkeits-Score zurückgegeben und enthalten coordinates (Array von Pfadschritten ab Query) sowie query für Query-Felder und select für verschachtelte Objektfelder.

• run_query(query) – Wenn --endpoint gesetzt ist, wird die Abfrage an den Endpunkt weitergeleitet; andernfalls wird sie gegen das lokale Schema validiert/ausgeführt (keine Resolver; primär zur Validierung/Formprüfung, Daten werden als null aufgelöst). Sowohl die Indizierung als auch die Abfrage verwenden dasselbe Embedding-Modell (standardmäßig text-embedding-3-small, überschreibbar über Konfiguration/Umgebung oder --model).

Ranking (list_types):

• Die Ergebnisse werden rein nach der Kosinus-Ähnlichkeit der Embeddings über den indizierten Suchtext der Feldknoten gerankt.

Beispiel für list_types-Ausgabe:

[
  {
    "field": "users",
    "summary": "Query.users(limit: Int) -> [User!]!",
    "coordinates": ["Query.users(limit: <Int>)"],
    "query": "query { users(limit: <Int>) { id name orders { id total status } } }"
  },
  {
    "type": "Order",
    "field": "total",
    "summary": "Order.total -> Float!",
    "coordinates": ["Query.user(id: <ID!>)", "User.orders", "Order.total"]
  },
  {
    "type": "User",
    "field": "orders",
    "summary": "User.orders -> [Order!]!",
    "coordinates": ["Query.user(id: <ID!>)", "User.orders"],
    "select": "orders { id total status }"
  }
]

Anmerkungen:

• python3 src/server.py verwendet standardmäßig den sse-Transport; übergeben Sie --transport streamable-http, wenn Sie stattdessen HTTP wünschen.

• Sie können auch Umgebungsvariablen mit dem Präfix FASTMCP_ setzen (z. B. FASTMCP_HOST, FASTMCP_PORT, FASTMCP_LOG_LEVEL), um die Standardwerte zu überschreiben.

• Der Server stellt sicher, dass der Schema-Index beim Start erstellt wird; wenn Embeddings berechnet werden, wird ein einfacher Fortschrittsbalken ausgegeben. Setzen Sie GRAPHQL_EMBED_BATCH_SIZE, um die Batch-Größe anzupassen.

• Der Server stellt MCP-instructions bereit (überschreibbar mit MCP_INSTRUCTIONS), die den Server als Abstraktionsschicht beschreiben und das LLM anweisen, list_types und dann run_query mit minimalen Tool-Aufrufen zu verwenden.

Schnelltest mit dem MCP Inspector

Erfordert npm/npx im PATH.

Verbindung zu einem bereits laufenden SSE-Server herstellen

In einem Terminal (Server starten):

python3 src/server.py --transport sse --port 8000

In einem anderen Terminal (Inspector starten und auf /sse verweisen):

npx @modelcontextprotocol/inspector --transport sse --server-url http://127.0.0.1:8000/sse

Konfiguration in Claude Desktop / CLI

Wenn Sie diesen Server lokal über SSE (Standard) ausführen, verweisen Sie Claude auf die /sse-URL.

claude mcp add --transport sse graphql-mcp http://127.0.0.1:8000/sse

Sie können auch über JSON konfigurieren (z. B. Konfigurationsdatei):

{
  "mcpServers": {
    "graphql-mcp": {
      "type": "sse",
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

Wenn Sie diesen Server hinter einer Authentifizierung bereitstellen, übergeben Sie Header:

claude mcp add --transport sse private-graphql http://127.0.0.1:8000/sse \
  --header "Authorization: Bearer your-token-here"