QA Copilot MCP Server

Un servidor Model Context Protocol que proporciona a un asistente de IA un pequeño conjunto de herramientas concretas de QA e inteligencia de pruebas, en lugar de pedirle que adivine: resumir una ejecución de Playwright, encontrar tests flaky entre varias ejecuciones, explicar un fallo de forma heurística, generar un stub de test de Playwright y consultar el estado reciente de CI de un repositorio de GitHub. Apunta a Claude Desktop, Claude Code o cualquier otro host compatible con MCP y esas capacidades pasan a ser llamadas reales a herramientas, no suposiciones en texto libre.

Es la pieza de «dale a la IA datos reales, no sensaciones» dentro de un portafolio de automatización de QA: los otros repositorios de este portafolio (healthcare-qa-automation-framework, healthcare-data-quality-framework) generan informes JSON de Playwright y ejecuciones de CI; este servidor es lo que convierte esos datos en algo que un asistente puede consultar de verdad.

Por qué está construido así

• El cableado del protocolo es una capa fina sobre funciones simples. La lógica real de cada herramienta vive en src/playwright/, src/github/ y src/tools/ como módulos pequeños, puros (o casi) y con pruebas unitarias independientes. src/index.ts solo los registra con el SDK de MCP, así que la parte complicada (el análisis de informes, la detección de flaky, las heurísticas) queda cubierta por pruebas unitarias rápidas, y la capa del protocolo la cubre una prueba de humo de extremo a extremo aparte (más abajo).

• El acceso a GitHub is pluggable, con el mismo patrón que las integraciones de LLM del resto del portafolio. GitHubClient una interfaz; RealGitHubClient envuelve fetch contra la GitHub REST API, y FakeGitHubClient devuelve datos fijos. Eso hace que get_repo_ci_status sea totalmente testeable unitariamente sin red, mientras que el cliente real es código genuino y ejecutable: un host MCP en la máquina de un desarrollador tiene acceso normal a internet, incluso en entornos (como el sandbox de CI de este mismo repositorio) que no lo tienen.

• La generación de stubs de pruebas es determinista y a propósito no se base en un LLM. Dada una secuencia con nombre de interacciones data-testid, generate_playwright_test_stub siempre produce exactamente la misma salida: instantánea, libremente reproducible. Una herramienta distinta para un trabajo distinto (generar casos de prueba a partir de una especificación o una historia de usuario, donde un LLM sí aporta valor) es un proyecto aparte dentro de este portafolio.

• Una prueba de humo a nivel de protocolo, no solo unit tests. smoke-test.mjs lanza el servidor compilado como un proceso hijo real y lo conduce con el Client oficial de MCP a través de stdio —tools/list y luego un tools/call por cada herramienta—, de modo que CI comprueba que el protocolo de red real funciona, no solo las funciones que hay detrás.

Related MCP server: playwright-fixer-mcp

Herramientas

Arquitectura

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

Stack tecnológico

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

Ejecutarlo en local

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

Uso desde un host MCP

Apunta cualquier cliente compatible con MCP al servidor compilado, por ejemplo en el claude_desktop_config.json de Claude Desktop:

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

Define la variable de entorno GITHUB_TOKEN para elevar el límite de requests sin autenticar de GitHub para get_repo_ci_status (60 peticiones por hora sin él; 5,000 por hora con él) — funciona bien sin token para un uso ocasional.

CI

Cada push y pull request sobre main ejecuta un único job: type-check (tsc --noEmit), la suite de tests unitarios (vitest run), un build de producción y un smoke test de protocolo (node smoke-test.mjs) contra el build generado. No se asume ni se requiere acceso a red en ningún punto de CI: get_repo_ci_status solo se ejerce contra FakeGitHubClient en los tests, y el smoke test acepta un resultado de get_repo_ci_status sin red como válido siempre que el servidor lo notifique correctamente por el canal isError de MCP en lugar de estrellarse.

Qué no es esto

No es un dashboard genérico de GitHub ni de CI, sino un conjunto pequeño y enfocado de herramientas construidas específicamente alrededor de las formas de Playwright-report y GitHub-Actions que de verdad producen los otros repos de este portfolio; está pensado para mostrar cómo un asistente de IA se conecta con datos de prueba reales y verificables en vez de que se le pida razonarlo sobre resultados de tests a partir de un paráfrasis.