AIQUAA Performance

Servidor MCP para analizar requisitos de rendimiento, generar y ampliar planes de prueba de Apache JMeter, evaluar resultados JTL, aplicar umbrales y crear borradores de solicitudes de extracción.

GitHub

Documentación

AIQUAA Performance MCP Server

Servidor Model Context Protocol para convertir requisitos no funcionales, contratos de API, código y artefactos JMeter en automatización de rendimiento segura y trazable. Analiza cobertura, genera o amplía planes .jmx, evalúa .jtl, compara ejecuciones y prepara draft pull requests.

La capacidad no se infiere sólo desde el código. Todas las respuestas distinguen información observada, declarada, estimada y desconocida. Si falta carga suficiente, el servidor devuelve supuestos y una propuesta, nunca una carga “validada”.

Quick start

Requiere Node.js 20+. Java 11+ y Apache JMeter 5.6+ sólo son obligatorios para ejecutar pruebas.

npx -y aiquaa-performance-mcp-server

El servidor publica:

MCP Streamable HTTP: http://localhost:3000/mcp
Health: http://localhost:3000/health

Configuración de un cliente MCP:

{
  "mcpServers": {
    "aiquaa-performance": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Desarrollo local:

npm ci
npm run check
npm start

Arquitectura

MCP HTTP → schemas Zod → tools → dominio
                                ├─ análisis de requisito/repositorio
                                ├─ modelo de carga cerrado/abierto
                                ├─ parser/generador/validador/runner JMeter
                                ├─ JTL, thresholds y comparación
                                ├─ pipelines y GitHub draft PR
                                └─ adapters AIQUAA, CodeGraph y Engram

Las operaciones de lectura son puras. La generación devuelve archivos, pero no los escribe. perf_ejecutar y perf_pr concentran los efectos externos y están bloqueadas por defecto. La ejecución usa argumentos de proceso separados (shell: false); XML rechaza DOCTYPE/ENTITY; todas las rutas se normalizan y validan.

Tools

Tool	Resultado
`perf_analizar`	Endpoints, flujos, auth, datos, riesgos, JMeter/CI existentes, faltantes y confianza
`perf_requisitos`	`PerformanceRequirement` trazable desde NFR/SLA/SLO
`perf_escenario`	Modelo cerrado u abierto y su justificación
`perf_cobertura`	`covered`, `partially_covered`, `uncovered`, `outdated`, `unsafe` o `blocked`
`perf_generar`	JMX, CSV ficticio, properties y thresholds en modos `create`, `extend`, `modify`
`perf_validar`	XML, estructura, variables, CSV, plugins, listeners y secretos, sin ejecutar
`perf_ejecutar`	`validation_only`, `smoke` o `full`, sujeto a autorización y límites
`perf_resultados`	Muestras, errores, throughput, P50/P90/P95/P99, bytes y veredictos
`perf_comparar`	Mejora, degradación, cambio no significativo o no comparable
`perf_pipeline`	GitHub Actions o Azure Pipelines headless con artifacts y thresholds
`perf_cambios`	Plan previo de archivos, cobertura estimada, riesgo y supuestos
`perf_pr`	Plan dry-run o rama + archivos + draft PR mediante Octokit

Todas aceptan response_format: json, markdown, files o patch.

Modelos y presets

Un workload cerrado modela usuarios concurrentes que esperan una respuesta; uno abierto modela una tasa de llegada independiente. perf_escenario selecciona el segundo cuando el requisito declara arrivalRate o throughput y el primero cuando declara concurrencia.

Presets incluidos:

smoke: 1 thread, 1 loop, ramp-up 1 s.
baseline: 5 threads, 60 s, ramp-up 10 s.
load, stress, spike, endurance, soak, capacity, breakpoint, scalability, volume: se derivan del requisito; sin datos, comienzan como propuesta mínima con confianza baja.
aiquaa_stress: 1000 threads × 30 loops, ramp-up 0, think time 0. Está marcado como agresivo y nunca puede ejecutarse sin confirmación explícita.

JMeter y archivos generados

Los planes usan JMeter 5.6.3, HttpClient4, HTTP defaults, cookies, headers, CSV UTF-8, assertions y Simple Data Writer. Evitan BeanShell, secretos y listeners gráficos. La ampliación preserva el XML existente e inserta sólo samplers cuyos nombres todavía no existen.

tests/performance/
├── plans/P_<API>.jmx
├── data/D_<API>.csv
├── properties/<environment>.properties
├── thresholds/thresholds.json
└── README.md

test-results/performance/
├── R_<API>.jtl
├── dashboard/
├── summary.json
├── comparison.json
└── INFORME_PERF_<API>.pdf

Los CSV generados contienen valores ficticios. Configure recycle, stopThread y sharing mode según si los datos son reutilizables, únicos, consumibles o requieren cleanup. No versionar credenciales ni datos reales.

Thresholds y resultados

{
  "global": { "maxErrorRate": 1, "p95Ms": 1500 },
  "operations": {
    "POST /payments": { "maxErrorRate": 0.1, "p95Ms": 2000, "p99Ms": 3500 }
  }
}

Los veredictos son PASS, FAIL, INCONCLUSIVE y NOT_EXECUTED. Falta de thresholds, pocas muestras o ambiente inestable producen INCONCLUSIVE. La comparación devuelve not_comparable si difieren carga, duración, dataset, ambiente, infraestructura, versión o warm-up.

Un pipeline puede evaluar resultados con:

npx -y aiquaa-performance-mcp-server --evaluate test-results/performance/R_API.jtl tests/performance/thresholds/thresholds.json

Seguridad de ejecución

perf_ejecutar usa validation_only por defecto. Para una ejecución real se requieren simultáneamente:

PERF_ALLOW_EXECUTION=true;
host exacto en PERF_ALLOWED_HOSTS;
authorized=true en la llamada;
carga bajo los máximos configurados;
confirmación adicional para producción, carga agresiva o pruebas destructivas.

Variables:

Variable	Uso
`PORT`, `MCP_PATH`	Servidor HTTP
`JMETER_HOME`, `JAVA_HOME`	Ejecución local
`PERF_ALLOWED_HOSTS`, `PERF_PRODUCTION_HOSTS`	Allowlist y protección de producción
`PERF_MAX_THREADS`, `PERF_MAX_DURATION_SECONDS`, `PERF_MAX_ARRIVAL_RATE`	Límites duros
`PERF_ALLOW_EXECUTION`	Kill switch; `false` por defecto
`GITHUB_TOKEN`, `GITHUB_API_URL`	Draft PR
`AIQUAA_API_BASE_URL`, `AIQUAA_ACCESS_TOKEN`	Adapter AIQUAA
`CODEGRAPH_BIN`, `CODEGRAPH_ALLOWED_ROOTS`	Contexto estructural opcional
`ENGRAM_BIN`, `ENGRAM_PROJECT_PREFIX`	Memoria opcional por proyecto

La API HTTP limita cuerpos a 10 MB; los runners tienen timeout y cancelación. Tokens, passwords, API keys y secretos se redactan antes de producir archivos o PR. No se permite path traversal.

GitHub PR

perf_pr siempre usa rama test/performance/<requirement-or-flow>, título test(perf): add load coverage for <flow> y draft PR. dry_run=true es el default y devuelve el plan completo sin mutar GitHub. Con dry_run=false, Octokit crea la rama desde base, escribe cada archivo y abre el draft.

El body proporcionado debe documentar requisito, tipo/modelo, endpoints, carga, duración, ramp-up, dataset, thresholds, supuestos, riesgos, comandos, variables, impacto, ejecución y checklist de seguridad.

AIQUAA, CodeGraph y Engram

AIQUAA centraliza rutas para obtener requisitos y guardar planes, ejecuciones y vínculos de PR. El adapter es opcional y no registra contratos inventados más allá de esas rutas configurables.
CodeGraph puede construir contexto estructural sólo dentro de CODEGRAPH_ALLOWED_ROOTS; ejecute codegraph init -i en cada repositorio antes de usarlo.
Engram queda aislado mediante ENGRAM_PROJECT_PREFIX + projectId. Guardar únicamente thresholds, decisiones, ambientes y resultados curados; nunca credenciales o datasets sensibles.

Docker y CI

El Dockerfile construye TypeScript con Node 20 y ejecuta sobre Java 17 con JMeter 5.6.3. GitHub Actions valida lint, build, pruebas, cobertura mínima de 70%, paquete npm y build de imagen. La publicación npm se dispara desde releases, usa OIDC/trusted publishing y --provenance; no necesita un token npm persistente.

Ejemplo de flujo MCP

Analizá el repositorio y NFR-018. El requisito establece 150 usuarios concurrentes, P95 < 2 s y error rate < 0,5%. Revisá auth, JMX y baseline; no dupliques samplers. Planificá cambios, ampliá el plan, generá CSV ficticio, thresholds y diff. Después prepará el draft PR. No ejecutes la prueba.

Orden recomendado: perf_analizar → perf_requisitos → perf_escenario → perf_cobertura → perf_cambios → perf_generar → perf_validar → perf_pr.

Reutilización y diferencias respecto a las referencias

De aiquaa-labs/jmeter-skill se conservaron nombres P_, D_, R_, generación JMX/CSV, ejecución non-GUI, dashboard, CI, reparación y reporting. El cambio deliberado es que 1000×30 dejó de ser universal y pasó a aiquaa_stress con riesgo explícito.

De aiquaa-playwright-mcp-server se reutilizó el patrón de McpServer + Streamable HTTP sin estado, schemas Zod estrictos, adaptadores AIQUAA/CodeGraph/Engram, respuestas estructuradas y procesos sin shell. Performance agrega policy centralizada, análisis XML/JTL, comparabilidad y efectos externos bloqueados por defecto.

Limitaciones

El modelo abierto genera ArrivalsThreadGroup y requiere instalar JMeter Plugins Custom Thread Groups; perf_validar lo declara como dependencia antes de ejecutar.
El análisis estático local detecta señales, no capacidad real ni topología desplegada.
Los percentiles se calculan en memoria; aplique límites externos para JTL muy grandes.
La generación de PDF se delega al dashboard/reporting del pipeline; esta versión analiza y produce JSON/Markdown, pero no maqueta el PDF directamente.
La ampliación localizada usa nombres de sampler como clave de identidad; renombres manuales pueden requerir revisión.