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

GraphQL APIをAIツールから利用できるようにするMCP サーバーです。次の機能を備えています。

• 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

環境変数

生成されるツールスキーマ

生成される各ツールは、次のパターンに従います。

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

🧪 テスト

包括的なテストスイート

• 40 件以上のテストケース：すべての機能とエッジケースを網羅します
• 実環境のシナリオ：実際の GraphQL スキーマ（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 変数のエラーを防止します
• Null／Undefined のチェック：パラメーターの有無と値を検証します
• プロトタイプ汚染対策：安全なプロパティチェックメソッドを使用します

スキーマのセキュリティ

• 入力のサニタイズ：すべての GraphQL 入力を適切に型付けし、検証します
• 循環参照対策：フィールド選択での無限再帰を防止します
• ヘッダーの検証：認証用ヘッダーを安全に処理します

🚀 パフォーマンス

ベンチマーク

• スキーマイントロスペクション：一般的なスキーマで約 10ms
• ツール生成：キャッシュ有効時に約 5ms
• フィールド選択：事前計算してキャッシュし、即座にアクセスできます
• メモリ使用量：メモリ使用量を最小限に抑えた効率的なキャッシュ

最適化機能

• フィールド選択のキャッシュ：フィールド選択の重複計算を排除します
• スキーマのキャッシュ：再起動を高速化するための、任意のスキーマ永続化
• 最小限の 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

カスタムスキーマの例

// 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.が開発・保守しています。

Issue • ディスカッション

OneGrep チームが ❤️ を込めて作成