Gaffer

@gaffer-sh/mcp

Gaffer 用 MCP（Model Context Protocol）サーバーです。AI アシスタントにテストの記憶を持たせます。

これは何ですか？

この MCP サーバーは、Claude Code や Cursor などの AI コーディングアシスタントを、Gaffer のテスト履歴やカバレッジデータに接続します。コードモードで動作し、17 個の関数をまとめた名前空間を通じて 3 つの MCP ツールを提供します。内訳は、読み取り専用の分析関数が 16 個と、upload_test_results です。AI は次のことができます。

• プロジェクトのテスト状況（合格率、不安定なテスト、傾向）を確認する
• 特定のテストの履歴を調べ、安定性を把握する
• デバッグ時にテスト失敗に関するコンテキストを取得する
• コードカバレッジを分析し、テストされていない領域を特定する
• すべてのプロジェクトを参照する（ユーザー API キーを使用）
• テストレポートファイル（HTML レポート、カバレッジなど）にアクセスする

前提条件

1. テスト結果がアップロード済みの Gaffer アカウント
2. Account Settings > API Keys で取得した API キー

セットアップ

Claude Code（CLI）

Gaffer MCP サーバーを追加するには、Claude Code CLI を使うのが最も簡単です。

claude mcp add gaffer -e GAFFER_API_KEY=gaf_your_api_key_here -- npx -y @gaffer-sh/mcp

Claude Code（手動）

または、Claude Code の設定（~/.claude.json またはプロジェクトの .claude/settings.json）に追加します。

{
  "mcpServers": {
    "gaffer": {
      "command": "npx",
      "args": ["-y", "@gaffer-sh/mcp"],
      "env": {
        "GAFFER_API_KEY": "gaf_your_api_key_here"
      }
    }
  }
}

Cursor

プロジェクトの .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "gaffer": {
      "command": "npx",
      "args": ["-y", "@gaffer-sh/mcp"],
      "env": {
        "GAFFER_API_KEY": "gaf_your_api_key_here"
      }
    }
  }
}

このサーバーの仕組み

このサーバーはコードモードを使用します。API 呼び出しごとに MCP ツールを 1 つ公開するのではなく、3 つのツールと、JavaScript から呼び出す codemode 名前空間を公開します。ツール定義が少ないためコンテキストウィンドウを占有する領域が減り、1 回の実行で複数の呼び出しを連結できます。

MCP ツール	機能
execute_code	codemode.<function>() を使って JavaScript を実行します。API 呼び出しは最大 20 回、タイムアウトは 30 秒です。
search_tools	キーワードで利用可能な関数を検索します。空のクエリを指定すると、すべての関数が一覧表示されます。
list_projects	プロジェクトを一覧表示します。トークンがユーザー API キー（gaf_）の場合にのみ登録されます。

const health = await codemode.get_project_health({ projectId: "proj_abc" });
if (health.flakyTestCount > 0) {
  const flaky = await codemode.get_flaky_tests({ projectId: "proj_abc" });
  return { health, flaky };
}
return { health };

execute_code で利用できる関数

関数	カテゴリ	説明
get_project_health	health	健全性スコア、合格率、不安定なテストの数、傾向
get_test_history	testing	特定のテストの合格／失敗履歴
get_flaky_tests	testing	成功と失敗が頻繁に切り替わるテスト
list_test_runs	testing	最近のテスト実行。コミット／ブランチ／ステータスで絞り込み可能
get_test_run_details	testing	1 回のテスト実行における個別の結果を解析して取得
get_failure_clusters	testing	根本原因ごとに分類された失敗テスト
get_slowest_tests	testing	P95 実行時間が最も長いテスト
compare_test_metrics	testing	コミットまたはテスト実行間のテストパフォーマンスを比較
search_failures	testing	エラーまたはテスト名のパターンで失敗を検索するか、最近の失敗をすべて一覧表示
get_coverage_summary	coverage	カバレッジ全体の指標と傾向
get_coverage_for_file	coverage	特定のファイルまたはパスのカバレッジ
get_untested_files	coverage	カバレッジがしきい値を下回るファイル
find_uncovered_failure_areas	coverage	カバレッジが低く、かつテストが失敗しているファイル
get_report	reports	テスト実行のレポートファイル URL
get_report_browser_url	reports	ブラウザーで表示できる署名付きレポート URL（30 分間有効）
get_upload_status	uploads	CI の結果がアップロードされ、処理済みかどうか
upload_test_results	uploads	テスト結果をアップロード（書き込み） — レート制限が適用され、監査ログに記録されます

