mcpField
G
graphql

graphql

github.com/crowdin開発1065 回インストール1 日前に更新
リポジトリ

graphql について

graphqlは、Crowdin GraphQLクエリの作成やエラー修正を支援するスキルです。実際のスキーマで利用できるフィールドと引数を重視し、ページネーション、フィルタリング、リクエスト規模の調整方法を案内します。

主な機能

  1. 01Crowdinスキーマに沿ったクエリ構築
  2. 02コネクションのページネーション引数確認
  3. 03カーソルページネーションの例
  4. 04フィルタリング・ソート・規模の指針
  5. 05未対応引数の修正

活用シーン

  1. 01Crowdinのプロジェクト、文字列、翻訳の照会
  2. 02コネクションクエリへのカーソルページネーション追加
  3. 03スキーマ非対応の引数エラーの調査
  4. 04ネストしたクエリのリクエスト規模の制限

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/crowdin/skills --skill graphql

インストール後、Claude Code で/graphqlを入力して読み込まれたか確認します。

同梱ファイルevals/evals.jsonreferences/common-fixes.md

詳細

Crowdin GraphQL クエリの作成

このスキルを使って、ライブスキーマに適合し、未サポートの引数を避け、実用的なページネーションとフィルタリングのパターンを含む、有効な Crowdin GraphQL クエリを作成します。

提供する内容

  1. 動作する GraphQL クエリ。
  2. クエリの仕組みに関する簡単な説明。
  3. 該当する場合は、ユーザーの壊れたクエリを修正したものと、問題点の簡単な説明。
  4. 任意：読みやすさが向上する場合は、変数オブジェクト。

基本的なワークフロー

1) 意図と範囲を確認する

次の項目を特定します。

  • 対象リソース（プロジェクト、文字列、翻訳など）。
  • 必須の条件（言語、日付、ステータス、ユーザー、承認状態）。
  • ユーザーが必要とする出力フィールド。

依頼が曖昧な場合は、保守的なデフォルトを選び、その旨を簡潔に伝えます。

2) スキーマに適合する基本要素から組み立てる

次の順に進めます。

  1. 対象のコネクションを実際に公開しているルートフィールドを選びます。
  2. すべてのコネクションに必須のページネーション引数（first または last）を追加します。
  3. ネストした選択（edges -> node）を追加し、要求されたフィールドのみを指定します。
  4. スキーマがサポートしている場合に限り、フィルタリングやソートを追加します。

REST のパラメーターから類推して引数を作り出さないでください。

3) Crowdin GraphQL の一般的な制約に照らして検証する

最終回答を作成する前に、次の点を確認します。

  • クエリ対象のすべてのコネクションに first または last（1..10000）が指定されている。
  • リクエストするノードの推定総数が 10,000 未満である。
  • ページネーションが必要になりそうな場合、クエリに pageInfo が含まれている。
  • フィールドで未サポートの引数を使っていない。
4) 安全なページネーションパターンを追加する

カーソルページネーションを推奨します。

  • 前方：first + after
  • 後方：last + before

ユーザーが「日付 X から日付 Y まで」と指定した場合、アドホックな引数ではなく、サポートされている filter 入力フィールドを使います（そのようなフィールドを公開しているリソースの場合）。

特に注意すべきミス

未知の引数エラー

ユーザーのクエリにスキーマにないフィールド引数が含まれている場合は、サポートされている代替手段を使うようにクエリを書き換えます。

実際にエラーが発生したアンチパターンの例：

  • translations(..., createdAfter: "...", createdBefore: "...")

修正方法：

  1. 未サポートの引数を削除します。
  2. languageId、first、after などのサポートされている引数は残します。
  3. 日付条件が必要な場合は、filter 入力を利用できるフィールドであればそこに条件を移します（または、このフィールドでは日付を直接フィルタリングできないことを説明します）。
必須のページネーション引数の欠落

Crowdin GraphQL のコネクションには first または last が必須です。省略しないでください。

過剰なデータ取得

理由なく、大量のネストされた結果を取得しないでください。ノード数の上限を考慮してください。

クエリパターン

パターン A：最小限で安全なコネクションクエリ
query GetProjects($first: Int!, $after: String) {
  viewer {
    projects(first: $first, after: $after) {
      edges {
        node {
          id
          name
        }
        cursor
      }
      pageInfo {
        hasNextPage
        endCursor
      }
      totalCount
    }
  }
}
パターン B：フィルタリング + 並べ替え（サポートされている場合）
query FilteredProjects {
  viewer {
    projects(
      first: 10
      filter: { createdAt: { gt: "2023-01-01T00:00:00Z" } }
      order: [{ lastActivityAt: asc }]
    ) {
      edges {
        node {
          id
          name
          lastActivityAt
        }
      }
    }
  }
}
パターン C：レート制限への配慮
query MeAndCost {
  viewer {
    username
  }
  rateLimit {
    limit
    cost
    remaining
    resetAt
  }
}

デバッグ用テンプレート

ユーザーがエラーを提示した場合は、次の形式で回答します。

  1. 原因：スキーマとの不一致を示す一文。
  2. 修正済みクエリ：修正したクエリ全体。
  3. これで動作する理由：スキーマのルールに関連した箇条書き 2～4 件。
  4. 日付フィルタリングが必要な場合：そのフィールドが日付フィルタリングをサポートしているかを説明します。サポートしていない場合は、最も近い有効な代替方法を提案します。

トーンと安全性

  • 「賢い」工夫よりも、正確さを優先します。
  • スキーマのサポート状況が不確かな場合は、「このフィールドについては Playground Explorer で確認してください」と明示します。
  • 引数が存在するかのように装わないでください。

参考資料

制約と例は、Crowdin のドキュメントに準拠させます。

コメント

Markdown 対応