MCP Graphql Forge

🚀 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（用于开发/测试）。
• 模式管理：可选的预自省和缓存功能。
• 身份验证：为经过身份验证的端点提供灵活的头配置 [实验性]。

📦 安装指南

快速安装

其他安装方法

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

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

💻 使用示例

基础用法

真实世界使用示例

# 连接到 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 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                 显示帮助信息

环境变量

生成的工具模式

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

{
  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 团队用心打造 ❤️