AIQUAA Performance

Servidor MCP para analisar requisitos de desempenho, gerar e estender planos de teste do Apache JMeter, avaliar resultados JTL, aplicar limites e criar pull requests de rascunho.

GitHubExperimente este MCPPatrocinado

Documentação

AIQUAA Performance MCP Server

Servidor Model Context Protocol para converter requisitos não funcionais, contratos de API, código e artefatos JMeter em automação de desempenho segura e rastreável. Analisa cobertura, gera ou amplia planos .jmx, avalia .jtl, compara execuções e prepara draft pull requests.

A capacidade não é inferida apenas a partir do código. Todas as respostas distinguem informação observada, declarada, estimada e desconhecida. Se faltar carga suficiente, o servidor retorna suposições e uma proposta, nunca uma carga "validada".

Quick start

Requer Node.js 20+. Java 11+ e Apache JMeter 5.6+ são obrigatórios apenas para executar testes.

npx -y aiquaa-performance-mcp-server

O servidor publica:

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

Configuração de um cliente MCP:

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

Desenvolvimento local:

npm ci
npm run check
npm start

Arquitetura

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

As operações de leitura são puras. A geração retorna arquivos, mas não os escreve. perf_ejecutar e perf_pr concentram os efeitos externos e estão bloqueadas por padrão. A execução usa argumentos de processo separados (shell: false); XML rejeita DOCTYPE/ENTITY; todos os caminhos são normalizados e validados.

Tools

Tool	Resultado
`perf_analizar`	Endpoints, fluxos, auth, dados, riscos, JMeter/CI existentes, faltantes e confiança
`perf_requisitos`	`PerformanceRequirement` rastreável a partir de NFR/SLA/SLO
`perf_escenario`	Modelo fechado ou aberto e sua justificativa
`perf_cobertura`	`covered`, `partially_covered`, `uncovered`, `outdated`, `unsafe` ou `blocked`
`perf_generar`	JMX, CSV fictício, properties e thresholds nos modos `create`, `extend`, `modify`
`perf_validar`	XML, estrutura, variáveis, CSV, plugins, listeners e segredos, sem executar
`perf_ejecutar`	`validation_only`, `smoke` ou `full`, sujeito a autorização e limites
`perf_resultados`	Amostras, erros, throughput, P50/P90/P95/P99, bytes e veredictos
`perf_comparar`	Melhora, degradação, mudança não significativa ou não comparável
`perf_pipeline`	GitHub Actions ou Azure Pipelines headless com artifacts e thresholds
`perf_cambios`	Plano prévio de arquivos, cobertura estimada, risco e suposições
`perf_pr`	Plano dry-run ou branch + arquivos + draft PR via Octokit
`perf_monitoreo`	Captura (Python + Selenium) evidência de um dashboard de monitoramento externo (Grafana, Datadog, etc.) para anexar ao relatório
`perf_informe`	Relatório PDF (capa, veredicto, percentis, comparação, detalhe por sampler, evidência de monitoramento opcional)

Todas aceitam response_format: json, markdown, files ou patch, exceto perf_informe, que sempre retorna o PDF embutido em base64 (resource com mimeType: application/pdf) junto a um resumo em texto; o cliente decide se o persiste.

Modelos e presets

Um workload fechado modela usuários concorrentes que aguardam uma resposta; um aberto modela uma taxa de chegada independente. perf_escenario seleciona o segundo quando o requisito declara arrivalRate ou throughput e o primeiro quando declara concorrência.

Presets incluídos:

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: são derivados do requisito; sem dados, começam como proposta mínima com confiança baixa.
aiquaa_stress: 1000 threads × 30 loops, ramp-up 0, think time 0. Está marcado como agressivo e nunca pode ser executado sem confirmação explícita.

JMeter e arquivos gerados

Os planos usam JMeter 5.6.3, HttpClient4, HTTP defaults, cookies, headers, CSV UTF-8, assertions e Simple Data Writer. Evitam BeanShell, segredos e listeners gráficos. A ampliação preserva o XML existente e insere apenas samplers cujos nomes ainda não existem.

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

Os CSV gerados contêm valores fictícios. Configure recycle, stopThread e sharing mode conforme os dados sejam reutilizáveis, únicos, consumíveis ou exijam cleanup. Não versionar credenciais nem dados reais.

