beluz-qa

MCP Server de QA automatizado para Claude Code. Un sistema completo de testing, review y reporting que se integra directamente en tu flujo de trabajo.

Instalacion

npm install -g beluz-qa

O ejecucion directa:

npx beluz-qa

Configuracion en Claude Code

Agrega el servidor a tu configuracion de Claude Code:

Global (~/.claude/settings.json):

{
  "mcpServers": {
    "beluz-qa": {
      "command": "npx",
      "args": ["beluz-qa"]
    }
  }
}

Por proyecto (.claude/settings.json en la raiz del proyecto):

{
  "mcpServers": {
    "beluz-qa": {
      "command": "npx",
      "args": ["beluz-qa"]
    }
  }
}

Despues de configurar, todas las herramientas estan disponibles en cualquier sesion de Claude Code.

Inicio rapido

1. Setup del proyecto — Ejecuta setup en tu primera sesion:

setup({
  vcs_platform: "github",
  pm_tool: "linear",
  env_local_url: "http://localhost:3000",
  env_staging_url: "https://staging.example.com",
  ci_tool: "github-actions"
})

Esto auto-detecta el stack, frameworks de testing, info de git, y almacena toda la configuracion del proyecto.

2. Ejecutar tests:

create_test_run({ suite_name: "vitest-unit", trigger_type: "manual" })

3. Revisar un PR:

skill_pr_review({ pr_number: 42 })

4. Pre-deploy check:

skill_deploy_check({ environment: "production" })

Herramientas disponibles (25)

Contexto (Brain)

| Tool | Descripcion | |------|-------------| | gather_context | Analiza el proyecto y recopila contexto automaticamente | | search_context | Busca en el brain por texto y/o categoria | | brain_status | Estado del brain: entries, suites, runs, bugs | | forget_context | Elimina entries del brain |

Gestion de Tests

| Tool | Descripcion | |------|-------------| | list_test_suites | Lista suites registradas con ultimo resultado | | list_test_cases | Lista casos de una suite con filtros | | push_test_cases | Registra nuevos test cases en una suite | | create_test_run | Ejecuta tests, parsea salida y registra resultados individuales | | get_test_run | Detalle completo de un run | | update_test_result | Actualiza resultado individual | | test_run | Ejecucion rapida de un comando de tests | | manage_tests | Activar, desactivar, repriorizar, mover test cases |

Flujos de Trabajo

| Tool | Descripcion | |------|-------------| | setup | Setup inicial con auto-deteccion + onboarding interactivo | | ticket_review | Review de ticket/branch: diff, impacto, tests, reporte | | sprint_review | Review de sprint: regresion completa + GO/NO-GO |

Testing

| Tool | Descripcion | |------|-------------| | browser_testing | Tests de UI/E2E con Playwright (archivos, URL ad-hoc, scenarios) | | test_session_report | Reporte consolidado de sesion con tendencias |

Documentacion

| Tool | Descripcion | |------|-------------| | help | Documentacion de todas las herramientas | | bug_report | Crear, listar, consultar y actualizar bugs | | testing_guide | Guia de testing generada para el proyecto |

Skills (Validaciones de Proceso)

| Tool | Descripcion | |------|-------------| | skill_conventions | Verifica convenciones del codigo | | skill_pr_review | Review de PR desde perspectiva QA | | skill_qa_checklist | Checklist de QA por tipo de cambio | | skill_regression_test | Regresion completa con comparacion | | skill_deploy_check | Checklist pre-deploy |

Stacks soportados

• Node.js: Jest, Vitest, Mocha, Ava
• Laravel + Vue: PHPUnit, Pest, Vitest, Vue Test Utils
• E2E: Playwright, Cypress

Deteccion automatica

El setup detecta automaticamente:

• Stack del proyecto (Node.js, Laravel+Vue)
• Frameworks de testing instalados
• Configuracion de git (remote, branch)
• Suites de test existentes

Onboarding interactivo

El setup acepta configuracion adicional que no se puede auto-detectar:

• VCS: Plataforma, URL del repo, branch principal, estrategia de branching
• Project Management: Herramienta (Jira, Linear, GitHub Issues...), URL, formato de tickets
• Entornos: URLs de local, staging, produccion, notas de acceso
• CI/CD: Plataforma, URL del dashboard
• Testing: Comando de tests, URL para browser testing
• Credenciales: Tokens de GitHub/Jira (almacenados en .beluz-qa/.env, nunca en la DB)

Todos los parametros son opcionales. Configura lo que necesites y completa despues.

Almacenamiento

• Base de datos SQLite en .beluz-qa/brain.db (local por proyecto)
• Credenciales en .beluz-qa/.env (nunca en SQLite)
• Agrega .beluz-qa/ a tu .gitignore (el setup lo hace automaticamente)

Uso en equipo

• Cada miembro tiene su propia instancia local de la DB
• Las convenciones se comparten via CLAUDE.md del proyecto
• El setup recopila el mismo contexto para todos automaticamente
• No se commitea .beluz-qa/ — cada desarrollador corre su propio setup

Desarrollo

# Clonar e instalar
git clone <repo>
cd beluz-qa
npm install

# Build
npm run build

# Watch mode
npm run dev

# Testear con MCP Inspector
npm run inspect

Arquitectura

beluz-qa/
├── src/
│   ├── index.ts              # Entry point MCP (stdio)
│   ├── server.ts             # Registro de tools
│   ├── db/                   # SQLite: conexion, schema, migraciones
│   ├── detectors/            # Auto-deteccion de stack y frameworks
│   ├── utils/                # Logger (stderr), git, runner
│   └── tools/
│       ├── context/          # Brain: gather, search, status, forget
│       ├── test-management/  # Suites, cases, runs, results
│       ├── workflows/        # Setup, ticket review, sprint review
│       ├── testing/          # Browser testing, session report
│       ├── documentation/    # Help, bug reports, testing guide
│       └── skills/           # Conventions, PR review, QA checklist,
│                             # regression, deploy check
├── package.json
└── tsconfig.json

Licencia

MIT