mcp-graphql-enhanced

mcp-graphql-enhanced

一个用于 GraphQL 的增强型 MCP（Model Context Protocol）服务，可解决大模型与 GraphQL API 之间现实中的互操作性问题。

可直接替代 mcp-graphql——支持动态请求头、可靠的变量解析，且不会造成任何破坏性变更。

🎯 什么是 mcp-graphql-enhanced？

mcp-graphql-enhanced 是一个高性能、联邦式 GraphQL 网关，旨在成为 LLM Agent 的主力工具。它连接了庞大而复杂的 GraphQL 生态与 AI 助手上下文受限的环境。与标准的“一刀切”内省工具不同，这类工具在大型架构（例如 GitHub 或企业级 Neo4j 图）面前常常不堪重负；本服务则可精确控制 Agent 如何感知并与数据交互。

💡 为什么需要它？

如果你在尝试内省 API 时见过<error>Tool result is too large</error>，就说明你已经碰到了标准 MCP 实现的限制。以下是 mcp-graphql-enhanced 适用于专业环境的原因：

避免 1MB 上限：它将范围控制的责任从服务端转移到调用方。你不必接受单方面的“全有或全无”数据转储，而是可以通过 typeNames 和 typeDepth 参数进行细粒度控制。

精准控制：你可以选择性地只内省所需的节点（例如 Repository、User 或 Message），让上下文窗口保持整洁，让大模型专注于任务。

追求可预测，而非无所不能：它不承诺“无限”容量，而是承诺可预测性。在企业系统中，你需要一种工具，让你能够精确遍历图，并在超出范围时以可预测的方式失败，而不是一个架构一变大就立刻崩溃的“黑盒”。

演示：查看针对 GitHub API 的真实诊断测试，比较范围限定内省与整体内省： 🔗 诊断案例研究：范围限定内省与整体内省对比（Shared Chat）

💬 社区与支持

加入交流！如果你对将此桥接工具与 Neo4j、Discord 数据图或 GraphQL 配合使用有疑问，欢迎来聊：

• Discord 频道： #mcp-graphql-enhanced
• 服务器： 官方 GraphQL Discord

这里最适合分享反馈、报告问题，或提出桥接工具“增强”功能的新建议。

✨ 主要增强功能

• ✅ 动态端点切换 — 无需重启服务或丢失会话上下文，即可通过工具参数直接实时切换目标。
• ✅ 内置 GraphiQL IDE — 在 /（或 /graphql、/graphiql）提供可视化测试环境，并预配置请求头，方便立即测试和内省。
• ✅ 双传输方式 — 同时支持 STDIO（用于本地 CLI/客户端工具）和 HTTP/JSON-RPC（用于外部/浏览器客户端）。
• ✅ 动态请求头 — 通过工具参数传入 Authorization、X-API-Key 等（无需重启配置）
• ✅ 健壮的变量解析 — 修复 “Query variables must be a null or an object” 错误
• ✅ 智能内省 — 支持筛选请求（通过 typeNames）和递归深度控制（通过 typeDepth），减少大模型上下文噪声并优化架构探索。
• ✅ 完全兼容 MCP — 支持 Claude Desktop、Groq Desktop、Google Antigravity、Glama、Gemini CLI、Hermes Agent 和任何标准 MCP 客户端
• ✅ 默认安全 — 除非显式启用，否则禁用变更操作
• ✅ 动态架构演进 — 针对实时重新生成 GraphQL 类型的服务（如 Neo4j），提供智能诊断和差异分析。
• ✅ 深度可观测性 — 自动提取并清理 GraphQL 扩展中的 Cypher。

🔥 动态端点切换

该桥接服务允许大模型或客户端在单个会话中运行时动态连接到不同的 GraphQL 端点，无需重启服务或更改配置。

只需在 query-graphql 或 introspect-schema 中传入可选的 endpoint 参数：

• 零停机时间：实时切换底层架构并立即清除内部缓存。
• 保留上下文：切换不同环境中的查询（例如，从 Discord 数据摄取节点切换到 Neo4j 图数据库）时，保持 MCP 连接开启。

🚀 联邦式多节点架构（自 v3.9.1 起）

该服务以联邦 GraphQL 网关的形式运行，将独立节点合并为一个统一系统。

