graphql-mcp-server-tools

关键词

GraphQLJSON-RPC自动工具生成传输协议服务器端实现

使用说明

  • 项目简介
    • 该项目实现一个 MCP 服务器，核心功能是从 GraphQL 架构中自动发现 Query/Mutation，将其转换为可通过 MCP 协议调用的工具，并通过 JSON-RPC 与客户端进行交互（支持 stdio 与 HTTP 两种传输方式）。
    • 服务器负责会话管理、能力声明、以及对输入进行 JSON 架构验证，输出可供 LLM 客户端消费的上下文信息与工具执行能力。
  • 主要功能点
    • 自动工具生成：解析 GraphQL 架构中的 Query/Mutation，生成工具名称、输入结构（inputSchema）及执行文档（GraphQL 操作文档）。
    • 数据与工具访问：工具支持通过 GraphQL 查询/变更对后端数据进行查询与修改，并返回结构化结果。
    • 提供多传输协议：支持标准输入输出（stdio）和 HTTP 服务（REST 风格的 MCP 端点 http://host:port/mcp）。
    • JSON Schema 兼容：将 GraphQL 的输入参数映射为 JSON 模式，便于 MCP 客户端进行参数验证。
    • 自定义与扩展：支持自定义标量类型映射、操作过滤（只暴露某些类型的操作）、日志输出、请求超时与重试策略等。
    • 安全与会话：HTTP 传输在初始连接后会分配会话 ID，以便后续连接管理与清理。
  • 安装步骤
    • 直接使用 npx 运行（无需全局安装）：
      • npx graphql-mcp-server-tools --schema <你的 schema 文件路径> --endpoint <你的 GraphQL API 地址>
    • 或者本地构建后运行（需要 Node.js 环境和打包产物）：
      • 先安装依赖并构建，再使用生成的 CLI 或脚本启动服务器（CLI 提供了启动选项）。
  • 服务器配置（供 MCP 客户端配置使用的示例，JSON 格式，包含 server name、command、args 等）
    • 基本示例（标准输出流方式启动服务器）： { "serverName": "mcp-graphql", "command": "node", "args": ["dist/cli.js", "--schema", "/path/to/schema.graphql", "--endpoint", "http://localhost:4000/graphql", "--transport", "stdio"] }
    • 使用 HTTP 传输的示例（通过指定端口暴露 MCP 端点）： { "serverName": "mcp-graphql", "command": "node", "args": ["dist/cli.js", "--schema", "/path/to/schema.graphql", "--endpoint", "http://localhost:4000/graphql", "--transport", "http", "--port", "3010"] } 注释说明
    • serverName: 客户端在管理与标识该服务器实例时使用的名称，默认为 mcp-graphql。
    • command: 启动服务器所需的命令（通常是 node），客户端会执行该命令以启动 MCP 服务器。
    • args: 命令行参数，需包含 schema 与 endpoint 等信息，具体选项与优先级请参考本仓库的使用说明。
    • MCP 客户端不需要你修改服务器实现，只需提供上述配置信息让客户端按需启动并连接。
  • 基本使用方法
    • 启动后，客户端可向 MCP 服务器发送以下请求：
      • initialize：获取协议版本、服务器信息与能力描述。
      • tools/list：获取所有工具的名称、描述及输入结构。
      • tools/call：调用某个工具（需要提供工具名称和参数）。
    • 客户端应按照 MCP 规范通过 JSON-RPC 与服务器通信，服务器返回相应的 JSON-RPC 响应或处理通知。
  • 额外信息
    • 你可以在 GraphQL 模式变化时重新生成工具集合，或通过配置自定义选项（如 maxDepth、自定义标量映射、operationFilter）来调整暴露给客户端的工具集。

服务器信息

访问项目