Skip to main content
Glama
deenesjakoruzh
ThoreKoritzius

GraphQL Schema Embedder MCP Server

by ThoreKoritzius
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

GraphQL schema embedder MCP 服务器

用于 LLM 的 Python MCP 服务器，它索引 GraphQL 模式，通过嵌入端点存储每个 type->field 的嵌入，并实现快速查找，一旦确定相关类型，即可执行 run_query 从您的 GraphQL 端点获取数据。

架构

  • GraphQL 模式：提供一个模式文件 (SDL) 以进行解析和索引。

  • 索引器：schema_indexer.py 构建 GraphQL 字段节点的导航索引，包括字段元数据、模糊搜索别名和查询根坐标，然后对生成的搜索文本进行嵌入并持久化到 data/metadata.json + data/vectors.npz。

  • 服务器：server.py 公开 MCP 工具 list_types 和 run_query。服务器确保在启动时存在模式索引；它仅在重新索引或嵌入新查询时调用嵌入端点。

  • 持久化：data/ 已被 .gitignore 忽略，因此您可以在本地重新生成而不会污染仓库。

架构图

Related MCP server: GraphQL Schema Explorer

设置

设置环境变量。您可以从 .env.example 开始。

环境配置：

  • GRAPHQL_EMBED_API_KEY (或 OPENAI_API_KEY)

  • GRAPHQL_EMBEDDINGS_URL (完整的嵌入 URL)

  • GRAPHQL_EMBED_MODEL

  • GRAPHQL_EMBED_API_KEY_HEADER / GRAPHQL_EMBED_API_KEY_PREFIX

  • GRAPHQL_EMBED_HEADERS (用于额外标头的 JSON 对象字符串) 端点身份验证 (使用 GRAPHQL_ENDPOINT_URL 时)：

  • GRAPHQL_ENDPOINT_HEADERS (JSON 对象字符串，与任何 --header 标志合并)

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

运行 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

本地端点测试 (仓库内示例服务器)：

# 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

工具：

  • list_types(query, limit=5) – 对 GraphQL 字段节点进行嵌入相似度搜索。结果按余弦相似度得分返回，并包含 coordinates（从 Query 开始的路径步骤数组），以及用于 Query 字段的 query 和用于嵌套对象字段的 select。

  • run_query(query) – 如果设置了 --endpoint，则将查询代理到该端点；否则针对本地模式进行验证/运行（无解析器；主要用于验证/形状检查，数据解析为 null）。 索引和查询都使用相同的嵌入模型（默认使用 text-embedding-3-small，可通过配置/环境变量或 --model 覆盖）。

排名 (list_types)：

  • 结果完全根据索引字段节点搜索文本的嵌入余弦相似度进行排名。

示例 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 }"
  }
]

注意：

  • python3 src/server.py 默认为 sse 传输；如果您需要 HTTP，请传递 --transport streamable-http。

  • 您还可以设置以 FASTMCP_ 为前缀的环境变量（例如 FASTMCP_HOST、FASTMCP_PORT、FASTMCP_LOG_LEVEL）来覆盖默认值。

  • 服务器确保在启动时构建模式索引；如果计算了嵌入，则会打印一个简单的进度条。设置 GRAPHQL_EMBED_BATCH_SIZE 以调整批处理大小。

  • 服务器公开 MCP instructions（使用 MCP_INSTRUCTIONS 覆盖），将服务器描述为抽象层，并告诉 LLM 使用 list_types 然后使用最少的工具调用执行 run_query。

使用 MCP Inspector 进行快速测试

需要在 PATH 中安装 npm/npx。

连接到已运行的 SSE 服务器

在一个终端中（启动服务器）：

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

在另一个终端中（启动 Inspector 并将其指向 /sse）：

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

在 Claude Desktop / CLI 中配置

如果您通过 SSE（默认）在本地运行此服务器，请将 Claude 指向 /sse URL。

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

您也可以通过 JSON 进行配置（例如配置文件）：

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

如果您将此服务器暴露在身份验证之后，请传递标头：

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers