QuerySculptor

⚒️ QuerySculptor

🚀 AI エージェント向け GraphQL クエリ生成ツール

AI エージェントが GraphQL クエリを直接生成するのではなく、構造化されたツールを使って GraphQL API とやり取りできるようにする MCP サーバーです。

QuerySculptor は Model Context Protocol（MCP）を通じて 26 個のツールを提供し、エージェントがクエリ文字列全体を生成するのではなく、段階的に GraphQL クエリを構築、検証、実行できるようにします。

仕組み

従来の方法：

• ハードコードされたクエリは柔軟性に欠け、保守も困難です
• GraphQL を直接生成すると、エラー率が高く、複雑な構文要件への対応も必要です
• エージェントは複雑なスキーマの関連性に苦労します
• 検証がないため、実行時に失敗します
• モノリシックなクエリは、一度にすべて構築する必要があります

QuerySculptor の方法：

• 段階的なクエリ構築と検証によるガイド付き構築
• リアルタイムのイントロスペクションと型安全性を備えたスキーマ認識
• 実行時ではなく構築中に問題を検出し、エラーを防止
• 会話型 AI のワークフローに適した段階的な構築
• Claude、Cursor、その他の MCP クライアントと互換性のある MCP 標準

Claude Sonnet モデルで最も効果を発揮します。他の LLM では結果が異なる場合があります。

📖 AI エージェント向け

QuerySculptor を初めて使いますか？

• 📋 エージェントシステムプロンプト - AI エージェント向けの完全ガイド
• ⚡ クイックリファレンス - 必須のワークフローとツール

🎯 課題と解決策

導入前：複雑な GraphQL 生成