upload_test_results を除くすべての関数は読み取り専用です。

関数リファレンス

list_projects

アクセス可能なすべてのプロジェクトを一覧表示します。

• 入力： organizationId（任意）、limit（任意、既定値：50）
• 戻り値： ID、名前、組織情報を含むプロジェクトの一覧
• 例：「Gaffer で利用できるプロジェクトは何ですか？」

get_project_health

プロジェクトの健全性指標を取得します。

• 入力： projectId（必須）、days（任意、既定値：30）
• 戻り値： 健全性スコア（0～100）、合格率、テスト実行回数、不安定なテストの数、傾向
• 例：「テストスイートの健全性はどうですか？」

get_test_history

特定のテストの合格／失敗履歴を取得します。

• 入力: projectId（必須）、testName または filePath（いずれか必須）、limit（任意）
• 戻り値: ステータス、実行時間、ブランチ、コミット、エラーを含む実行履歴
• 例: 「ログインテストは不安定ですか？履歴を確認してください」

get_flaky_tests

プロジェクト内の不安定なテストの一覧を取得します。

• 入力: projectId（必須）、threshold（任意、デフォルト：0.1）、days（任意）、limit（任意）
• 戻り値: 反転率、遷移回数、実行回数を含む不安定なテストの一覧
• 例: 「プロジェクト内で不安定なテストはどれですか？」

list_test_runs

任意のフィルタリング条件を指定して、最近のテスト実行を一覧表示します。

• 入力: projectId（必須）、commitSha（任意）、branch（任意）、status（任意）、limit（任意）
• 戻り値: 合格／失敗／スキップの件数と、コミットおよびブランチの情報を含むテスト実行の一覧
• 例: 「直近のコミットで失敗したテストは何ですか？」

get_test_run_details

特定のテスト実行について、解析済みのテスト結果を取得します。

• 入力: testRunId（必須）、projectId（必須）、status（任意のフィルター）、limit（任意）
• 戻り値: 名前、ステータス、実行時間、ファイルパス、エラーを含む個別のテスト結果
• 例: 「このテスト実行で失敗したテストをすべて表示してください」

get_report

テスト実行に伴ってアップロードされたレポートファイルの URL を取得します。

• 入力: testRunId（必須）
• 戻り値: ファイル名、サイズ、コンテンツタイプ、ダウンロード URL を含むファイルの一覧
• 例: 「最新のテスト実行の Playwright レポートを取得してください」

get_report_browser_url

テストレポートを表示するための、ブラウザーで開ける URL を取得します。

• 入力: projectId（必須）、testRunId（必須）、filename（任意）
• 戻り値: 30 分間有効な署名付き URL
• 例: 「テストレポートを表示するリンクをください」

get_slowest_tests

プロジェクト内で最も遅いテストを、P95 実行時間の順に取得します。

• 入力: projectId（必須）、days（任意）、limit（任意）、framework（任意）、branch（任意）
• 戻り値: 平均実行時間、P95 実行時間、実行回数を含むテストの一覧
• 例: 「CI パイプラインを遅くしているテストはどれですか？」

compare_test_metrics

2 つのコミットまたはテスト実行間のテストメトリクスを比較します。

• 入力: projectId（必須）、testName（必須）、beforeCommit／afterCommit または beforeRunId／afterRunId
• 戻り値: 実行時間の変化と変化率を含む、変更前／変更後のメトリクス
• 例: 「修正によってこのテストは速くなりましたか？」

get_coverage_summary

プロジェクトのカバレッジメトリクスの概要を取得します。

• 入力: projectId（必須）、days（任意、デフォルト：30）
• 戻り値: 行／ブランチ／関数のカバレッジ率、推移、レポート数、カバレッジが最も低いファイル
• 例: 「テストカバレッジはどのくらいですか？」

get_coverage_for_file

特定のファイルまたはパスのカバレッジメトリクスを取得します。

• 入力: projectId（必須）、filePath（必須 - 完全一致または部分一致）
• 戻り値: 行／ブランチ／関数のカバレッジを含む、一致したファイルの一覧
• 例: 「API ルートのカバレッジはどのくらいですか？」

get_untested_files

テストカバレッジがほとんどない、またはまったくないファイルを取得します。

