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 忽略，因此您可以在本地重新生成而不会污染仓库。

架构图

设置

设置环境变量。您可以从 .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"

GraphQL Schema Embedder MCP Server

GraphQL schema embedder MCP 服务器

架构

设置

运行 MCP 服务器

使用 MCP Inspector 进行快速测试

连接到已运行的 SSE 服务器

在 Claude Desktop / CLI 中配置

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API