Thresholds e resultados

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

Os veredictos são PASS, FAIL, INCONCLUSIVE e NOT_EXECUTED. Falta de thresholds, poucas amostras ou ambiente instável produzem INCONCLUSIVE. A comparação retorna not_comparable se diferirem carga, duração, dataset, ambiente, infraestrutura, versão ou warm-up.

Um pipeline pode avaliar resultados com:

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

Ou gerar o mesmo relatório PDF que produz perf_informe, sem passar por MCP:

npx -y aiquaa-performance-mcp-server --report test-results/performance/R_API.jtl tests/performance/thresholds/thresholds.json test-results/performance/INFORME_PERF_API.pdf \
  --api-name "Mi API" --test-type smoke --threads 1 --loops 1 \
  --baseline test-results/performance/R_BASELINE.jtl --api-version v1.2.0 --repo-url https://github.com/org/repo --author "Nombre" \
  --evidence-image test-results/performance/evidence/EVIDENCIA_MONITOREO.png --evidence-label "Dashboard de monitoreo" --evidence-url https://example.grafana.net/public-dashboards/xxx

Segurança de execução

perf_ejecutar usa validation_only por padrão. Para uma execução real são necessários simultaneamente:

PERF_ALLOW_EXECUTION=true;
host exato em PERF_ALLOWED_HOSTS;
authorized=true na chamada;
carga abaixo dos máximos configurados;
confirmação adicional para produção, carga agressiva ou testes destrutivos.

Variáveis:

Variável	Uso
`PORT`, `MCP_PATH`	Servidor HTTP
`JMETER_HOME`, `JAVA_HOME`	Execução local
`PERF_ALLOWED_HOSTS`, `PERF_PRODUCTION_HOSTS`	Allowlist e proteção de produção
`PERF_MAX_THREADS`, `PERF_MAX_DURATION_SECONDS`, `PERF_MAX_ARRIVAL_RATE`	Limites rígidos
`PERF_ALLOW_EXECUTION`	Kill switch; `false` por padrão
`PERF_MONITORING_PYTHON_BIN`	Binário de Python para `perf_monitoreo`; `python3` por padrão
`PERF_MONITORING_ALLOWED_PRIVATE_HOSTS`	Allowlist de hosts privados/loopback para `perf_monitoreo`
`GITHUB_TOKEN`, `GITHUB_API_URL`	Draft PR
`AIQUAA_API_BASE_URL`, `AIQUAA_ACCESS_TOKEN`	Adapter AIQUAA
`CODEGRAPH_BIN`, `CODEGRAPH_ALLOWED_ROOTS`	Contexto estrutural opcional
`ENGRAM_BIN`, `ENGRAM_PROJECT_PREFIX`	Memória opcional por projeto

A API HTTP limita corpos a 10 MB; os runners têm timeout e cancelamento. Tokens, senhas, API keys e segredos são redigidos antes de produzir arquivos ou PR. Não é permitido path traversal.

GitHub PR

perf_pr sempre usa branch test/performance/<requirement-or-flow>, título test(perf): add load coverage for <flow> e draft PR. dry_run=true é o default e retorna o plano completo sem mutar o GitHub. Com dry_run=false, Octokit cria a branch a partir de base, escreve cada arquivo e abre o draft.

O body fornecido deve documentar requisito, tipo/modelo, endpoints, carga, duração, ramp-up, dataset, thresholds, suposições, riscos, comandos, variáveis, impacto, execução e checklist de segurança.

AIQUAA, CodeGraph e Engram

AIQUAA centraliza rotas para obter requisitos e salvar planos, execuções e vínculos de PR. O adapter é opcional e não registra contratos inventados além dessas rotas configuráveis.
CodeGraph pode construir contexto estrutural apenas dentro de CODEGRAPH_ALLOWED_ROOTS; execute codegraph init -i em cada repositório antes de usá-lo.
Engram fica isolado por meio de ENGRAM_PROJECT_PREFIX + projectId. Salvar apenas thresholds, decisões, ambientes e resultados curados; nunca credenciais ou datasets sensíveis.

Docker e CI