• 入力: projectId（必須）、maxCoverage（任意、デフォルト：10%）、limit（任意）
• 戻り値: しきい値を下回るファイルを、カバレッジが低い順に並べた一覧
• 例: 「テストがないファイルはどれですか？」

find_uncovered_failure_areas

カバレッジが低く、かつテスト失敗もある（リスクの高い）コード領域を見つけます。

• 入力: projectId（必須）、days（任意）、coverageThreshold（任意、デフォルト：80%）
• 戻り値: ファイルパス、カバレッジ率、失敗回数とともに、スコア順に並べたリスク領域
• 例: 「テストに注力すべき箇所はどこですか？」

get_failure_clusters

エラーメッセージの類似性をもとに、失敗したテストを根本原因ごとにグループ化します。

• 入力： projectId（必須）、testRunId（必須）
• 戻り値： 類似するエラーメッセージごとにグループ化した、失敗したテストのクラスター。代表的なエラーとテスト件数を含みます
• 例：「この15件の失敗は同じバグが原因ですか？」

search_failures

エラーメッセージ、スタックトレース、テスト名で過去の失敗を検索します。検索語を省略すると、対象期間内のすべての失敗を一覧表示します。

• 入力： query（省略可。省略するとすべての失敗を返します）、projectId（gaf_ キーでは必須）、searchIn（省略可：errors／names／all、デフォルトは all）、days（省略可、デフォルトは30）、branch（省略可）、limit（省略可、デフォルトは20）
• 戻り値： 一致した失敗と、テスト名、エラーメッセージ、実行およびコミットのコンテキストを返します。スキャン上限により一覧が途中で切り詰められた場合は、truncated も返します
• 例：「この接続拒否エラーが以前にも発生したことはありますか？」／「過去7日間に失敗したものは何ですか？」

get_upload_status

CI の結果がアップロードされ、処理されたかどうかを確認します。

• 入力： projectId（必須）、sessionId（省略可）、commitSha（省略可）、branch（省略可）
• 戻り値： 処理状況、関連するテスト実行、カバレッジレポートを含むアップロードセッション
• 例：「コミット abc123 のテスト結果は準備できていますか？」

upload_test_results

構造化されたテスト結果をアップロードします。書き込みを行う関数はこれだけです。

CI 出力またはランナーの JSON レポートを解析した結果が手元にあり、それをアップロードするための Gaffer CLI が使えない場合に使用します。

• 入力： projectId（gaf_ キーでは必須）、framework（必須）、tests（必須）、branch、commitSha、ciProvider、startedAt、finishedAt、coverage
• 戻り値： uploadSessionId、生成された runId、算出された成功／失敗／スキップの概要
• 例：「解析済みのこの42件の pytest 結果をアップロードして、追跡できるようにしてください」

runId、実行時刻、概要は tests から算出されます。実際の経過時間が分かる場合に限り、startedAt／finishedAt を渡してください。

知っておくべき制約が2つあります。

• 冪等ではありません。 呼び出しごとに新しい実行が作成されるため、失敗したかどうか不明な場合に再試行すると重複が発生します。再試行する代わりに get_upload_status を確認してください。
• プロジェクトごとにレート制限があります。 また、各呼び出しは、呼び出しに使用した認証情報の ID とともにプロジェクトの監査ログに記録されます。

結果の処理は非同期で行われます。結果が読み取り関数から確認できるようになるまで、数秒かかります。

エージェント型 CI ワークフロー

これらのワークフローでは、AI エージェントが CI の失敗を診断し、結果を待ち、カバレッジの不足を見つける方法を示します。各ステップは codemode 関数なので、ステップごとに個別のラウンドトリップを行うのではなく、チェーン全体を1回の execute_code 呼び出し内で実行できます。

ワークフロー：CI の失敗を診断する

list_test_runs(projectId, status="failed")
  → get_test_run_details(projectId, testRunId, status="failed")
  → get_failure_clusters(projectId, testRunId)
  → get_test_history(projectId, testName="...")
  → compare_test_metrics(projectId, testName, beforeCommit, afterCommit)

1. 失敗したテスト実行を見つける
2. スタックトレースを含む個々の失敗の詳細を取得する
3. 失敗を根本原因ごとにグループ化する。多くの場合、15件の失敗は2〜3件のバグが原因です
4. 各失敗が新規（リグレッション）か、再発したものかを確認する
5. 変更前後を比較して、修正を検証する