• 不产生破坏性变更：如果在 ENDPOINT 中提供单个 URL，服务的行为与之前完全相同。
• 联邦内省：同时扫描所有端点，以构建全局能力映射。
• 智能聚合：提供多个以逗号分隔的 URL 时，服务会广播查询，并使用通用深度去重（对象级别）合并结果。
• 冲突处理：识别不同节点中同名类型的结构差异，并以唯一名称公开这些类型。
• 绕过免费套餐限制：非常适合使用“免费套餐”云数据库（如 Neo4j Aura）的用户。你可以将数据拆分到多个免费实例中，再使用此桥接服务将它们作为一个统一图进行查询，从而有效绕过实体数量限制。

概念验证：

查看联邦查询合成的真实演示，其中 Agent 将实时 Discord 数据与 Neo4j 历史数据见解汇总在一起： 🔗 实时联邦分析（共享聊天）

💡 使用场景：连接 WSL 与 Windows（PowerShell）

Windows 开发者常遇到的一个问题是 Windows Subsystem for Linux（WSL）与宿主操作系统之间的网络隔离。此功能可将这两个环境连接起来，构成一个“统一神经系统”。

Claude Desktop 的示例配置：

{
  "ENDPOINT": "http://DESKTOP-NAME.local:2311/graphql,http://127.0.0.1:4000/graphql"
}

• 混合生态系统：无缝查询和聚合 Windows 原生进程（PowerShell）与基于 Linux 的环境（WSL）中的数据。

• mDNS 支持：使用 .local 地址时，桥接服务会自动从 WSL 环境中解析宿主机的 IP。

• 透明聚合：AI 助手通过单一统一架构进行交互，无需知道数据是从不同操作系统同时获取的。

🔍 高级可观测性与 Cypher

该桥接器可深入洞察大模型如何与图数据库交互。

🕸️ 自动提取 Cypher

对于会返回查询执行计划的 GraphQL 服务端实现（例如 @neo4j/graphql），该桥接器会自动：

1. 检测响应中的 extensions.cypher。
2. 清理输出，移除内部标头（例如 CYPHER 5 或空的 PARAMS）。
3. 注入干净的 Cypher 代码块，直接加入工具输出，供 AI 分析。

注意： 此功能要求将 GraphQL 服务端配置为在响应扩展中包含调试信息。

---

🎨 可视化控制中心（GraphiQL）

与标准 MCP 服务不同，该服务为人类用户提供可视化界面。使用 ENABLE_HTTP=true 运行时，你可以在浏览器中打开功能齐全的 GraphiQL IDE。

• 端点： http://localhost:6274/（或 /graphql、/graphiql）
• 标头同步： 环境中设置的任何标头（例如 GitHub 令牌）都会自动注入 GraphiQL 的“Headers”选项卡，以便立即测试。

💻 HTTP / 双传输模式

该服务以双传输模式运行，同时支持标准 STDIO 通信（大多数 MCP 客户端使用）和端口 6274 上的 HTTP JSON-RPC 端点。

这样，外部系统、Web 应用和直接执行的 curl 命令都可以访问该服务的工具，并在终端中实时记录请求（[HTTP-RPC] 日志）。

端点	方法	说明
/graphiql	GET	人类界面：可视化 GraphQL IDE。
/mcp	POST	用于执行工具的主要 JSON-RPC 2.0 端点。
/health	GET	简单的健康检查，返回 { status: 'ok' }。

解决端口冲突（EADDRINUSE）并自动选择端口

服务默认使用端口 6274。如果遇到 EADDRINUSE: address already in use :::6274 错误（本地开发中因残留进程而常见），服务会自动查找下一个可用端口（最多尝试 10 次，不会启动多个服务）。

这样即使默认端口被占用，服务也能成功启动。如果你的 curl 或客户端工具无法使用默认端口 6274，请务必查看服务日志中的最终绑定端口（例如，[HTTP] Started server on http://localhost:6275）。

如需强制指定端口（例如，确保外部防火墙设置正常），仍可显式设置 MCP_PORT 环境变量：

MCP_PORT=8080 npx @letoribo/mcp-graphql-enhanced

测试 HTTP 端点

只要服务正在运行（例如，通过 npm run dev 启动），你就可以使用 curl 测试该端点：

