QA Copilot MCP Server

Model Context Protocol を実装したサーバーです。AI アシスタントに推測をさせるのではなく、Playwright の実行を要約する、複数の実行にわたって flaky テストを検出する、失敗をヒューリスティックに説明する、Playwright テストの雛形を生成する、GitHub リポジトリの最近の CI 状況を取得する、といった具体的な QA／テストインテリジェンスツールの小さなセットを提供します。Claude Desktop、Claude Code、その他の MCP 互換ホストからこのサーバーを指定すれば、それらは自由文の推測ではなく、実際のツール呼び出しになります。

これは、QA 自動化ポートフォリオの中でも「AI に雰囲気ではなく実データを与える」部分に当たります。このポートフォリオ内の他のリポジトリ（healthcare-qa-automation-framework、healthcare-data-quality-framework）は Playwright の JSON レポートと CI 実行を生成しますが、このサーバーはそれらを、アシスタントが実際に照会できるものへと変換します。

この設計にした理由

• プロトコル配線は、素の関数の上に載せる薄い層に過ぎません。 各ツールの実際のロジックは src/playwright/、src/github/、src/tools/ に、小さく（ほぼ）純粋で、それぞれ単体テストされたモジュール群あります。src/index.ts はそれらを MCP SDK に登録するだけです。つまり、間違えにくい部分（レポート解析、flaky 検出、ヒューリスティック）は高速な単体テストでカバーされ、プロトコル配線は別途、エンドツーエンドのスモークテスト（後述）でカバーされます。

• GitHub アクセスはプラグ可能です。このポートフォリオ内の他の LLM 統合と同じパターンです。 GitHubClient はインターフェースであり、RealGitHubClient は GitHub REST API への fetch をラップし、FakeGitHubClient は固定データを返します。これにより get_repo_ci_status はオフラインで完全に単体テスト可能になります。一方、実際のクライアントは本物の実行可能なコードです。開発者のマシンで動く MCP ホストには通常のインターネットアクセスがありますが、ネットワークのない環境（このリポジトリ自身の CI サンドボックスなど）でも、そのままテスト可能です。

• テストスタブ生成は、意図的に LLM ベースではなく決定論的です。 名前付きの data-testid 操作シーケンスを渡すと、generate_playwright_test_stub は常に同じ出力を生成します。即時・無料・再現可能です。別の仕事のための別のツール（仕様やユーザーストーリーからテスト ケース を生成するもの。そこでは LLM が実際に価値を発揮します）は、このポートフォリオの別プロジェクトになります。

• 単体テストだけでなく、プロトコルレベルのスモークテストも行います。 smoke-test.mjs はビルドされたサーバーを実際の子プロセスとして起動し、公式 MCP Client を使って stdio 上で操作します。tools/list を実行し、続いてツールごとに tools/call を実行します。これにより CI は、内部の関数だけでなく実際のワイヤプロトコルが機能することを証明します。

Related MCP server: playwright-fixer-mcp

ツール

アーキテクチャ

src/
  index.ts                    MCP server: registers all 5 tools, connects over stdio
  playwright/reportParser.ts  Pure Playwright-JSON parsing: summarizeReport, findFlakyTests
  github/githubClient.ts      GitHubClient interface + RealGitHubClient (fetch) + FakeGitHubClient
  tools/
    explainFailure.ts         Heuristic pattern-matching (ported from the triage_failure.py
                               script in healthcare-qa-automation-framework)
    generateTestStub.ts       Deterministic Playwright test-file template generator
    getRepoCiStatus.ts        Wraps GitHubClient into pass/fail/in-progress counts
test/                         Vitest unit tests for every module above
fixtures/                     Sample Playwright JSON reports (3 runs, used for flaky-test tests)
smoke-test.mjs                End-to-end MCP protocol smoke test (real child process, real client)
.github/workflows/ci.yml      Type-check, unit tests, build, protocol smoke test

技術スタック

TypeScript · Node.js · @modelcontextprotocol/sdk · Zod · Vitest · GitHub REST API · GitHub Actions

ローカルでの実行

npm install
npm run build       # compiles to dist/
npm test            # unit tests (27 tests, fully offline)
npm run smoke        # builds, then drives the real server over stdio via the MCP client

MCP ホストから使用する

ビルドしたサーバーを MCP 互換クライアントに指定します。たとえば Claude Desktop の claude_desktop_config.json では:

{
  "mcpServers": {
    "qa-copilot": {
      "command": "node",
      "args": ["/absolute/path/to/qa-copilot-mcp-server/dist/index.js"]
    }
  }
}

環境変数 GITHUB_TOKEN を設定すると、実効的に get_repo_ci_status の GitHub レート制限を引き上げられます（トークンなしで 60 リクエスト/時、トークンありで 5,000 リクエスト/時）。たまに使う分には、トークンなしでも問題なく動作します。

CI

main へのすべての push と pull request で、単一のジョブが実行されます。型チェック（tsc --noEmit）、単体テストスイート（vitest run）、プロダクションビルド、そしてビルド成果物に対するプロトコルレベルのスモークテスト（node smoke-test.mjs）です。CI ではどこでもネットワークアクセスを前提とせず、要求もしません。get_repo_ci_status は単体テストで FakeGitHubClient に対してのみ実行され、スモークテストでは、サーバーがクラッシュせず MCP の isError チャネル経由で正常に報告さえすれば、ネットワークなしの get_repo_ci_status の結果は合格として扱います。

これは何ではないか

これは汎用的な GitHub ダッシュボードや CI ダッシュボードではありません。このポートフォリオの他のリポジトリが実際に生成する Playwright レポートと GitHub Actions の形状に特化した、小さく焦点の絞られたツール群です。AI アシスタントがテスト結果を要約情報へ言い換えるのではなく、実際の検証可能なテストデータに接続されることを示すためのものです。