ワークフロー：結果を待つ

get_upload_status(projectId, commitSha="abc123")
  → poll until processingStatus="completed"
  → get_test_run_details(projectId, testRunId)

1. コミットの結果がアップロードされているか確認する
2. 処理が完了するまで待つ
3. 関連するテスト実行 ID を使用して結果を取得する

ワークフロー：カバレッジの不足を見つける

find_uncovered_failure_areas(projectId)
  → get_untested_files(projectId)
  → get_coverage_for_file(projectId, filePath="src/critical/")

1. カバレッジが低く、テストが失敗しているファイルを見つける（最もリスクが高い）
2. カバレッジがまったくないファイルを見つける
3. 特定のディレクトリを詳しく調べ、対象を絞った分析を行う

関数のクイックリファレンス

エージェントへの質問	関数
「何が失敗しましたか？」	get_test_run_details
「同じ根本原因ですか？」	get_failure_clusters
「このエラーは以前にも発生しましたか？」	search_failures
「不安定なテストですか？」	get_flaky_tests
「これは新しい問題ですか？」	get_test_history
「修正は機能しましたか？」	compare_test_metrics
「結果は準備できていますか？」	get_upload_status
「テストされていない箇所はどこですか？」	find_uncovered_failure_areas
「遅いものはどれですか？」	get_slowest_tests

カバレッジ改善の優先順位付け

カバレッジツールを使ってテストスイートを改善する場合は、最良の結果を得るために、カバレッジデータとコードベースの調査を組み合わせてください。

1. コードの利用状況を把握する

カバレッジ率だけを基準に対象ファイルを選ぶ前に、実際に重要なコードを調べてください。

• エントリーポイントを探す： ルート定義、イベントハンドラー、エクスポートされた関数を確認します。これらから、本番環境で実行されるコードがわかります
• 多くのファイルからインポートされているファイルを探す： 多数のファイルからインポートされているファイルは、優先度の高い対象です
• 重要なビジネスロジックを特定する： 認証、支払い、データの変更、または中核となるドメインロジックを扱うファイルを探します

2. 影響度に基づいて優先順位を付ける

カバレッジが低いだけでは、優先度は決まりません。次の点を考慮してください。

• 利用頻度が高く、カバレッジが低い = 最優先 - 頻繁に実行される一方で、テストが不足しているコード
• カバレッジが0%の大きなファイル - 未カバーの行が多いほど、全体のカバレッジへの影響が大きくなります
• 失敗があり、カバレッジも低いファイル - この場合は find_uncovered_failure_areas を使用します

3. パスベースのクエリを使用する

get_untested_files ツールは、多数のフロントエンドコンポーネントを返す場合があります。バックエンドや特定の領域については、次を使用してください。

# Query specific paths with get_coverage_for_file
get_coverage_for_file(filePath="server/services")
get_coverage_for_file(filePath="src/api")
get_coverage_for_file(filePath="lib/core")

4. 繰り返し改善する

1. get_coverage_summary でベースラインを取得します
2. 重要なパスに対して get_coverage_for_file を使い、対象を特定します
3. 影響度の最も高いファイルのテストを作成します
4. CI が新しい結果をアップロードした後、カバレッジを再確認します
5. 繰り返します

認証

ユーザー API キー（推奨）

ユーザー API キー（gaf_ プレフィックス）は、組織全体のすべてのプロジェクトへの読み取り専用アクセスを提供します。API キーは Account Settings > API Keys から取得してください。

プロジェクトトークン

プロジェクトトークン（gfr_ プレフィックス）は、テスト結果のアップロード用に設計されており、単一のプロジェクトにのみアクセスできます。プロジェクトトークンを使用する場合は、projectId を省略してください。自動的に解決されます。MCP サーバーでは、list_projects を有効にし、複数のプロジェクトを読み取れるユーザー API キーが推奨されます。

環境変数

変数	必須	説明
GAFFER_API_KEY	はい	Gaffer API キー（gaf_ で始まります）
GAFFER_API_URL	いいえ	API のベース URL（デフォルト：https://app.gaffer.sh）

ローカル開発

pnpm install
pnpm build

Claude Code でローカルテストを行います（ビルド済みファイルには絶対パスを使用してください）。

{
  "mcpServers": {
    "gaffer": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "GAFFER_API_KEY": "gaf_..."
      }
    }
  }
}

ライセンス

MIT