测试健康检查（假设服务绑定到默认端口或找到下一个可用端口）

curl http://localhost:6274/health

测试 JSON-RPC 传输

curl -X POST http://localhost:6274/mcp  \
-H "Content-Type: application/json"  \
-d '{
  "jsonrpc":"2.0",
  "method":"tools/list",
  "params":{},
  "id":1
}'

curl -X POST http://localhost:6274/mcp \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "introspect-schema",
    "arguments": {}
  },
  "id": 2
}'

curl -X POST http://localhost:6274/mcp \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "introspect-schema",
    "arguments": {
      "endpoint": "https://mcp-neo4j-discord.vercel.app/api/graphiql"
    }
  },
  "id": 3
}'

curl -X POST http://localhost:6274/mcp \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "introspect-schema",
    "arguments": {
      "typeNames": ["User", "Message"]
    }
  },
  "id": 4
}'

curl -X POST http://localhost:6274/mcp \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "introspect-schema",
    "arguments": {
      "typeNames": ["Message"],
      "typeDepth": 4
    }
  },
  "id": 5
}'

curl -X POST http://localhost:6274/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "query-graphql",
      "arguments": {
        "query": "{ guildChannels(guild_id: \"1312302100125843476\") { name id topic } }"
      }
    },
    "id": 6
  }'

# Executing query with dynamic endpoint switching
curl -X POST http://localhost:6274/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "query-graphql",
      "arguments": {
        "endpoint": "https://mcp-neo4j-discord.vercel.app/api/graphiql",
        "query": "{ getGuilds { name } }"
      }
    },
    "id": 7
  }'

# Targeted introspection with depth control and dynamic endpoint switching
curl -X POST http://localhost:6274/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "introspect-schema",
      "arguments": {
        "endpoint": "https://mcp-neo4j-discord.vercel.app/api/graphiql",
        "typeNames": ["Message"],
        "typeDepth": 1
      }
    },
    "id": 8
  }'

（如果 6274 被占用，则使用端口 6275）

curl -X POST http://localhost:6275/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"query-graphql","arguments":{"query":"query { __typename }"}},"id":1}'

🔍 使用官方 MCP Inspector 实时测试服务：

npx @modelcontextprotocol/inspector \
  -e ENDPOINT=https://api.example.com/graphql \
  npx @letoribo/mcp-graphql-enhanced

环境变量

注意： 从 1.0.0 版本起，命令行参数已由环境变量取代。

环境变量	说明	默认值
ENDPOINT	GraphQL 端点。支持以逗号分隔的列表，用于多节点架构。	https://mcp-discord.vercel.app/api/graphiql
HEADERS	包含请求标头的 JSON 字符串	{}
ALLOW_MUTATIONS	启用 mutation 操作（默认禁用）	false
NAME	MCP 服务的名称	mcp-graphql-enhanced
SCHEMA	本地 GraphQL 架构文件的路径或 URL	-
MCP_PORT	HTTP/JSON-RPC 服务的端口。	6274
ENABLE_HTTP	启用 HTTP 传输：auto（默认）、true 或 false	auto
关于 ENABLE_HTTP 的说明：

• auto（默认）：仅在 MCP Inspector 中运行时自动启用 HTTP。
• true：始终启用 HTTP 服务
• false：完全禁用 HTTP 服务

🚀 示例

1. 快速开始

使用默认端点启动的基本示例。

npx @letoribo/mcp-graphql-enhanced

2. 配置与身份验证

使用自定义标头运行（例如用于 API 密钥或 Bearer 令牌）。

ENDPOINT=https://api.example.com/graphql \
HEADERS='{"Authorization":"Bearer xyz"}' \
npx @letoribo/mcp-graphql-enhanced

3. 高级集成

使用本地 .graphql 文件：如果你想使用本地架构，而不直接查询 API。

ENDPOINT=http://localhost:3000/graphql \
SCHEMA=./schema.graphql \
npx @letoribo/mcp-graphql-enhanced

启用变更（写入）：出于安全考虑，默认禁用变更。若要启用：

ENDPOINT=http://localhost:3000/graphql \
ALLOW_MUTATIONS=true \
npx @letoribo/mcp-graphql-enhanced

多节点架构（联邦）：将多个来源的数据聚合到一个统一的图中。

