mcp-graphql-enhanced

一个用于 GraphQL 的增强型 MCP（模型上下文协议）服务器，解决了 LLM 与 GraphQL API 之间实际应用中的互操作性问题。

mcp-graphql 的直接替代品——具有动态标头、强大的变量解析功能，且零破坏性变更。

💬 社区与支持

加入讨论！如果您对将此桥接器与 Neo4j、Discord 数据图或一般的 GraphQL 一起使用有疑问，欢迎加入我们：

• Discord 频道： #mcp-graphql-enhanced

• 服务器： 官方 GraphQL Discord

这是分享反馈、报告问题或建议桥接器新“增强”功能的最佳场所。

Related MCP server: mcp-graphql-schema

✨ 关键增强功能

• ✅ 内置 GraphiQL IDE — 位于 http://localhost:MCP_PORT/（或 /graphiql）的可视化操练场，带有预配置的标头。

• ✅ 双重传输 — 同时支持 STDIO（用于本地 CLI/客户端工具）和 HTTP/JSON-RPC（用于外部/浏览器客户端）。

• ✅ 动态标头 — 通过工具参数传递 Authorization、X-API-Key 等（无需重启配置）。

• ✅ 强大的变量解析 — 修复了 “Query variables must be a null or an object” 错误。

• ✅ 过滤后的内省 — 仅请求特定类型（例如 typeNames: ["Query", "User"]）以减少 LLM 上下文噪声。

• ✅ 完全兼容 MCP — 可与 Claude Desktop、Cursor、Glama 配合使用。

• ✅ 默认安全 — 除非明确启用，否则禁用变更（mutations）。

• ✅ 动态模式演进 — 为即时重新生成 GraphQL 类型（如 Neo4j）的服务器提供智能诊断和差距分析。

• ✅ 深度可观测性 — 自动从 GraphQL 扩展中提取并清理 Cypher。

🚀 多端点广播（v3.9.0+ 实验性功能）

从 v3.9.0 开始，服务器支持同时查询多个 GraphQL 端点。此功能最初旨在同步不同环境（例如 Node.js 和 Python 后端）之间的变更，但它为数据聚合开启了强大的可能性。

• 零破坏性变更：如果您在 ENDPOINT 中提供单个 URL，服务器的行为与之前完全相同。

• 智能聚合：当提供多个以逗号分隔的 URL 时，服务器会将查询广播到所有端点并合并结果数组。

• 绕过免费层限制：非常适合“免费层”云数据库（如 Neo4j Aura）的用户。您可以将数据拆分到多个免费实例中，并使用此桥接器将它们作为单个统一图谱进行查询，从而有效绕过实体数量限制。

• 去重：桥接器会自动根据唯一字段删除重复对象，以保持 AI 上下文窗口的整洁。

⚠️ 使用风险自负： 此功能假设所有端点共享相同（或非常相似）的 GraphQL 模式。内省是针对列表中的第一个端点执行的。

💡 用例：桥接 WSL 和 Windows (PowerShell)

Windows 开发人员面临的一个常见挑战是 Windows 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

该桥接器提供了关于 LLM 如何与您的图数据库交互的深度见解。

🕸️ 自动 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/（或 /graphiql）

• 标头同步： 环境中设置的任何标头（如 GitHub 令牌）都会自动注入到 GraphiQL 的“Headers”选项卡中，以便立即测试。

💻 HTTP / 双重传输

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

这允许外部系统、Web 应用程序和直接的 curl 命令访问服务器工具，并在您的终端中提供实时请求日志（[HTTP-RPC] 日志）。

自动端口选择

服务器默认使用端口 6274。如果您遇到 EADDRINUSE 错误，服务器将自动查找下一个可用端口。请查看服务器日志以获取最终绑定的端口（例如 [HTTP] Started server on http://localhost:6275）。

解决端口冲突 (EADDRINUSE) 和自动端口选择

服务器默认使用端口 6274。如果您遇到 EADDRINUSE: address already in use :::6274 错误（由于僵尸进程，在本地开发中很常见），服务器将自动查找下一个可用端口（最多尝试 10 次，不会生成多个服务器）。

这确保了即使默认端口被占用，服务器也能成功启动。如果您的 curl 或客户端工具在默认的 6274 上失败，请务必查看服务器日志以获取最终绑定的端口（例如 [HTTP] Started server on http://localhost:6275）。

要强制使用特定端口（例如，为了保证外部防火墙设置），您仍然可以显式设置 MCP_PORT 环境变量：

测试 HTTP 端点

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

# Test the health check (assuming the server bound to the default or found the next available port)
curl http://localhost:6274/health

# Example: Test the query tool via JSON-RPC (using port 6275 if 6274 was busy)
curl -X POST http://localhost:6275/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"query-graphql","params":{"query":"query { __typename }"},"id":1}'

## 🔍 Filtered Introspection
Avoid 50k-line schema dumps. Ask for only what you need:
`@introspect-schema typeNames ["Query", "User"]`
## 🔍 Debug & Inspect
Use the official MCP Inspector to test your server live:
```bash
npx @modelcontextprotocol/inspector \
  -e ENDPOINT=https://api.example.com/graphql \
  npx @letoribo/mcp-graphql-enhanced

环境变量（1.0.0 版本中的破坏性变更）

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

• auto（默认）：仅在 MCP Inspector 中运行时自动启用 HTTP...

• true：始终启用 HTTP 服务器

• false：完全禁用 HTTP 服务器

示例

# Basic usage
ENDPOINT=http://localhost:3000/graphql npx @letoribo/mcp-graphql-enhanced
# With auth header
ENDPOINT=https://api.example.com/graphql \
HEADERS='{"Authorization":"Bearer xyz"}' \
npx @letoribo/mcp-graphql-enhanced
# Enable mutations
ENDPOINT=http://localhost:3000/graphql \
ALLOW_MUTATIONS=true \
npx @letoribo/mcp-graphql-enhanced
# Use local schema file
ENDPOINT=http://localhost:3000/graphql \
SCHEMA=./schema.graphql \
npx @letoribo/mcp-graphql-enhanced
# Change the HTTP port
MCP_PORT=8080 npx @letoribo/mcp-graphql-enhanced
# Disable HTTP transport (fastest, recommended for Claude Desktop)
ENABLE_HTTP=false npx @letoribo/mcp-graphql-enhanced
# Test the surgical precision and the IDE immediately:
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

🖥️ 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"
      }
    }
  }
}

资源

• graphql-schema：服务器将 GraphQL 模式作为客户端可以访问的资源公开。这可以是本地模式文件、托管在 URL 上的模式文件，或者是基于内省查询的结果。

可用工具

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

1. introspect-schema：此工具检索 GraphQL 模式或过滤后的子集（通过 typeNames）。如果您无法将模式作为资源访问，请先使用此工具。 它使用本地模式文件、托管在 URL 上的模式文件或内省查询。 过滤后的内省 (typeNames) 仅在使用实时 GraphQL 端点时可用（不适用于 SCHEMA 文件或 URL）。

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

安全注意事项

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

为您自己的服务器进行自定义

这是一个非常通用的实现，它允许完全内省，并允许您的用户执行任何操作（包括变更）。如果您需要更具体的实现，我建议您创建自己的 MCP，并锁定工具调用，以便客户端只能输入特定的查询字段和/或变量。您可以将其作为参考。