Servidor MCP de incrustación de esquemas GraphQL

Servidor MCP en Python para LLMs que indexa un esquema GraphQL, almacena incrustaciones por type->field a través de un punto final de incrustaciones, y permite una búsqueda rápida además de la ejecución de run_query una vez identificados los tipos relevantes para obtener datos de su punto final GraphQL.

Arquitectura

• Esquema GraphQL: proporcione un archivo de esquema (SDL) para ejercitar el análisis y la indexación.

• Indexador: schema_indexer.py construye un índice de navegación de nodos de campo GraphQL, incluyendo metadatos de campo, alias de búsqueda difusa y coordenadas de la raíz de consulta (Query-root), luego incrusta el texto de búsqueda generado y lo persiste en data/metadata.json + data/vectors.npz.

• Servidor: server.py expone las herramientas MCP list_types y run_query. El servidor asegura que el índice del esquema exista al iniciarse; solo llama al punto final de incrustaciones cuando se reindexa o se incrusta una nueva consulta.

• Persistencia: data/ está en .gitignore para que pueda regenerar localmente sin contaminar el repositorio.

Configuración

Establezca las variables de entorno. Puede comenzar desde .env.example.

Configuración del entorno:

• GRAPHQL_EMBED_API_KEY (o OPENAI_API_KEY)

• GRAPHQL_EMBEDDINGS_URL (URL completa de incrustaciones)

• GRAPHQL_EMBED_MODEL

• GRAPHQL_EMBED_API_KEY_HEADER / GRAPHQL_EMBED_API_KEY_PREFIX

• GRAPHQL_EMBED_HEADERS (cadena de objeto JSON para encabezados adicionales) Autenticación del punto final (cuando se usa GRAPHQL_ENDPOINT_URL):

• GRAPHQL_ENDPOINT_HEADERS (cadena de objeto JSON, fusionada con cualquier bandera --header)

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

Ejecutar el servidor MCP

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

Prueba de punto final local (servidor de ejemplo en el repositorio):

# 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

Herramientas:

• list_types(query, limit=5) – búsqueda por similitud de incrustaciones sobre nodos de campo GraphQL. Los resultados se devuelven por puntuación de similitud de coseno e incluyen coordinates (matriz de pasos de ruta desde Query), además de query para campos de Query y select para campos de objeto anidados.

• run_query(query) – si se establece --endpoint, redirige la consulta al punto final; de lo contrario, valida/ejecuta contra el esquema local (sin resolutores; principalmente para validación/verificación de forma, los datos se resuelven como nulos). Tanto la indexación como la consulta utilizan el mismo modelo de incrustación (text-embedding-3-small por defecto, se puede anular mediante configuración/entorno o --model).

Clasificación (list_types):

• Los resultados se clasifican puramente por similitud de coseno de incrustación sobre el texto de búsqueda del nodo de campo indexado.

Ejemplo de salida de list_types:

[
  {
    "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 }"
  }
]

Notas:

• python3 src/server.py utiliza el transporte sse por defecto; pase --transport streamable-http si desea HTTP en su lugar.

• También puede establecer variables de entorno con el prefijo FASTMCP_ (por ejemplo, FASTMCP_HOST, FASTMCP_PORT, FASTMCP_LOG_LEVEL) para anular los valores predeterminados.

• El servidor asegura que el índice del esquema se construya al iniciarse; si se calculan las incrustaciones, se imprime una barra de progreso simple. Establezca GRAPHQL_EMBED_BATCH_SIZE para ajustar el tamaño del lote.

• El servidor expone instructions de MCP (anúlelas con MCP_INSTRUCTIONS) que describen el servidor como una capa de abstracción y le dicen al LLM que use list_types y luego run_query con llamadas mínimas a herramientas.

Prueba rápida con el Inspector MCP

Requiere npm/npx en el PATH.

Conectar a un servidor SSE ya en ejecución

En una terminal (inicie el servidor):

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

En otra terminal (inicie el Inspector y apúntelo a /sse):

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

Configurar en Claude Desktop / CLI

Si está ejecutando este servidor localmente sobre SSE (predeterminado), apunte Claude a la URL /sse.

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

También puede configurar mediante JSON (por ejemplo, archivo de configuración):

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

Si expone este servidor detrás de una autenticación, pase los encabezados:

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