Testcollab Mcp Server

TestCollab MCP サーバー

AI コーディングアシスタントをTestCollabに接続して、Claude、Cursor、Windsurf、Codex、または MCP 対応クライアントからテストケース、テスト計画、スイートを直接管理できます。

クイックスタート

1. API トークンを取得する

TestCollab にログインし、My Profile Settings → API Token タブ → Generate new API token を選択します。

2. MCP クライアントにサーバーを追加する

Claude Code — プロジェクトのルートにある .mcp.json に追加します。

{
  "mcpServers": {
    "testcollab": {
      "command": "npx",
      "args": ["-y", "@testcollab/mcp-server"],
      "env": {
        "TC_API_TOKEN": "your-api-token",
        "TC_API_URL": "https://api.testcollab.io",
        "TC_DEFAULT_PROJECT": "16"
      }
    }
  }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "testcollab": {
      "command": "npx",
      "args": ["-y", "@testcollab/mcp-server"],
      "env": {
        "TC_API_TOKEN": "your-api-token",
        "TC_API_URL": "https://api.testcollab.io",
        "TC_DEFAULT_PROJECT": "16"
      }
    }
  }
}

Codex - コマンドラインから TestCollab を登録します。

codex mcp add testcollab \
  --env TC_API_TOKEN=your-api-token \
  --env TC_API_URL=https://api.testcollab.io \
  --env TC_DEFAULT_PROJECT=16 \
  -- npx -y @testcollab/mcp-server

または、すべてのプロジェクトで使用する場合は ~/.codex/config.toml に、信頼済みプロジェクトで使用する場合は .codex/config.toml にサーバーを追加します。

[mcp_servers.testcollab]
command = "npx"
args = ["-y", "@testcollab/mcp-server"]

[mcp_servers.testcollab.env]
TC_API_TOKEN = "your-api-token"
TC_API_URL = "https://api.testcollab.io"
TC_DEFAULT_PROJECT = "16"

codex mcp list を実行して、サーバーが設定されていることを確認します。設定のスコープや追加オプションについては、Codex の公式 MCP ドキュメントを参照してください。

Cursor — プロジェクトのルートにある .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "testcollab": {
      "command": "npx",
      "args": ["-y", "@testcollab/mcp-server"],
      "env": {
        "TC_API_TOKEN": "your-api-token",
        "TC_API_URL": "https://api.testcollab.io",
        "TC_DEFAULT_PROJECT": "16"
      }
    }
  }
}

手動テスト

TC_API_TOKEN=your-token npm start

利用可能なツール

list_test_cases

オプションのフィルターを指定して、プロジェクトのテストケースを一覧表示します。

パラメーター：

名前	型	必須	説明
project_id	number	いいえ*	プロジェクト ID（*TC_DEFAULT_PROJECT が設定されていない場合は必須）
suite	number|string	いいえ	スイート ID またはタイトルで絞り込みます
filter	object	いいえ	絞り込み条件
sort	array	いいえ	並べ替えの指定
limit	number	いいえ	最大件数（1～100、デフォルト：50）
offset	number	いいえ	先頭からスキップする件数（デフォルト：0）

3. 動作を確認する

クライアントを再起動してから、次のように尋ねます。「TestCollab でどのようなツールを使えますか？」

TestCollab のツール一覧が表示されます。次のように試してみてください。「すべてのテストケースを表示して」。

設定

変数	必須	デフォルト	説明
TC_API_TOKEN	はい	—	TestCollab のプロフィールにある API トークン
TC_API_URL	いいえ	https://api.testcollab.io	TestCollab API のベース URL
TC_DEFAULT_PROJECT	いいえ	—	デフォルトのプロジェクト ID（すべてのツール呼び出しで project_id を省略できます）

EU リージョン： TestCollab アカウントが EU でホストされている場合は、TC_API_URL に https://api-eu.testcollab.io を指定してください。

できること

