Mcp Graphql Forge

MCP GraphQL Forge

快速安装

其他安装方式

# Via Smithery (recommended)
npx @smithery/cli install @toolprint/mcp-graphql-forge --client claude

# Via npm
npm install -g @toolprint/mcp-graphql-forge

一个 MCP 服务，可让 AI 工具访问 GraphQL API，具体方式如下：

• 根据 GraphQL 架构内省自动生成 MCP 工具
• 验证参数并处理错误，确保 AI 交互可靠
• 支持 stdio 和 HTTP 传输，适用于开发和生产环境
• 缓存架构和字段选择，确保性能稳定

✨ 功能

• 工具生成：根据 GraphQL 架构内省创建 MCP 工具
• 参数验证：多层验证可防止 GraphQL 错误
• 双重传输：支持 stdio（AI 工具）和 HTTP（开发/测试）
• 架构管理：支持可选的预先内省和缓存
• 身份验证：为需要身份验证的端点灵活配置标头 [实验性]

🚀 入门

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

使用 HTTP 模式快速开始（推荐用于开发）

1. 启动服务：

   # Start serving it with the Streamable HTTP transport
   GRAPHQL_ENDPOINT="https://your-api.com/graphql" npx -y @toolprint/mcp-graphql-forge --transport http --port 3001
   

2. 使用 MCP Inspector 连接：

   # In another terminal, launch the inspector
   npx @modelcontextprotocol/inspector
   

3. 使用身份验证：

   # Using environment variables for configuration
   export GRAPHQL_ENDPOINT="https://api.github.com/graphql"
   export GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN"
   npx @toolprint/mcp-graphql-forge --transport http --port 3001
   
   # Or all in one line
   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. 预生成架构：

   # Generate schema without starting server
   GRAPHQL_ENDPOINT="https://your-api.com/graphql" mcp-graphql-forge introspect
   
   # Start server using pre-generated schema
   mcp-graphql-forge --no-introspection --transport http --port 3001
   

2. 自定义架构位置：

   # Generate schema in custom location
   SCHEMA_PATH="./schemas/my-api.json" mcp-graphql-forge introspect
   
   # Use custom schema location
   SCHEMA_PATH="./schemas/my-api.json" mcp-graphql-forge --no-introspection --transport http --port 3001
   

3. 强制重新生成架构：

   # Force regenerate schema even if it exists
   mcp-graphql-forge introspect --force
   
   # Regenerate and start server
   mcp-graphql-forge --force-introspection --transport http --port 3001
   

高级配置

# Multiple custom headers
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

# Development mode with auto-reload on schema changes
mcp-graphql-forge --transport http --port 3001 --watch

🛠️ 工作原理

1. 架构内省

🗂️  Building field selection cache for all types...
📊 Generated field selections for 44 types  
💾 Field selection cache contains 44 full selections and 5 minimal selections
Generated 63 tools from GraphQL schema:
  - 30 query tools
  - 33 mutation tools

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 查询：

# ❌ Error-prone manual approach
query {
  articles {
    # Missing required field selections!
    author {
      # Circular reference issues!
    }
  }
}

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

# ✅ Auto-generated with full field selections
query articlesOperation($filters: ArticleFiltersInput, $pagination: PaginationArg) {
  articles(filters: $filters, pagination: $pagination) {
    documentId
    title
    description
    author {
      documentId
      name
      email
      articles_connection {
        nodes { documentId }  # Circular reference handled!
      }
    }
    category {
      documentId
      name
      articles { documentId }  # Cached selection reused!
    }
  }
}

🏗️ 架构

缓存系统

• 类型级缓存：每种 GraphQL 类型的字段选择只计算一次，并重复使用
• 循环引用解析：智能检测，并使用最少字段回退方案
• 输出一致性：相同类型始终生成相同的字段选择

验证流程

1. JSON Schema 验证：MCP 客户端会在执行前验证参数
2. 服务端验证：防止在缺少必需参数时执行
3. GraphQL 验证：在 GraphQL 层进行最终验证

传输支持

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

📚 API 参考

CLI 选项

mcp-graphql-forge [options]

