shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

mcp-graphql-forge

一个MCP服务器，通过GraphQL模式自省自动生成AI工具，支持参数验证和双传输模式，使AI工具能够可靠地访问GraphQL API。

article

README

🚀 MCP GraphQL Forge

MCP GraphQL Forge 是一个 MCP 服务器，它让 AI 工具能够轻松访问 GraphQL API。其具备自动从 GraphQL 模式自省生成 MCP 工具、验证参数并处理错误、支持多种传输方式以及缓存模式和字段选择等功能，能为 AI 交互提供可靠保障，确保性能稳定。

🚀 快速开始

注意：目前 Docker 运行时支持仍在开发中。对于生产部署，我们建议在 Smithery 等平台上使用 TypeScript 运行时。

推荐开发使用的 HTTP 模式快速启动

  1. 启动服务器：

    # 使用可流式 HTTP 传输启动服务
GRAPHQL_ENDPOINT="https://your-api.com/graphql" npx -y @toolprint/mcp-graphql-forge --transport http --port 3001

  2. 连接 MCP 检查器：

    # 在另一个终端中启动检查器
npx @modelcontextprotocol/inspector

  3. 使用身份验证：

    # 使用环境变量进行配置
export GRAPHQL_ENDPOINT="https://api.github.com/graphql"
export GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN"
npx @toolprint/mcp-graphql-forge --transport http --port 3001

# 或者一行完成
GRAPHQL_ENDPOINT="https://api.github.com/graphql" GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN" npx @toolprint/mcp-graphql-forge --transport http --port 3001

直接集成 AI（Claude/Cursor）

在项目根目录创建一个 mcp.json 文件，这将使其以 stdio 模式运行。

{
    "mcpServers": {
        "mcp-graphql-forge": {
            "command": "npx",
            "args": [
              "-y",
              "@toolprint/mcp-graphql-forge"
            ],
            "env": {
                "GRAPHQL_ENDPOINT": "https://your-api.com/graphql",
                "GRAPHQL_AUTH_HEADER": "Bearer YOUR_TOKEN"
            }
        }
    }
}

模式管理

  1. 预生成模式：

    # 不启动服务器生成模式
GRAPHQL_ENDPOINT="https://your-api.com/graphql" mcp-graphql-forge introspect

# 使用预生成的模式启动服务器
mcp-graphql-forge --no-introspection --transport http --port 3001

  2. 自定义模式位置：

    # 在自定义位置生成模式
SCHEMA_PATH="./schemas/my-api.json" mcp-graphql-forge introspect

# 使用自定义模式位置
SCHEMA_PATH="./schemas/my-api.json" mcp-graphql-forge --no-introspection --transport http --port 3001

  3. 强制重新生成模式：

    # 即使模式存在也强制重新生成
mcp-graphql-forge introspect --force

# 重新生成并启动服务器
mcp-graphql-forge --force-introspection --transport http --port 3001

高级配置

# 多个自定义头
export GRAPHQL_HEADER_X_API_KEY="your-api-key"
export GRAPHQL_HEADER_X_CLIENT_ID="your-client-id"
mcp-graphql-forge --transport http --port 3001

# 开发模式，模式更改时自动重新加载
mcp-graphql-forge --transport http --port 3001 --watch

✨ 主要特性

  • 工具生成：从 GraphQL 模式自省创建 MCP 工具。
  • 参数验证：多层验证可防止 GraphQL 错误。
  • 双传输方式：支持 stdio（用于 AI 工具）和 HTTP（用于开发/测试）。
  • 模式管理：可选的预自省和缓存功能。
  • 身份验证：为经过身份验证的端点提供灵活的头配置 [实验性]。

📦 安装指南

快速安装

Install MCP Server

其他安装方法

# 通过 Smithery（推荐）
npx @smithery/cli install @toolprint/mcp-graphql-forge --client claude

# 通过 npm
npm install -g @toolprint/mcp-graphql-forge

💻 使用示例

基础用法

真实世界使用示例