ツール	説明
get_project_context	スイート、タグ、カスタムフィールド、要件、テスト計画フォルダー、リリース、ユーザーを取得します — 最初に呼び出してください
list_test_cases	フィルタリング、並べ替え、ページネーションを使ってテストケースを検索します
get_test_case	すべてのステップの詳細を含むテストケースを取得します
create_test_case	ステップ、タグ、カスタムフィールドを指定してテストケースを作成します
update_test_case	テストケースの任意のフィールドを更新します
list_test_plans	フィルタリング／並べ替えを使ってテスト計画を一覧表示します（リリース ID／タイトルによるフィルターを含む）
get_test_plan	含まれるテストケース数、構成、実行、現在の進捗状況、リリース情報を含むテスト計画を取得します
create_test_plan	ID、セレクター、またはタグ ID／名前で選択したケースを使ってテスト計画を作成します。上書きしない限り、デフォルトの担当者を維持します
get_test_plan_cases	実行に含まれるケースのステップ、期待結果、構成のステータス、割り当てられた実行 ID を取得します
report_test_case_result	ステータス、コメント、ミリ秒、ステップ結果、エビデンスファイルを指定して、1 件の実行を記録します
report_results	構造化された一括結果を報告し、計画のカスタムフィールドを設定します。省略された割り当てを任意でスキップできます
update_test_plan	テスト計画のメタデータ、ステータス、割り当て、リリースとの関連付けを更新します
delete_test_plan	テスト計画を削除します
list_suites	プロジェクト内のすべてのテストスイートを一覧表示します（title、parent、description フィルターに対応）
get_suite	スイートの詳細を取得します
create_suite	新しいスイートを作成します
update_suite	スイートを更新します
delete_suite	スイートを削除します
move_suite	スイートを別の親に移動します
reorder_suites	親の配下でスイートの順序を変更します

プロンプト例

"Show me all high-priority test cases in the Login suite"

"Create a test case for verifying password reset with 5 steps"

"List all test plans created this week"

"Create a regression test plan with all test cases tagged 'smoke'"

"Move the Payment suite under the Checkout suite"

詳細なワークフローについては、ユースケースを参照してください。

MCP 経由で計画を実行する

既存の作成フローを使ってタグ付きの計画を作成します。

{
  "title":"Smoke tests",
  "test_cases":{"tag_name":"Smoke","assignee":"me"},
  "override_assignees":false
}

test_cases.tag_id を指定すると、代わりに数値のプロジェクトタグが選択されます。タグ参照は 1 つ使用してください。タグの選択には追加の selector フィルターを含めることができ、明示的な test_case_ids とは別に指定します。既存のケース、構成、割り当て、リリース、フォルダー、カスタムフィールドのオプションも引き続き利用できます。override_assignees を省略するか false にすると、デフォルトのケース担当者が維持され、指定した担当者は未割り当てのケースにのみ設定されます。デフォルトの担当者を置き換えるには true に設定します。

test_plan_id を指定して get_test_plan_cases を呼び出します。トークン所有者に割り当てられた実行 ID と、実行の改訂ステップを取得するには、run_id も指定してください。応答には testCases、configurations、有効な systemName 値を含む statuses、および executions が含まれます。これらの内部 ID を使用してください。TC- 表示番号は別の ID です。

データ駆動型ケースでは、各ケースに id、name、parameters、rows（index と values）を含む datasets が含まれます。各実行には、保存済みの datasets と datasetResults が含まれます。実行では、そのスナップショットを使用してください。後からライブラリを編集すると、ケースの現在のデータセットが変わる可能性があります。

割り当てられた実行を 1 件、report_test_case_result で報告します。

{
  "run_id":365,
  "executed_test_case_id":53404,
  "status":"passed",
  "comment":"Login succeeded",
  "time_taken":1200,
  "step_results":[{
    "step":"Sign in","expected_result":"Home page appears","status":"passed",
    "attachments":[{"file_name":"step.log","content_base64":"T2sK"}]
  }],
  "attachments":[{"file_name":"run.log","content_base64":"T2sK"}]
}

step_results は位置に基づいて実行のステップと照合されます。保存された各ステップのテキストと期待結果は維持され、送信したステータスとコメントが適用されます。送信しなかったステップにはケースのステータスが適用されます。各ステップにつき、結果は最大 1 件送信してください。ステータスには、カスタムステータスを含む有効なシステム名を使用します。time_taken は ミリ秒 を加算します（CLI の tc reportCase --time-taken は秒を受け取ります）。実行者はトークンによって決まり、結果には execution_source: agent（実行モード列では「Agent」）と execution_context.tool: tc-mcp-server が記録されます。TestCollab は agent の結果を機械実行としてカウントします。

各 step_results 項目では、トップレベルのリストと同じ形式の attachments リストを任意で指定できます。ステップファイルはそのステップの下に表示され、以前に保存したステップファイルは保持されます。トップレベルのファイルは結果全体に属します。 添付できるファイルは、結果、ステップ、データセットの行を合わせて、1 回の呼び出しにつき最大 10 個です。stdio モードでは、10 MB 以下のローカルの通常ファイルに対して、{"file_path":"/path/to/screenshot.png"} を使用してください。 file_name と標準形式のパディング済み content_base64 を使うこともできます。この場合、ファイルごとのデコード後のサイズは最大 1 MB です。データ URL のプレフィックスは省略してください。任意の mime_type を指定すると、ファイル拡張子による判定を上書きできます。

