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 團隊用心打造 ❤️