🔸 集成 Strapi CMS 
# 连接到 Strapi GraphQL API
export GRAPHQL_ENDPOINT="https://your-strapi.com/graphql"
export GRAPHQL_AUTH_HEADER="Bearer YOUR_STRAPI_TOKEN"
mcp-graphql-forge

# 生成的工具如下：
# - query_articles, query_users, query_categories
# - mutation_createArticle, mutation_updateUser
# - 包含媒体、关系和元数据的完整字段选择
🔸 集成 GitHub API 
# 连接到 GitHub GraphQL API
export GRAPHQL_ENDPOINT="https://api.github.com/graphql"
export GRAPHQL_AUTH_HEADER="Bearer YOUR_GITHUB_TOKEN"
mcp-graphql-forge

# 生成的工具如下：
# - query_repository, query_user, query_organization
# - query_search（具备智能结果类型处理）
# - mutation_createIssue, mutation_addComment
🔸 电子商务平台 
# 连接到 Shopify/WooCommerce GraphQL
export GRAPHQL_ENDPOINT="https://your-shop.myshopify.com/api/graphql"
export GRAPHQL_HEADER_X_SHOPIFY_ACCESS_TOKEN="YOUR_TOKEN"
mcp-graphql-forge

# 生成的工具用于：
# - 产品管理（query_products, mutation_productCreate）
# - 订单处理（query_orders, mutation_orderUpdate）
# - 具备完整关系映射的客户管理

高级用法

自定义模式示例

// 示例：博客平台模式
type Query {
  posts(published: Boolean, authorId: ID): [Post]
  post(slug: String!): Post
  authors: [Author]
}

type Mutation {
  createPost(input: CreatePostInput!): Post
  publishPost(id: ID!): Post
}

// 生成的工具：
// ✅ query_posts (published?: boolean, authorId?: string)
// ✅ query_post (slug: string) ← 强制使用必需参数
// ✅ query_authors () ← 无参数
// ✅ mutation_createPost (input: CreatePostInput) ← 验证输入
// ✅ mutation_publishPost (id: string) ← 强制使用必需参数

📚 详细文档

CLI 选项

mcp-graphql-forge [options]

选项:
  --transport <type>     传输类型：stdio 或 http（默认：stdio）
  --port <number>        HTTP 传输的端口（默认：3000）
  --no-introspection     跳过模式自省（使用缓存的模式）
  --version              显示版本号
  --help                 显示帮助信息

环境变量

| 属性 | 详情 | 示例 | |------|------|------| | GRAPHQL_ENDPOINT | GraphQL API 端点 | https://api.example.com/graphql | | GRAPHQL_AUTH_HEADER | 授权头 | Bearer token123 | | GRAPHQL_HEADER_* | 自定义头 | GRAPHQL_HEADER_X_API_KEY=key123 | | SCHEMA_PATH | 模式缓存文件路径 | ./schema.json | | PORT | HTTP 服务器端口 | 3001 |

生成的工具模式

每个生成的工具都遵循以下模式：

{
  name: "query_user",
  description: "执行 GraphQL 查询：user",
  inputSchema: {
    type: "object",
    properties: {
      id: { type: "string" }
    },
    required: ["id"]  // 仅真正必需的参数
  }
}

🔧 技术细节

工作原理

1. 模式自省

🗂️  为所有类型构建字段选择缓存...
📊 为 44 种类型生成了字段选择  
💾 字段选择缓存包含 44 个完整选择和 5 个最小选择
从 GraphQL 模式生成了 63 个工具：
  - 30 个查询工具
  - 33 个变更工具

2. 智能工具生成

对于如下 GraphQL 模式：

type Query {
  user(id: ID!): User
  articles(filters: ArticleFiltersInput, pagination: PaginationArg): [Article]
}

type Mutation {
  createUser(input: CreateUserInput!): User
}

Fast MCP GraphQL 会自动生成：

  • ✅ query_user - 具备必需的 id 参数验证
  • ✅ query_articles - 具备可选的过滤和分页功能
  • ✅ mutation_createUser - 具备输入验证和完整的字段选择

3. 智能字段选择

无需手动构建 GraphQL 查询：