ENDPOINT=https://mcp-discord.vercel.app/api/graphiql,https://mcp-neo4j-discord.vercel.app/api/graphiql \
npx @letoribo/mcp-graphql-enhanced

4. 自定义环境

端口配置和开发模式设置示例。

# Change the HTTP port
MCP_PORT=8080 npx @letoribo/mcp-graphql-enhanced

# Test targeted introspection and explore the schema visually:
ENDPOINT=https://api.github.com/graphql \
HEADERS='{"Authorization":"Bearer YOUR_GITHUB_TOKEN"}' \
ENABLE_HTTP=true \
npx @letoribo/mcp-graphql-enhanced

# Then visit http://localhost:6274/graphiql

5. 使用 mcpgql 交互式启动（推荐）

如果你想跳过手动设置环境变量，可以使用我们在 npm 上提供的 CLI 工具。 如果已全局安装（npm install -g @letoribo/mcpgql），只需运行：

mcpgql

或者，你也可以不进行全局安装，直接运行：

npx @letoribo/mcpgql@latest

• 零配置启动：自动发现并初始化模板。
• 交互式选择：随时切换多个端点和权限。
• 桥接模式：自动处理 localhost:6274 上的 Federated Bridge 设置。

☁️ 部署到云端

此服务已完全容器化，并针对长期运行进行了优化。

推荐托管平台

平台	推荐端口	说明
Railway	8080	在 Variables 中设置 PORT，并更新 Networking ingress port。
Render	10000	在 Environment Variables 中设置 PORT。
Azure Container Apps	8080	在 Environment Variables 中设置 PORT 和 ENABLE_HTTP=true，然后启用 Ingress 并将其目标端口设置为相同端口。

使用 Azure CLI 快速部署

az containerapp up \
  --name mcp-graphql-enhanced \
  --resource-group mcp-graphql-rg \
  --image ghcr.io/letoribo/mcp-graphql-enhanced:latest \
  --ingress external \
  --target-port 8080 \
  --env-vars ENABLE_HTTP=true PORT=8080

重要：

• 对于托管环境，必须在平台设置中设置环境变量 ENABLE_HTTP=true，以确保 HTTP 传输层处于启用状态。
• 请确保托管提供商的公共网络设置已配置为将流量路由到 PORT 环境变量指定的端口，以避免出现 502 Bad Gateway 错误。

⚠️ 云端并发使用与动态端点

虽然 mcp-graphql-enhanced 支持通过可选的 endpoint 参数动态切换目标端点，但在托管或共享环境（例如 Render、Railway、Smithery）中运行时，请注意状态可变性：

• **状态隔离：**提供 endpoint 参数会动态更新该服务实例的活动图上下文。
• **云端并发请求的最佳实践：**如果多个客户端、Agent 会话或自动化工作进程共用同一个云端实例，请始终在每次工具调用（query-graphql 和 introspect-schema）中显式传入 endpoint。
• **防止上下文漂移：**在共享环境中依赖隐式缓存的端点，可能导致竞态条件：其他会话的并发调用会在你不知情的情况下切换活动上游 URL。

🌐 公共在线网关（托管式 SSE/HTTP 桥接）

如果想立即测试桥接，无需运行本地 Node.js 进程，可使用我们托管在云端的端点：

平台	边缘运行时	公共 MCP 端点
Cloudflare Workers	Workers V8（全球边缘网络）	mcp-graphql-enhanced.letoribo.workers.dev/mcp
Vercel	Node.js 无服务器	mcp-graphql-enhanced.vercel.app/mcp

注意： 公共网关运行在共享环境中。请记得在工具调用中提供明确的 endpoint 和 headers，以确保请求相互隔离。

🖥️ Claude Desktop 配置示例

你可以通过 npx 包（推荐，简单易用）或 Docker 镜像（适合确保可复现性和隔离性）将 Claude Desktop 连接到你的 GraphQL API。

✅ 选项 1：使用 npx

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "npx",
      "args": ["@letoribo/mcp-graphql-enhanced"],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql"
      }
    }
  }
}

