AI导哈

GraphQL架构嵌入MCP服务器

一个为LLMs设计的Python MCP服务器，用于索引GraphQL架构，存储类型到字段的嵌入，并通过嵌入端点实现快速查找和查询执行。

  • by ThoreKoritzius
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 ThoreKoritzius/graphql-mcp-server

使用说明

GraphQL模式嵌入器MCP服务器

用于LLM的Python MCP服务器，对GraphQL模式进行索引，并存储每个LLM的嵌入 type->field 通过嵌入端点，并支持快速查找+ run_query 在识别出相关类型后执行，以从GraphQL端点获取数据。

建筑

  • GraphQL模式：提供一个模式文件（SDL）来进行解析和索引。
  • 索引器： schema_indexer.py 构建GraphQL字段节点的导航索引，包括字段元数据、模糊搜索别名和查询根坐标，然后嵌入生成的搜索文本并持久化到 data/metadata.json + data/vectors.npz.
  • 服务器： server.py 公开MCP工具 list_types 和 run_query服务器确保启动时架构索引存在；它仅在重新索引或嵌入新查询时调用embeddings端点。
  • 坚持不懈： 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

本地端点测试（在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

工具：

  • list_types(query, limit=5) -在GraphQL字段节点上嵌入相似性搜索。结果由余弦相似性得分返回，包括 coordinates （从以下位置开始的路径步骤数组 Query)，加 query 为了 Query 字段和 select 用于嵌套对象字段。
  • run_query(query) –如果 --endpoint 设置后，将查询代理到端点；否则，对本地模式进行验证/运行（没有解析器；主要用于验证/形状检查，数据解析为null）。 索引和查询都使用相同的嵌入模型(text-embedding-3-small 默认情况下，通过config/env或 --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 运输；通过 --transport streamable-http 如果你想要HTTP。
  • 您还可以设置前缀为的env变量 FASTMCP_ （例如。， FASTMCP_HOST, FASTMCP_PORT, FASTMCP_LOG_LEVEL)以覆盖默认值。
  • 服务器确保模式索引是在启动时构建的；如果计算了嵌入，则会打印一个简单的进度条。集 GRAPHQL_EMBED_BATCH_SIZE 调整批量大小。
  • 服务器暴露MCP instructions （用覆盖 MCP_INSTRUCTIONS)将服务器描述为抽象层，并告诉LLM使用 list_types 然后 run_query 使用最少的工具调用。

使用MCP检查员进行快速测试

需要 npm/npx 在PATH上。

连接到已运行的SSE服务器

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

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

在另一个终端中（启动检查器并将其指向 /sse):

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

在Claude桌面/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"
    }
  }
}

如果您在auth之后公开此服务器，请传递标头：

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

相关 MCP