# ❌ 易出错的手动方式
query {
  articles {
    # 缺少必需的字段选择！
    author {
      # 存在循环引用问题！
    }
  }
}

Fast MCP GraphQL 会自动生成最优查询：

# ✅ 自动生成，包含完整字段选择
query articlesOperation($filters: ArticleFiltersInput, $pagination: PaginationArg) {
  articles(filters: $filters, pagination: $pagination) {
    documentId
    title
    description
    author {
      documentId
      name
      email
      articles_connection {
        nodes { documentId }  # 处理循环引用！
      }
    }
    category {
      documentId
      name
      articles { documentId }  # 重用缓存的选择！
    }
  }
}

架构

缓存系统

  • 类型级缓存：每个 GraphQL 类型的字段选择仅计算一次并重复使用。
  • 循环引用解析：智能检测并采用最小字段回退策略。
  • 一致输出：相同类型始终生成相同的字段选择。

验证管道

  1. JSON 模式验证：MCP 客户端在执行前验证参数。
  2. 服务器端验证：防止使用缺少必需参数的情况执行。
  3. GraphQL 验证：在 GraphQL 层进行最终验证。

传输支持

  • Stdio 传输：用于 MCP 客户端集成（默认）。
  • HTTP 传输：符合 MCP 2025 可流式 HTTP 规范的 RESTful 接口。
  • 会话管理：为 HTTP 传输自动处理会话。

测试

综合测试套件

  • 40 多个测试用例：涵盖所有功能和边缘情况。
  • 真实场景测试：针对实际的 GraphQL 模式（如 Strapi、GitHub 等）进行测试。
  • 安全测试：防止原型污染和输入验证。
  • 性能测试：测试缓存效率和字段选择优化。
# 运行所有测试
npm test

# 运行特定测试套件
npm test -- src/__tests__/field-selection-cache.test.ts
npm test -- src/__tests__/server-validation.test.ts
npm test -- src/__tests__/graphql-execution.test.ts

# 覆盖率报告
npm run test:coverage

集成测试

# 使用真实的 GraphQL 端点进行测试
GRAPHQL_ENDPOINT="https://countries.trevorblades.com/" npm test

# 测试缓存性能
npm run test:performance

安全

参数验证

  • 强制使用必需参数：防止 GraphQL 变量错误。
  • 空值/未定义检查：验证参数的存在和值。
  • 防止原型污染：使用安全的属性检查方法。

模式安全

  • 输入清理：所有 GraphQL 输入都经过正确类型化和验证。
  • 防止循环引用：防止字段选择中出现无限递归。
  • 头验证：安全处理身份验证头。

性能

基准测试

  • 模式自省：典型模式约需 10ms。
  • 工具生成：启用缓存时约需 5ms。
  • 字段选择：预计算并缓存，可即时访问。
  • 内存使用：高效缓存，内存占用极小。

优化特性

  • 字段选择缓存：消除冗余的字段选择计算。
  • 模式缓存：可选的模式持久化，加快重启速度。
  • 最小化 GraphQL 查询：仅请求必要的字段。
  • 连接池：高效管理 HTTP 客户端。

🤝 贡献

我们欢迎贡献！请参阅我们的 贡献指南 了解详细信息。

开发设置

# 克隆仓库
git clone https://github.com/toolprint/mcp-graphql-forge.git
cd mcp-graphql-forge

# 安装依赖
npm install

# 运行测试
npm test

# 开始开发
npm run dev

代码质量

  • TypeScript：完全类型化的代码库。
  • ESLint：一致的代码格式。
  • Vitest：现代测试框架。
  • 100% 测试覆盖率：全面的测试套件。

📄 许可证

本项目采用 Apache 许可证 2.0 - 详情请参阅 LICENSE 文件。

🏢 关于 OneGrep, Inc.

MCP GraphQL Forge 由 OneGrep, Inc. 开发和维护，这是一家专注于构建开发人员工具和 AI 基础设施的公司。

问题反馈 • 讨论交流

由 OneGrep 团队用心打造 ❤️

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端