# Agent tries to generate this complex query in one go:
query GetUserWithPostsAndComments($userId: ID!, $postLimit: Int = 10) {
  user(id: $userId) {
    id
    name
    email
    posts(first: $postLimit) {
      edges {
        node {
          id
          title
          content
          comments(first: 5) {
            edges {
              node {
                id
                content
                author {
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}

**結果：**構文エラー、誤った型、フィールドの不足、開発者の不満

導入後：QuerySculptor の方法

// Agent builds this incrementally with guided tools:
1. startQuerySession() 
2. introspectSchema()
3. selectField("user") 
4. setTypedArgument("id", userId)
5. selectField("user.name")
6. selectField("user.posts")
7. setTypedArgument("user.posts", "first", 10)
// ... continue building step by step
8. validateQuery() ✅
9. executeQuery() 🎉

**結果：**適切な形式のクエリ、構文エラーの削減、組み込みの検証

🌟 機能

🧠 スキーマイントロスペクション

• ライブでのスキーマ検出と API の把握
• 複雑なスキーマの型関連性のマッピング
• 利用可能なフィールドと要件を示す、フィールド単位の情報

🔧 ガイド付きクエリ構築

• 7 カテゴリに分類された 26 個のツール
• AI の推論ワークフローに適した段階的な構築
• 実行前にエラーを検出するリアルタイム検証
• 再利用可能なクエリコンポーネント向けのフラグメント対応

⚡ アーキテクチャ

• インタラクション間で状態を保持する Redis ベースのセッション
• API 保護のためのレート制限
• Vercel へのデプロイに対応
• エージェントのようなワークフローのテストを含む、包括的なテストカバレッジ
• インラインフラグメント操作の信頼性を高めるセッション永続化の修正

🤝 互換性

• MCP 標準に準拠。Claude Desktop、Cursor、その他の MCP クライアントで動作
• TypeScript ネイティブで、完全な型安全性を備えています

📋 要件

QuerySculptor では、セッション管理とクエリ状態の永続化に Redis が必要です。

Redis の選択肢：

• Upstash - サーバーレス Redis（本番環境に推奨）
• ローカル Redis - 開発用（redis-server）
• Docker Redis - docker run -d -p 6379:6379 redis:alpine
• 任意の Redis プロバイダー - AWS ElastiCache、Google Cloud Memorystore など

🎪 デモとセットアップ

🌍 公開デモ

MCP エンドポイント： https://querysculptor.com/mcp

デモでは、QuerySculptor の機能をテストするために Pokemon API を使用するよう事前設定されています。

💬 Query Sculptor Chat で Pokemon GraphQL API を利用： QuerySculptor Chat - QuerySculptor MCP サーバーを利用して、Pokemon の GraphQL API とチャット

🎮 デモ：Pokemon API の例

デモでは Pokemon API を使用します。次のような質問ができます。

Pokemon を探す：

• 「最初の 10 匹の Pokemon と、それぞれのタイプやスプライトを表示して」
• 「ほのおタイプとひこうタイプの両方を持つ Pokemon をすべて探して」
• 「リザードンのステータスは？」

特性とわざを調べる：

• 「すべての Pokemon の特性と効果を一覧表示して」
• 「ピカチュウが覚えられるわざは？」
• 「でんきタイプのわざをすべて、威力と命中率とともに表示して」

地域と種族のデータ：

• 「カントー地方の Pokemon をすべて一覧表示して」
• 「進化の系統とともに Pokemon の種族を表示して」
• 「利用できるきのみと、その効果は？」

複雑なクエリ：

• 「ピンチのときに攻撃を上げる特性を持つ Pokemon を探して」
• 「伝説の Pokemon をすべて、タイプと種族値とともに表示して」
• 「みずタイプとこおりタイプの両方のわざを覚えられる Pokemon を一覧表示して」

Cursor の mcp.json に追加します：

{
  "mcpServers": {
    "graphql-query-builder-demo": {
      "url": "https://querysculptor.com/mcp"
    }
  }
}

🏃‍♂️ ローカルセットアップ

# Clone and setup
git clone https://github.com/flinstonedev/querysculptor.git
cd querysculptor
pnpm install

# Configure (copy example.env to .env and customize)
cp example.env .env

# Launch
vercel dev
# 🚀 Your MCP server is live at http://localhost:3000/mcp

カスタムエンドポイントとベアラートークンを設定するには、.env ファイルを編集します：

DEFAULT_GRAPHQL_ENDPOINT=https://your-api.com/graphql
DEFAULT_GRAPHQL_HEADERS={"Authorization": "Bearer your_token"}

🎯 ユースケース

🔍 データの発見

「エージェントさん、先週投稿したユーザーをすべて見つけて、人気のコメントを表示してください。」

エージェントは QuerySculptor を使用して、次の処理を行います：

1. あらゆる GraphQL API をイントロスペクションする
2. ユーザー、投稿、コメントを対象とするクエリを作成する
3. 適切な構文と構造で実行する

💬 自然言語から GraphQL へ

チャットボットを GraphQL 対応のエージェントに変換します：

• ユーザー：「最近のフィクションで 20 ドル未満の本を表示して」
• エージェント： QuerySculptor のツールを使って書店の API にクエリを実行します
• 結果： クエリを手動で記述せずに、構造化データを取得します

📊 レポートの自動生成

ビジネスインサイトを生成するエージェントを作成します：

• E コマース API から売上ダッシュボードを作成
• ソーシャルメディア API からユーザーエンゲージメントを取得
• あらゆる GraphQL ソースからパフォーマンス指標を取得

🛠️ 開発者ツール

• IDE 連携 - クエリの作成を支援する AI アシスタント
• API の探索 - あらゆる GraphQL API を発見して理解
• クエリの最適化 - AI が提案するパフォーマンス改善

🏗️ 利用可能なツール

7 カテゴリーにわたる 26 個のツール：

🔍 スキーマインテリジェンス（5 個のツール）

• introspect-schema - API スキーマの理解
• get-root-operation-types - エントリーポイントの発見
• get-type-info - 型の分析
• get-field-info - フィールドレベルの情報
• get-input-object-help - 入力オブジェクトのガイダンス

🎯 セッション管理（4 個のツール）

• start-query-session - セッションの初期化
• end-query-session - リソースのクリーンアップ
• get-current-query - クエリの表示
• get-selections - フィールドの候補

⚡ フィールド選択（3 個のツール）

• select-field - フィールドの指定
• select-multiple-fields - 一括操作
• select-field-simple - シンプルなフィールド選択

🧬 変数管理（3 個のツール）

• set-query-variable - 変数の定義
• set-variable-value - 値の割り当て
• remove-query-variable - 変数の削除

🎪 引数の処理（4 個のツール）

• set-string-argument - 文字列と列挙型の処理
• set-typed-argument - 数値、ブール値、複合型の処理
• set-input-object-argument - ネストされたオブジェクトの構築
• set-variable-argument - 変数参照

🎭 フラグメントのサポート（3 個のツール）

• define-named-fragment - 再利用可能なクエリコンポーネント
• apply-named-fragment - フラグメントの適用
• apply-inline-fragment - 型に応じた選択

🔮 ディレクティブのサポート（2 個のツール）

• set-field-directive - フィールドレベルのディレクティブ（@include、@skip）
• set-operation-directive - オペレーションレベルのディレクティブ

✅ 検証と実行（2 個のツール）

• validate-query - スキーマへの準拠を検証
• execute-query - クエリの実行

🌍 設定

🤝 Claude Desktop のセットアップ

QuerySculptor は、mcp-remote を通じて Claude Desktop と連携します。mcp-remote は、Claude Desktop とリモート MCP サーバーの間をつなぐブリッジとして機能します。

設定ファイルを編集します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

リモートデモの場合：

{
  "mcpServers": {
    "querysculptor": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://querysculptor.com/mcp"
      ]
    }
  }
}

ローカル開発の場合：

{
  "mcpServers": {
    "querysculptor-local": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3000/mcp",
        "--allow-http"
      ]
    }
  }
}

カスタムエンドポイントとベアラートークンを設定するには、設定に env を追加します。

{
  "mcpServers": {
    "querysculptor": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-querysculptor.vercel.app/mcp"],
      "env": {
        "DEFAULT_GRAPHQL_ENDPOINT": "https://your-api.com/graphql",
        "DEFAULT_GRAPHQL_HEADERS": "{\"Authorization\": \"Bearer your_token\"}"
      }
    }
  }
}

🔍 トラブルシューティング

問題が発生した場合は、次の手順をお試しください。

1. mcp-remote のキャッシュをクリアする：

   rm -rf ~/.mcp-auth
   

2. ログを確認する：

   • macOS/Linux：tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
   • Windows：Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20

3. 設定変更後は、Claude Desktop を完全に再起動します。

🚀 どこにでもデプロイ

⚡ Vercel（推奨）

ワンクリックでデプロイ：

デプロイ後、Vercel ダッシュボードで次の環境変数を設定します。

• REDIS_URL - Redis の接続文字列
• DEFAULT_GRAPHQL_ENDPOINT - GraphQL API のエンドポイント（任意）
• DEFAULT_GRAPHQL_HEADERS - 認証用ヘッダーを含む JSON 文字列（任意）

手動でデプロイ：

# Clone and deploy
git clone https://github.com/flinstonedev/querysculptor.git
cd querysculptor
vercel --prod

Vercel ダッシュボードで環境変数を設定します。

カスタムエンドポイントとベアラートークンを設定するには、Vercel の環境変数に次の項目を追加します。

DEFAULT_GRAPHQL_ENDPOINT=https://your-api.com/graphql
DEFAULT_GRAPHQL_HEADERS={"Authorization": "Bearer your_token"}

🧪 テスト

QuerySculptor には、包括的なテストフレームワークが含まれています。

標準テスト

pnpm test            # Run all tests
pnpm test:watch      # Watch mode
pnpm test:coverage   # Coverage report

エージェントのようなテスト

AI エージェントがツールを使用する場合とまったく同じ方法でテストします。

pnpm test:agent                  # Run all agent workflow tests
pnpm test:agent:basic           # Basic workflow tests
pnpm test:agent:debug           # Debug mode with detailed output
pnpm test:agent:errors          # Error scenario tests

エージェントテストフレームワークの機能：

• ✅ 実際の MCP プロトコル：実際の MCP 通信レイヤーを介してテストします
• ✅ セッションの永続化：Redis を利用したセッション管理を検証します
• ✅ ワークフローのシミュレーション：現実的な複数ステップのエージェントワークフローを実行します
• ✅ エラーからの回復：一般的な障害モードと回復パターンをテストします
• ✅ デバッグユーティリティ：詳細な分析およびデバッグ機能を提供します

セッションセキュリティの強化

• セッション ID の検証により、インジェクション攻撃を防止します
• 空白文字を適切に処理し、正規化します
• 無効なセッション形式に対して明確なエラーメッセージを表示します
• 既存の実装との後方互換性があります

📈 ロードマップ

• 適切なロギングの追加 - デバッグとモニタリングのための構造化ロギング
• クエリ最適化 AI - パフォーマンスを自動的に改善
• ビジュアルクエリビルダー - クエリを構築するための Web UI
• エージェントテストの強化 - エージェントワークフローのテスト範囲を拡大

🌟 コミュニティからの貢献を歓迎します

• ドキュメントの改善 - プロジェクトへの理解を深めるための支援
• ツールの機能強化 - 新しい機能を追加
• クライアントとの統合 - より多くの MCP クライアントをサポート
• パフォーマンスの最適化 - パフォーマンスを改善
• エージェントテストのシナリオ - 実際のワークフローに即したテストを追加