Options:
  --transport <type>     Transport type: stdio or http (default: stdio)
  --port <number>        Port for HTTP transport (default: 3000)
  --no-introspection     Skip schema introspection (use cached schema)
  --version              Show version number
  --help                 Show help

环境变量

生成的工具 Schema

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

{
  name: "query_user",
  description: "Execute GraphQL query: user",
  inputSchema: {
    type: "object",
    properties: {
      id: { type: "string" }
    },
    required: ["id"]  // Only truly required parameters
  }
}

🧪 测试

全面的测试套件

• 40+ 个测试用例：覆盖所有功能和边缘情况
• 真实场景：针对实际 GraphQL Schema（Strapi、GitHub 等）进行测试
• 安全测试：原型污染防护和输入验证
• 性能测试：缓存效率和字段选择优化

# Run all tests
npm test

# Run specific test suites
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

# Coverage report
npm run test:coverage

集成测试

# Test with real GraphQL endpoints
GRAPHQL_ENDPOINT="https://countries.trevorblades.com/" npm test

# Test caching performance
npm run test:performance

🛡️ 安全性

参数验证

• 必需参数检查：防止 GraphQL 变量错误
• 空值/未定义值检查：验证参数是否存在及其取值
• 原型污染防护：使用安全的属性检查方法

Schema 安全性

• 输入清理：所有 GraphQL 输入都会进行正确的类型检查和验证
• 循环引用防护：防止字段选择中出现无限递归
• 标头验证：安全处理用于身份验证的标头

🚀 性能

基准测试

• Schema 自省：典型 Schema 约需 10ms
• 工具生成：启用缓存后约需 5ms
• 字段选择：预先计算并缓存，可即时访问
• 内存用量：通过高效缓存将内存占用降至最低

优化功能

• 字段选择缓存：避免重复计算字段选择
• Schema 缓存：可选的 Schema 持久化，加快重启速度
• 最小化 GraphQL 查询：仅请求必要的字段
• 连接池：高效管理 HTTP 客户端

🤝 贡献

欢迎贡献！详情请参阅我们的贡献指南。

开发环境设置

# Clone the repository
git clone https://github.com/toolprint/mcp-graphql-forge.git
cd mcp-graphql-forge

# Install dependencies
npm install

# Run tests
npm test

# Start development
npm run dev

代码质量

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

📖 示例

实际用法

# Connect to Strapi GraphQL API
export GRAPHQL_ENDPOINT="https://your-strapi.com/graphql"
export GRAPHQL_AUTH_HEADER="Bearer YOUR_STRAPI_TOKEN"
mcp-graphql-forge

# Generates tools like:
# - query_articles, query_users, query_categories
# - mutation_createArticle, mutation_updateUser
# - Full field selections with media, relations, and metadata

# Connect to GitHub GraphQL API
export GRAPHQL_ENDPOINT="https://api.github.com/graphql"
export GRAPHQL_AUTH_HEADER="Bearer YOUR_GITHUB_TOKEN"
mcp-graphql-forge

# Generates tools like:
# - query_repository, query_user, query_organization
# - query_search (with intelligent result type handling)
# - mutation_createIssue, mutation_addComment

# Connect to 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

# Generates tools for:
# - Product management (query_products, mutation_productCreate)
# - Order processing (query_orders, mutation_orderUpdate)
# - Customer management with full relationship mapping

自定义 Schema 示例

// Example: Blog Platform Schema
type Query {
  posts(published: Boolean, authorId: ID): [Post]
  post(slug: String!): Post
  authors: [Author]
}

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

// Generated Tools:
// ✅ query_posts (published?: boolean, authorId?: string)
// ✅ query_post (slug: string) ← Required parameter enforced
// ✅ query_authors () ← No parameters
// ✅ mutation_createPost (input: CreatePostInput) ← Validated input
// ✅ mutation_publishPost (id: string) ← Required parameter enforced

📄 许可证

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

🏢 关于 OneGrep, Inc.

MCP GraphQL Forge 由专注于构建开发者工具和 AI 基础设施的公司 OneGrep, Inc. 开发并维护。

问题 • 讨论

由 OneGrep 团队倾心打造 ❤️