QA Copilot MCP Server

一个 Model Context Protocol 服务器，它为 AI 助手提供一组小而具体的 QA/测试智能工具，而不是让它凭空猜测：汇总一次 Playwright 运行、在多次运行中找出不稳定（flaky）的测试、以启发式的方式解释失败原因、搭建一个 Playwright 测试脚手架，以及读取 GitHub 仓库近期的 CI 状态。把它指向 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 在 fetch 外层封装了 GitHub REST API，而 FakeGitHubClient 返回预设数据。这让 get_repo_ci_status 可以在完全离线的环境下做完整的单元测试，而真实客户端同时又是可运行的真实代码——运行在开发者机器上的 MCP 主机拥有正常的互联网访问权限，即使在某些没有网络的环境（比如本仓库自己的 CI 沙箱）中也是如此。

• 测试脚手架生成是确定性的，而不是基于 LLM，这是有意的选择。 给定一组具名的 data-testid 交互序列，generate_playwright_test_stub 总是生成相同的输出——即时、免费、可复现。另一类工具负责另一类任务（根据规格说明或用户故事编写测试用例，那种场景下 LLM 才真正创造价值），那是本作品集的另一个项目。

• 不仅有单元测试，还有协议层面的冒烟测试。 smoke-test.mjs 将构建好的服务器作为真正的子进程启动，并通过 stdio 用官方 MCP Client 驱动它——先 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 次请求，有 token 时每小时 5,000 次）——不配置 token 也完全可行用于程序，只是适合偶发使用。

CI

每次针对 main 的 push 和拉取请求都会运行一个作业：类型检查（tsc --noEmit）、单元测试套件（vitest run）、生产构建、以及针对构建产物的协议级冒烟测试（node smoke-test.mjs）。CI 全程不假设也不需要网络：get_repo_ci_status 在单元测试中只对 FakeGitHubClient 进行验证；冒烟测试则把无网络状态下的 get_repo_ci_status 结果视为通过，只要服务器通过 MCP 的 isError 通道干净地报告结果而不是崩溃。

这说明它不是什么

这不是一个通用的 GitHub或 CI 仪表盘——它是一组小巧、聚焦的工具，专门围绕该作品集中其他仓库实际产生的 Playwright 测试报告和 GitHub Actions 数据形态来构建，目的是演示如何让 AI 助手接入真实、可验证的测试数据，而不是让它根据一段转述去推断测试结果。