データ駆動型の実行では、step_results の代わりに dataset_results を送信します。

{
  "run_id":365,
  "executed_test_case_id":53404,
  "status":"failed",
  "dataset_results":[
    {"dataset_id":7,"dataset_row_index":0,"step_index":0,"status":"passed"},
    {"dataset_id":7,"dataset_row_index":1,"step_index":0,"status":"failed",
     "comment":"This account could not sign in",
     "attachments":[{"file_name":"failure.log","content_base64":"T2sK"}]}
  ]
}

実行の datasetResults から dataset_id、dataset_row_index、step_index をコピーしてください。インデックスは 0 から始まります。指定した各エントリーで変更されるのは、その行とステップのみです。報告されていないエントリーのステータス、コメント、ファイルはそのまま保持されます。新しいファイルは、選択したエントリーの既存ファイルに追加されます。10 個のファイル上限は、トップレベル、ステップ、行のファイルを合算した数です。ケースの status は、プロジェクトのステータス体系において、保存済みのすべての行ステータス以上の順位である必要があります。重複または不明な座標、および非アクティブなステータスは、アップロードや書き込みの前に拒否されます。行の結果にファイル ID を保存する前に、行ファイルがアップロードされ、実行にリンクされます。その後、結果の書き込みに失敗した場合、それらのファイルは実行にリンクされたままになり、時間は加算されません。

無効なエビデンスは、結果を書き込む前にチェックされます。結果の保存後にエラーが発生した場合は、時間またはエビデンスの更新失敗が示されます。時間の更新を再試行すると、二重に加算される可能性があります。ファイル ID をステップに保存する前に、ステップファイルがアップロードされ、実行にリンクされます。アップロードまたはリンクに失敗した場合、結果と時間は更新されません。

report_results では、test_plan_id と空でない results 配列を渡してください。

{
  "test_plan_id":131,
  "results":[{"test_case_id":1724,"configuration_id":9,"status":"passed","time_taken":1200}],
  "skip_missing":true,
  "custom_fields":[{"id":5,"name":"environment_text","value":"staging","valueLabel":"staging"}]
}

任意の run_id を指定すると、その実行が選択されます。指定しない場合は、最新の実行が使用されます。呼び出し元に割り当てられた実行は、内部のケース ID と構成 ID によって照合されます。割り当て済みの実行が複数一致する場合は、configuration_id が必要です。無効な対象と重複する対象は、書き込み前に拒否されます。カスタムフィールドには、API ID、システム名、型付きの値を使用します。指定されていない既存の値は保持されます。skip_missing を指定すると、指定した結果の処理が成功した後、呼び出し元に割り当てられているものの省略された実行はスキップとしてマークされます。レスポンスには、確認済みの結果、スキップされた ID、実行ごとのエラーが一覧表示されます。一部失敗時は、再試行する前に内容を確認してください。エビデンスは、report_test_case_result を使って一括で添付できます。ファイル解析、自動作成、ビルドは、この実行フローの対象外です。

実行アーキテクチャと検証を参照してください。

ローカル開発環境のセットアップ

コントリビュートする場合、または npx ではなくソースから実行する場合：

git clone <repo-url>
cd tc-mcp-server
npm install
npm run build

次に、ビルドしたファイルを MCP クライアントに指定します。

{
  "mcpServers": {
    "testcollab": {
      "command": "node",
      "args": ["/path/to/tc-mcp-server/dist/index.js"],
      "env": {
        "TC_API_TOKEN": "your-api-token",
        "TC_API_URL": "http://localhost:1337",
        "TC_DEFAULT_PROJECT": "16"
      }
    }
  }
}

開発コマンド

npm run dev          # Watch mode with hot reload
npm run build        # Compile TypeScript
npm test             # Run tests
npm run typecheck    # Type check
npm run lint         # Lint

トラブルシューティング

サーバーがクライアントに表示されない場合

• 設定を追加した後、クライアントを再起動してください
• Node.js 20+ がインストールされていることを確認してください：node --version
• 手動でテストしてください：TC_API_TOKEN=your-token npx @testcollab/mcp-server

認証エラー

• API トークンが有効で、期限切れでないことを確認してください
• TC_API_URL が正しいサーバーを指していることを確認してください

「project_id is required」エラー

• 環境設定で TC_DEFAULT_PROJECT を設定するか、
• プロンプトでプロジェクトを指定してください：「プロジェクト 16 のテストケースを表示して」

ライセンス

MIT