O Dockerfile compila TypeScript com Node 20 e executa sobre Java 17 com JMeter 5.6.3. GitHub Actions valida lint, build, testes, cobertura mínima de 70%, pacote npm e build de imagem. A publicação npm é disparada a partir de releases, usa OIDC/trusted publishing e --provenance; não precisa de um token npm persistente.

Evidência de monitoramento (Python + Selenium)

perf_monitoreo automatiza, com Python + Selenium, o que antes era montado à mão: abrir um dashboard de monitoramento público (por exemplo, Grafana) e capturá-lo como evidência dentro do relatório PDF. Caso típico: um dashboard público de Grafana que mostra o estado de um banco de dados durante a execução (como o usado para mostrar aos alunos o que observar enquanto uma prova de desempenho é executada).

Requer Python 3 além do runtime Node do servidor:

pip install -r src/monitoring/python/requirements.txt

Selenium ≥4.6 resolve o driver do Chrome sozinho (Selenium Manager), sem webdriver-manager nem configuração manual; basta ter Chrome/Chromium instalado. perf_monitoreo não executa nada se o host do dashboard for privado/loopback, exceto se estiver em PERF_MONITORING_ALLOWED_PRIVATE_HOSTS.

Fluxo recomendado pós-execução: perf_ejecutar → perf_resultados → (opcional) perf_monitoreo com a URL do dashboard → perf_informe passando o resultado em monitoring_evidence. Um agente que orquestra esse fluxo deve perguntar ao usuário se precisa de evidência de monitoramento antes de invocar perf_monitoreo (assim indica a descrição da tool); se não precisar, pula direto para perf_informe.

O mesmo anexo pode ser gerado sem passar por MCP com a CLI --report (ver abaixo), usando --evidence-image, --evidence-label, --evidence-url e --evidence-captured-at.

Exemplo de fluxo MCP

Analise o repositório e NFR-018. O requisito estabelece 150 usuários concorrentes, P95 < 2 s e error rate < 0,5%. Revise auth, JMX e baseline; não duplique samplers. Planeje mudanças, amplie o plano, gere CSV fictício, thresholds e diff. Depois prepare o draft PR. Não execute o teste.

Ordem recomendada: perf_analizar → perf_requisitos → perf_escenario → perf_cobertura → perf_cambios → perf_generar → perf_validar → perf_pr.

Reutilização e diferenças em relação às referências

De aiquaa-labs/jmeter-skill foram preservados nomes P_, D_, R_, geração JMX/CSV, execução non-GUI, dashboard, CI, reparação e reporting. A mudança deliberada é que 1000×30 deixou de ser universal e passou a aiquaa_stress com risco explícito. O design do relatório PDF (perf_informe: capa, faixa de estatísticas, percentis, veredicto, comparação com linha de base, detalhe por sampler, top erros) reproduz o de reporter/jmeter_report.py desse repo, mesmo layout, mas reimplementado em TypeScript com pdfkit para não exigir Python/pandas/reportlab no servidor MCP.

De aiquaa-playwright-mcp-server foi reutilizado o padrão de McpServer + Streamable HTTP sem estado, schemas Zod estritos, adaptadores AIQUAA/CodeGraph/Engram, respostas estruturadas e processos sem shell. Performance adiciona policy centralizada, análise XML/JTL, comparabilidade e efeitos externos bloqueados por padrão.

Limitações

O modelo aberto gera ArrivalsThreadGroup e requer a instalação do JMeter Plugins Custom Thread Groups; perf_validar o declara como dependência antes de executar.
A análise estática local detecta sinais, não capacidade real nem topologia implantada.
Os percentis são calculados em memória; aplique limites externos para JTL muito grandes.
perf_informe gera o PDF com pdfkit (sem dependências de Python) a partir do que já calcula perf_resultados/perf_comparar; o dashboard HTML do JMeter (-e -o) continua sendo separado, via os pipelines de perf_pipeline.
A ampliação localizada usa nomes de sampler como chave de identidade; renomes manuais podem exigir revisão.
perf_monitoreo requer Python 3 + Selenium instalados separadamente (src/monitoring/python/requirements.txt); eles não estão incluídos no Dockerfile deste servidor nem nas dependências do npm, e só são necessários se essa tool for usada.