QA Copilot MCP Server

Model Context Protocol 서버로, AI 어시스턴트가 추측하도록 요구하는 대신, 구체적인 QA/테스트 인텔리전스 도구 세트를 제공합니다. Playwright 실행 요약, 여러 실행에서 플래키 테스트 찾기, 휴리스틱 기반 실패 원인 설명, Playwright 테스트 스텁 생성, GitHub 저장소의 최근 CI 상태 읽기가 그 도구들입니다. Claude Desktop, Claude Code 또는 기타 다른 MCP 호환 호스트가 이 서버에 연결되면, 이 기능들은 자연어 추측이 아닌 실제 도구 호출이 됩니다.

이것은 "AI에 실제 데이터를 주자, 감에 의존하지 말자"는 QA 자동화 포트폴리오의 한 축입니다. 이 포트폴리오의 다른 저장소(healthcare-qa-automation-framework, healthcare-data-quality-framework)에서 생성하는 Playwright JSON 리포트와 CI 실행이 그 원, 이 서버는 그것들을 어시스턴트가 실제로 질의할 수 있는 형태로 바꿔 줍니다.

이렇게 만든 이유

• 프로토콜 연결은 일반 함수 위에 있는 얇은 계층일 뿐입니다. 각 도구의 실제 로직은 src/playwright/, src/github/, src/tools/ 에서, 작고 (거의) 순수하며 독립적으로 단위 테스트되는 모듈들로 구현됩니다. src/index.ts 는 이들 로직을 MCP SDK에 등록하는 일만 합니다. 실제 파싱·플래키 감지·휴리스틱과 같은 진짜 로직은 빠른 단위 테스트로 보호하고, 프로토콜 연결 부위는 별도의 종단 간 스모크 테스트(아래 참조)로 보호하는 방식입니다.

• 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로 stdin/stdout을 통해 구동합니다. 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"]
    }
  }
}

get_repo_ci_status의 인증되지 않은 GitHub 요청 한계(토큰 없으면 시간당 60회, 있으면 5,000회)를 늘리려면 환경변수에 GITHUB_TOKEN을 설정하세요. 간헐적 사용에는 토큰이 없어도 정상 동작합니다.

CI

main 으로의 모든 푸시와 풀 리퀘스트는 하나의 잡으로 수행됩니다: 타입 검사(tsc --noEmit), 단위 테스트 스위트(vitest run), 프로덕션 빌드, 그리고 빌드된 결과를 대상한 프로토콜 수준 스모크 테스트(node smoke-test.mjs)를 실행합니다. 어떤 CI 환경에서도 네트워크 접근을 가정하거나 요구하지 않습니다. get_repo_ci_status 는 단위 테스트에서 FakeGitHubClient 대상으로만 검증되고, 스모오크 테스트는네트워크 없는 환경에서도 서버가 MCP의 isError 채널로 오류를 보고만 하면(크래시 없이) 통과로 처리합니다.

이것이 아닌 것

범용 GitHub 또는 CI 대시보드가 아닙니다. 이 저장소의 다른 리포지토리가 실제 만들어내는 Playwright 리포트 / GitHub Actions 형태를 중심으로 설계된, 작고 집중된 도구 모음입니다. AI 어시스턴트가 테스트 결과를 실재 동작하고 검증 가능한 데이터로 얻을 수 있게 하는 방법을 보여주기 위한 것이며, 문단을 요약한 자연어 정보를 가지고 테스트 결과를 추론하게 하는 것과는 대적입니다.