🐳 选项 2：使用 Docker（支持自动拉取）

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "sh",
      "args": [
        "-c",
        "docker run --rm -i -e ENDPOINT=$ENDPOINT -e HEADERS=$HEADERS -e ALLOW_MUTATIONS=$ALLOW_MUTATIONS ghcr.io/letoribo/mcp-graphql-enhanced:main"
      ],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql",
        "HEADERS": "{\"Authorization\": \"Bearer YOUR_TOKEN\"}",
        "ALLOW_MUTATIONS": "false"
      }
    }
  }
}

🧪 选项 3：使用 node 和本地构建（用于开发）

如果你已克隆仓库并构建项目（npm run build → 输出到 dist/）：

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql",
        "ALLOW_MUTATIONS": "true"
      }
    }
  }
}

🖥️ 在线 Playground 集成（mcp-graphiql）

是否希望在 Claude Desktop 或 Antigravity 中生成的 GraphQL 查询，能实时自动填入你的 GraphiQL Playground？

@letoribo/mcp-graphql-enhanced 提供了通往 mcp-graphiql 的 HTTP/SSE 桥接。每当你的 AI Agent 调用 query-graphql 时，负载就会立即流式传输到已打开的 GraphiQL 标签页；切换端点时，introspect-schema 会热重载并实时更新 Docs 浏览器。

资源

• graphql-schema：服务端将 GraphQL 架构作为资源公开，客户端可以访问该资源。它可以是本地架构文件、托管在 URL 上的架构文件，也可以基于内省查询。

可用工具

该服务提供两个主要工具：

1. introspect-schema：获取 GraphQL 架构或其子集。请先使用此工具了解图结构。

• 参数：
  • typeNames （可选，数组）：要检查的特定类型列表（例如，["User", "Message"]）。仅返回图中相关部分，减少冗余信息。
  • typeDepth （可选，数字）：控制嵌套字段的递归层级（默认值：2）。

    注意： 只有在提供 typeNames 以缩小范围时，typeDepth 才有效。

  • endpoint （可选，字符串）：目标 GraphQL HTTP/HTTPS URL，可在执行内省前动态切换端点。
  • headers （可选，字符串）：自定义 HTTP 标头的 JSON 字符串（例如，'{"Authorization": "Bearer token"}'）。
• 注意： 只有查询在线 GraphQL 端点时，才能进行筛选式内省。

2. query-graphql：对端点执行 GraphQL 查询。默认情况下，除非将 ALLOW_MUTATIONS 设为 true，否则禁用变更操作。

• 参数：
  • query （必填，字符串）：GraphQL 查询或变更操作字符串。
  • variables （可选，字符串）：变量对象的 JSON 字符串。
  • endpoint （可选，字符串）：目标 GraphQL HTTP/HTTPS URL，可在执行查询前动态切换端点。
  • headers （可选，字符串）：自定义 HTTP 标头的 JSON 字符串（例如，'{"Authorization": "Bearer token"}'）。

💡 注意：动态标头与静态环境变量 过去，身份验证令牌必须在启动时静态硬编码到配置的 "env" 区块中（例如，在 claude_desktop_config.json 中）。

现在，query-graphql 和 introspect-schema 直接支持可选的 headers 参数，你可以完全动态地控制标头：

• 将机密保留在终端中：你不必将私有令牌（例如 GitHub PAT 或 Bearer 密钥）直接提供给 Claude 的提示词或静态配置。只需设置 "ENABLE_HTTP": "true"，在终端中直接运行 cURL 命令或本地脚本，并在那里传入标头。运行时传入的任何标头都会覆盖配置文件中的静态令牌。否则，Claude 可能会因为你在聊天中分享原始机密令牌而嘲笑你！
• 随时切换：无需重启 MCP 服务，即可在执行时为每个请求或端点动态注入不同的身份验证标头。

安全注意事项

默认禁用变更操作，以防止意外更改数据。在生产环境中，务必验证 HEADERS 和 SCHEMA 输入。尽可能使用 HTTPS 端点和短时效令牌。

为你自己的服务自定义

这是一个非常通用的实现，支持完整内省，并允许用户执行任何操作（包括变更操作）。如果你需要更具体的实现，我建议自行创建 MCP，并限制客户端调用工具时只能输入特定查询字段和／或变量。你可以将此作为参考。

---

贡献者说明

本项目未使用 Claude Code。如果你想了解 Claude 如何通过自定义 MCP 架构成为共同作者，欢迎提问！