TestChimp

@testchimp/cli

TestChimp CLI および、TESTCHIMP-API-KEY を使用して TestChimp /api/mcp/* エンドポイントを呼び出す MCP サーバーです。

このリポジトリのフォルダー名は、ローカルでは引き続き testchimp-mcp-client になっている場合がありますが、公開されている npm パッケージは @testchimp/cli です。

インストール

npm install -D @testchimp/cli@latest

MCP（Cursor、Claude Code、VS Code などのエージェント）

ホストが次のコマンドを実行するようにサーバーを登録します。

npx -y @testchimp/cli@latest mcp

mcpServers.testchimp の設定例：

{
  "command": "npx",
  "args": ["-y", "@testchimp/cli@latest", "mcp"],
  "env": {
    "TESTCHIMP_API_KEY": "your-project-key",
    "TESTCHIMP_BACKEND_URL": ""
  }
}

設定のファイルパスはホストによって異なります（例：Cursor では通常 <repo>/.cursor/mcp.json を使用します）。ツール名には ケバブケースを使用します（例：get-requirement-coverage、create-user-story）。

CLI

export TESTCHIMP_API_KEY=...   # required unless TESTCHIMP_OAUTH_TOKEN is set (often read from project MCP env; never commit keys)
testchimp --help
testchimp get-requirement-coverage --branch-name main --help
testchimp create-user-story --platform-file-path plans/stories/foo.md --title "Checkout"
testchimp list-screen-states --json-input '{}'
testchimp upsert-screen-states --json-input '{"screenStates":[{"screen":"Checkout","states":["empty","filled"]}]}'
testchimp list-perf-runs --testchimp-id TC-123 --kind JOURNEY --limit 20
testchimp list-perf-runs --run-id 01ABC --include-raw
testchimp promote-perf-baseline --run-id 01ABC --env-class CI
testchimp compare-perf-to-baseline --run-id 01ABC --max-p95-regression-percent 10
testchimp list-related-perf-tests --scenario-titles "Checkout,Refund"
testchimp list-api-operation-interactions --operation-id 01XYZ --interaction-type REAL --limit 100
testchimp list-meetings --include-filter-options
testchimp list-meetings --from 2026-09-01 --to 2026-09-30 --domain customer.com --label Sales --search "pricing"
testchimp get-meeting-transcript --meeting-id <meeting-id> --summary-only
testchimp ephemeral-environment --action PROVISION --branch-name feat --no-wait
testchimp report-scan-findings --id scan-1 --scanner DAST --report-file zap.json
testchimp upsert-issue --title "Broken checkout"
testchimp list-issues --status ACTIVE --limit 10
testchimp get-release --release 1.2.0
testchimp upsert-release --release 1.2.0
testchimp manage-test-run --release 1.2.0 --title "Sprint 12"

• 標準出力： API のレスポンス JSON。
• 標準エラー出力： ephemeral-environment --action PROVISION で待機している間の進行状況（「まだ待機中…」のポーリング）。作成／デプロイのトリガーのみを実行する場合は、--no-wait を指定します。
• パフォーマンスゲート： compare-perf-to-baseline は JSON レスポンスを出力しますが、regressed が true（トップレベルまたは comparison 内）の場合はゼロ以外の終了コードを返します。
• ミーティング： list-meetings はチーム全体の Meeting Bots ミーティングのみを対象とします（Meetings ページと同じフィルター）。--include-filter-options を指定すると、ラベル／参加者／ドメインの一覧が返されます。--from／--to には YYYY-MM-DD（ローカル日付で両端を含む）、ISO 日時、またはエポックミリ秒を指定します。--label、--participant、--domain は複数回指定するか、カンマ区切りで指定できます。
• フラグ： 各サブコマンドのデフォルト値。--json-input '<json>' または --json-input @file.json を指定すると、フラグの値にマージされます（競合する場合は JSON が優先されます）。ネストされたボディ（例：TrueCoverage スコープ）には JSON を使用してください。
• リリースラベル： get-release、upsert-release、manage-test-run およびその他のリリースフィルターコマンドでは、--release <label>（別名 --release-version）を使用します。--version／-V は CLI のバージョンのみを表示します。

認証と環境

変数	用途
TESTCHIMP_API_KEY	プロジェクトの API キー（TestChimp-Api-Key として送信）。TESTCHIMP_OAUTH_TOKEN が設定されていない場合は必須です。
TESTCHIMP_OAUTH_TOKEN	featureservice が発行する OAuth 2.1 アクセストークン（Authorization: Bearer として送信）。両方が設定されている場合は両方が送信され、バックエンドでは Bearer が優先されます。
TESTCHIMP_BOT_ID	QA ボット ID（帰属情報として bot-id ヘッダーで送信）。スペースを含まない、1～64 文字の印字可能な ASCII 文字である必要があります。それ以外の場合は警告とともに無視されます。
TESTCHIMP_BACKEND_URL	Featureservice のベース URL（デフォルトは https://featureservice.testchimp.io）。
TESTCHIMP_INGRESS_URL	ボットイベントの ACK に使用する Ingress のベース URL（デフォルトは https://ingress.testchimp.io）。
TESTCHIMP_HOME	projects.json を格納する TestChimp Studio／CLI のホームディレクトリ（デフォルトは ~/.testchimp）。

ワークスペースフォルダーのマッピング

現在のユーザーのローカルリポジトリフォルダーを TestChimp プロジェクトにマッピングします。マッピングは ~/.testchimp/projects.json（または $TESTCHIMP_HOME/projects.json）に保存されます。このファイルは TestChimp Studio が使用するものと同じため、CLI からマッピングしたフォルダーは Studio とヘッドレスの AgentWatch デーモンにも表示されます。

testchimp workspace map --project-id <id> --folder ~/code/shop [--project-name "Shop"] [--reassign] [--skip-repo-check]
testchimp workspace get --project-id <id>        # prints the mapping JSON; exit 1 when unmapped

workspace map には Studio と同じルールが適用されます。

• フォルダーは存在し、Git のワークツリーである必要があります。パスは正規化された実パスとして保存されます。
• TESTCHIMP_API_KEY / TESTCHIMP_OAUTH_TOKEN が設定されている場合、CLI はプロジェクトに接続されたリポジトリ（get-git-folder-mapping）を読み込みます。接続されているリポジトリがある場合、フォルダーはリポジトリのルートであり、Git リモートのいずれかが一致する（大文字と小文字を区別しない owner/repo）必要があります。認証情報が設定されていない場合、リポジトリが接続されていない場合、または検索に失敗した場合は、標準エラーに注記を出してチェックをスキップします。この検索には認証情報に紐づくプロジェクトが使われるため、同じプロジェクトのキーまたはボットトークンで実行してください。--skip-repo-check を指定すると、検索全体をスキップします。
• フォルダーは1つのプロジェクトにのみ属します。--reassign を指定しない限り、2つ目のプロジェクトへのマッピングは失敗します。--reassign を指定するとフォルダーが移動され、古いプロジェクトにフォルダーがなくなる場合は、そのエントリーも削除されます。
• ファイルはアトミックに書き込まれます（一時ファイルを作成してから名前を変更）。モードは 0600 です。他のプロジェクトには影響せず、新しい Studio バージョンが書き込んだ未知のフィールドも保持されます。ファイルが有効な JSON でない場合、またはスキーマ v2 に一致しない場合は、projects.invalid.<millis>.json に移動され、空のレジストリに置き換えられます。スキーマ v1 のファイルは v2 に移行されます。

バイト単位の形式は fixtures/projects-registry/ で固定されており、Studio リポジトリにも同一のコピーがあります。両方のテストスイートで同じアップサートの一連の処理を再現し、出力バイトを比較します。

ローカルランナーのプロジェクトキー（workspace save-creds）

ローカルランナー（Playwright レポーター、この CLI、k6）には、環境内のプロジェクト API キーが必要です。TestChimp Studio は <repo>/.testchimp/mcp.json にキーを保存します。リモート MCP（OAuth）ユーザーも、リポジトリごとに同じファイルを一度書き込みます。

# CLI: copy TESTCHIMP_API_KEY from the environment (or fetch when TESTCHIMP_OAUTH_TOKEN is set)
testchimp workspace save-creds --folder . --project-id <id> \
  [--project-name "Shop"] [--backend-url <backendUrl>] [--ingress-url <ingressUrl>] [--reassign]

# Local stdio MCP: tool save-workspace-creds { folder, projectId? } — never returns the key
# Hosted / plugin: get-project-credentials, then write .testchimp/mcp.json with a file-write tool
# Legacy: pipe the key on stdin (never as a command-line argument)
printf '%s' "$KEY" | testchimp workspace save-creds --folder . --project-id <id>

• キーをコマンドに含めないでください。標準入力と TESTCHIMP_API_KEY は引き続き使用できます。キーが出力されることはありません。
• このファイルは Studio と完全に同じ形式を使います（fixtures/workspace-mcp-json/ で固定され、Studio リポジトリにも同じものが配置されています）。モードは 0600、.testchimp/ ディレクトリのモードは 0700 です。ファイル内の他のサーバー設定は保持され、.testchimp/ が .gitignore に追加されます。workspace map と同様に、フォルダーも projects.json にマッピングされます。
• 同じプロジェクトの既存エントリーは（Studio が管理するバイナリも含め）そのまま保持されます。キーが変更された場合にのみ更新されます。他のプロジェクトのエントリーがある場合は、--reassign が指定されない限り拒否されます。

フォールバック： TESTCHIMP_API_KEY と TESTCHIMP_OAUTH_TOKEN のどちらも設定されていない場合、CLI は現在のディレクトリまたはその上位にある最も近い .testchimp/mcp.json から TESTCHIMP_API_KEY、TESTCHIMP_PROJECT_ID、TESTCHIMP_BACKEND_URL、TESTCHIMP_INGRESS_URL を読み込みます。エクスポートされた環境変数は常に優先され、--bot のバインドには影響しません。このファイルはユーザー自身のみが読み取れる必要があります（Studio と save-creds が書き込む場合と同じモード 0600）。クローンしたリポジトリにコミットされたものなど、グループまたは全ユーザーが読み取れるコピーは、警告とともに無視されます。他のランナー（Playwright、k6）では、引き続き各自のシェルで環境変数をエクスポートする必要があります。

QA ボット

testchimp get-my-tasks --user-id <user-id>      # OAuth tokens imply the user
testchimp list-tests-awaiting-verification --limit 20
testchimp get-qa-posture
testchimp bot get-profile
testchimp bot register-profile --role QA_ENGINEER --responsibilities "Checkout + payments" \
  --capability E2E_AUTHORING --capability TEST_BATCH_FIX \
  --subscriptions-json '[{"eventType":"git-push","filters":[{"field":"author","op":"eq","value":"me"}]},{"eventType":"e2e-batch-completed"}]'
testchimp bot ack <eventId> [<eventId>...] --ack-url <delivery ackUrl>
testchimp bot compat --skill-version 1.0.53

bot ack は各 ID について eventId<TAB>status の行を1つ出力し、ステータスが BOT_ACK_UNKNOWN_EVENT、BOT_ACK_NOT_A_TARGET、BOT_ACK_MISSING_BOT_ID のいずれかである場合は、ゼロ以外の終了コードで終了します。明示的に指定する --ack-url は https である必要があります（localhost でのみ http を使用できます）。また、TestChimp ホスト、または TESTCHIMP_INGRESS_URL のホストを指定する必要があります。bot compat は終了コード0で終了し、デプロイに必要な最小バージョンと cliUpgradeRequired / skillUpgradeRequired を出力します。

TestChimp Studio を使用しない AgentWatch

testchimp bot connect --project-id <id>       # browser approval (OAuth, "agentwatch" scope)
testchimp bot connect --pair --project-id <id> # or: no browser, your QA bot approves (see below)
npx -y @testchimp/agentwatch query --project-id <id>
testchimp bot disconnect --project-id <id>    # forget the stored keys

ヘッドレス AgentWatch はユーザーとして動作するため、ユーザー ID、個人用アクセストークン、プロジェクト API キーが必要です。bot connect はループバックリダイレクトを使った OAuth 2.1 PKCE ログインを実行し、オプトインの agentwatch スコープを要求します（同意ページには、キーがローカルに保存されることが表示されます）。/bots/get_agentwatch_credentials からキーを取得し、バックエンド URL とイングレス URL とともに ~/.testchimp/agentwatch/credentials.json（モード 0600、プロジェクトごとに保存）に書き込みます。OAuth リフレッシュトークンはただちに失効させ、キーを表示することはありません。承認すると、プロジェクトも AgentWatch にオプトインされます。

ペアリング（2 回目のブラウザー同意は不要。QA ボットが使用）。 Use this connection as my QA bot を選択して承認された接続にはすべて agentwatch_pair スコープが含まれるため、別のブラウザーログインを行わず、ボットを経由させることもなく、キーをユーザーのコンピューターに送信できます。

1. ユーザーのコンピューターで、testchimp bot connect --pair [--project-id <id>] を実行します。ランダムな検証子が ~/.testchimp/agentwatch/pairing.json（0600）に保存され、{pairingCode, expiresAtMillis} が表示されます。コードは検証子の SHA-256（base64url）です。
2. ボットが独自のトークンを使って承認します。MCP ツール approve-agentwatch-pairing（または testchimp bot approve-pairing <code>）を使用します。
3. ユーザーのコンピューターで、testchimp bot connect --finish-pair を実行し、検証子を使って引き換えます（--timeout-ms の間、最大でデフォルトの 60 秒までポーリングします）。上記と同様にキーを保存し、保留中のファイルを削除します。

ペアリングは 1 回限りで、10 分後に期限切れになります。ボットに見えるのはペアリングコードだけであり、検証子がなければ役に立ちません。

リモート MCP（ストリーミング可能な HTTP）

testchimp mcp --http [--port 8080] [--host 0.0.0.0]

POST /mcp でステートレスなストリーミング可能 HTTP を提供します。すべてのリクエストに Authorization: Bearer <OAuth access token> を含める必要があります。呼び出し元のトークンは各ツール呼び出しで TestChimp に転送され、サーバー独自の TESTCHIMP_API_KEY／TESTCHIMP_OAUTH_TOKEN／TESTCHIMP_BOT_ID は使用されません。ベアラートークンのないリクエストには、WWW-Authenticate: Bearer resource_metadata="…" を含む 401 が返されます。その他のエンドポイントは GET /.well-known/oauth-protected-resource（RFC 9728 メタデータ）と GET /healthz です。リクエスト本文の上限は 1 MB です。

プロジェクトごとの URL。 POST /mcp?projectId=<id> は、すべてのツール呼び出しをそのプロジェクトに限定します。プロジェクトは TestChimp-Project-Id として送信され、TestChimp はトークンのユーザーがそのプロジェクトのメンバーであることを確認します（明示的な projectApiKey 引数が指定された場合は、そちらが優先されます）。リポジトリごとに URL を 1 つ登録します（例：{"url": "https://mcp.testchimp.io/mcp?projectId=<id>"}）。どのプロジェクトでも同じサインインを使用できます。401 チャレンジと保護リソースメタデータにはクエリが反映されるため、通知される resource は設定済みの URL と一致します。通常の /mcp は、引き続き同意ページで選択したプロジェクトを使用します。ホスト型／プラグイン型エージェントは、get-project-credentials を呼び出してランナーキーを取得し、ファイル書き込みツールを使って <repo>/.testchimp/mcp.json に書き込みます（ワークスペースフォルダーのマッピングを参照）。ローカルの stdio MCP では save-workspace-creds を呼び出せます。

変数	用途
PORT	--port が指定されていない場合のリッスンポート（デフォルトは 8080。Cloud Run によって設定されます）。
TESTCHIMP_MCP_PUBLIC_URL	このサーバーの公開ベース URL（例：https://mcp.testchimp.io）。保護リソースの resource と WWW-Authenticate に使用されます。デフォルトは、リクエストで転送されたプロトコルとホストです。
TESTCHIMP_OAUTH_ISSUER	メタデータに通知される認可サーバー（デフォルト：TESTCHIMP_BACKEND_URL）。
TESTCHIMP_BACKEND_URL / TESTCHIMP_INGRESS_URL	上流の TestChimp サービス。
TESTCHIMP_PUBLIC_BACKEND_URL / TESTCHIMP_PUBLIC_INGRESS_URL	上流 URL が内部向けの場合に、ローカルランナー用として get-project-credentials が返すホスト（デフォルトは上流 URL。イングレスは featureservice[-env].testchimp.io から導出されます）。

リポジトリの Dockerfile は、非 root ユーザーとして testchimp mcp --http を実行するイメージをビルドします（Cloud Run 対応）。

docker build -t testchimp-mcp .
docker run -p 8080:8080 -e TESTCHIMP_MCP_PUBLIC_URL=https://mcp.example.com testchimp-mcp

MCP API 2.0.0

@testchimp/cli 2.0.2 は TestChimp MCP API 2.0.0（88 個のツール）に対応しています。2.0.2 では ask-user-question-async が追加されました。2.0.0 では、すべての /api/mcp/* パス 70 個に加えて、ボット／ワークスペース用ヘルパーを含む 87 個のツールがリリースされました。1.x のいくつかのツールは統合されています。

旧ツール	新しいツール
provision-ephemeral-environment-and-wait	ephemeral-environment（action=PROVISION、wait のデフォルトは true）
report-dast-findings / report-sast-findings / …	report-scan-findings（scanner=DAST|SAST|DEPS|SECRETS）
list-workflow-executions / get-workflow-execution	get-workflow-executions
get-policy / list-policies	get-policies
list-api-operations / get-api-operation-detail	get-api-operations
create-issue / update-issue-status	upsert-issue
get-perf-run	list-perf-runs（runId）
get-release-details	get-release（version と detail=GATE を指定します。version を省略すると一覧が表示されます）

get-eaas-config は、単独の接続確認ツールとして維持されています。destroy-ephemeral-environment は変更されておらず、破壊的な操作のままです。完全な対応表は CHANGELOG.md と MIGRATION.md を参照してください。

testchimp-mcp-client からの移行

npm パッケージ testchimp-mcp-client は @testchimp/cli に置き換えられました。MCP の args を ["-y", "@testchimp/cli@latest", "mcp"] に更新し、ツール参照を ケバブケース に変更してください。MIGRATION.md を参照してください。

ライセンス

MIT