🚀 MCP GraphQL Forge

MCP GraphQL Forgeは、GraphQL APIをAIツールが利用できるようにするMCPサーバーです。GraphQLスキーマのイントロスペクションから自動的にMCPツールを生成し、パラメータの検証やエラー処理を行い、開発と本番環境での使用に適したstdioとHTTPの両方のトランスポートをサポートします。また、スキーマとフィールド選択をキャッシュすることで、一貫したパフォーマンスを実現します。

🚀 クイックスタート

クイックインストール

代替インストール方法

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

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

✨ 主な機能

• ツール生成：GraphQLスキーマのイントロスペクションからMCPツールを作成します。
• パラメータ検証：多層検証により、GraphQLエラーを防止します。
• 双方向トランスポート：stdio（AIツール用）とHTTP（開発/テスト用）の両方をサポートします。
• スキーマ管理：オプションで事前イントロスペクションとキャッシュを行います。
• 認証：認証済みエンドポイントの柔軟なヘッダー構成 [実験的]

📦 インストール

HTTPモードでのクイックスタート（開発用に推奨）

1. サーバーを起動する

   # Streamable 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
   
   # または1行で実行する
   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_ENDPOINT="https://your-api.com/graphql" npx -y @toolprint/mcp-graphql-forge --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 --watch

📚 ドキュメント

CLIオプション

mcp-graphql-forge [options]

Options:
  --transport <type>     トランスポートタイプ: stdioまたはhttp (デフォルト: stdio)
  --port <number>        HTTPトランスポートのポート (デフォルト: 3000)
  --no-introspection     スキーマのイントロスペクションをスキップする (キャッシュされたスキーマを使用)
  --version              バージョン番号を表示する
  --help                 ヘルプを表示する

環境変数

生成されたツールのスキーマ

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

{
  name: "query_user",
  description: "Execute GraphQL query: 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 Streamable 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変数エラーを防止します。
• Null/Undefinedチェック：パラメータの存在と値を検証します。
• プロトタイプ汚染防止：安全なプロパティチェック方法を使用します。

スキーマセキュリティ

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

🚀 パフォーマンス

ベンチマーク

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

最適化機能

• フィールド選択キャッシュ：冗長なフィールド選択の計算を排除します。
• スキーマキャッシュ：オプションでスキーマを永続化し、再起動を高速化します。
• 最小限のGraphQLクエリ：必要なフィールドのみを要求します。
• コネクションプーリング：効率的なHTTPクライアント管理です。

🤝 コントリビュート

コントリビューションを歓迎します！詳細については、Contributing Guideを参照してください。

開発環境のセットアップ

# リポジトリをクローンする
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%テストカバレッジ：包括的なテストスイートです。

📖 実例

実世界での使用例

</details>

<details>
<summary>🔸 <strong>GitHub APIとの統合</strong></summary>
```bash
# 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

</details>

### カスタムスキーマの例
```typescript
// 例: ブログプラットフォームのスキーマ
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) ← 必須パラメータが強制されます