ReqStorm

Analisador de desempenho de API MCP

Documentação

ReqStorm

ReqStorm é um servidor Model Context Protocol (MCP) para testes de API, análise de desempenho, validação de contratos, fuzzing e verificações leves de segurança. Ele opera via stdio, funcionando com clientes MCP como Claude Desktop, VS Code, Cursor e outros hosts compatíveis.

ReqStorm é publicado como reqstorm e fornece 14 ferramentas:

Desempenho: benchmark, smoke, load-test, spike, soak, stress-test, compare
Funcional e contrato: validate, chain, contract-check, fuzz, regression
Segurança e perfilamento: security-scan, profile

Início rápido

Adicione ReqStorm à configuração do seu host MCP:

{
  "mcpServers": {
    "reqstorm": {
      "command": "npx",
      "args": ["-y", "reqstorm"]
    }
  }
}

A primeira execução baixa o pacote do npm. Para um binário instalado globalmente:

npm install --global reqstorm

Em seguida, peça ao seu cliente MCP para executar uma ferramenta, por exemplo:

Execute um benchmark ReqStorm contra https://api.example.com/health com 10 conexões por 10 segundos.

ReqStorm requer Node.js 18 ou superior.

Referência de ferramentas

Testes de desempenho

Ferramenta	Use para
`benchmark`	Medir throughput e latência p50/p95/p99/p999. Os resultados incluem dados gerais, de aquecimento e de estado estável.
`smoke`	Verificar rapidamente se um endpoint responde com o status e corpo esperados.
`load-test`	Executar tráfego contínuo e avaliar limites de `maxP95`, `maxP99` e `maxErrorRate` em estado estável.
`spike`	Executar fases de linha de base, pico súbito e recuperação; medir a recuperação em relação à latência da linha de base.
`soak`	Executar tráfego de longa duração em blocos periódicos para encontrar vazamentos de memória, esgotamento e degradação de desempenho. A duração padrão é de 30 minutos.
`stress-test`	Aumentar a concorrência passo a passo até que limites de latência ou taxa de erro identifiquem um ponto de ruptura.
`compare`	Comparar dois endpoints ou configurações lado a lado, opcionalmente repetindo cada alvo até cinco vezes.

Testes funcionais e de contrato

Ferramenta	Use para
`validate`	Enviar uma requisição e fazer asserções sobre valores JSONPath, tipos, comparações, regex, propriedades de arrays e limites de tempo de resposta.
`chain`	Executar até 20 requisições ordenadas, extrair valores das respostas, interpolá-los em requisições posteriores e fazer asserções em cada etapa.
`contract-check`	Verificar uma API em execução contra um documento OpenAPI 3.x JSON/YAML, incluindo códigos de status, schemas, tipos de conteúdo e campos obrigatórios.
`fuzz`	Mutar corpos de requisição com estratégias de limite, troca de tipo, injeção, estouro, campo ausente, Unicode, formato e campo nulo.
`regression`	Comparar o desempenho em estado estável com uma linha de base `.reqstorm/` salva e, opcionalmente, salvar a execução atual como nova linha de base.

Segurança e perfilamento

Ferramenta	Use para
`security-scan`	Executar verificações selecionadas para bypass de autenticação, IDOR, cabeçalhos de segurança, exposição de dados, limitação de taxa, override de método, incompatibilidade de tipo de conteúdo e path traversal.
`profile`	Inspecionar distribuição de latência, contagens de códigos de status, estabilidade de throughput e detalhamentos de erros/timeouts.

Convenções comuns de entrada

Valores de url devem ser acessíveis pela máquina que executa o servidor MCP.
headers é um objeto string-para-string e pode carregar autenticação, cookies ou chaves de API.
Campos HTTP body são strings JSON, não objetos JavaScript. Defina um cabeçalho Content-Type apropriado ao enviar JSON.
Métodos que usam JSONPath aceitam expressões como $.user.id, $.items[0], $..email e $.tags[*].
As saídas são retornadas como texto formatado na resposta da ferramenta MCP.
Ferramentas de desempenho usam a fase de estado estável para avaliação de limites; resultados de aquecimento ainda são relatados, não descartados.

Exemplos

Benchmark de um endpoint

{
  "url": "https://api.example.com/users",
  "connections": 50,
  "duration": 30,
  "warmUpDuration": 5,
  "headers": {
    "Authorization": "Bearer <token>"
  }
}

Validar uma resposta JSON

{
  "url": "https://api.example.com/users/1",
  "assertions": [
    {
      "path": "$.name",
      "match": { "op": "equals", "expected": "Alice" }
    },
    {
      "path": "$.age",
      "match": { "op": "gte", "expected": 18 }
    },
    {
      "path": "$.email",
      "match": { "op": "matches", "pattern": "^[^@]+@[^@]+$" }
    }
  ],
  "timeouts": {
    "maxResponseMs": 500
  },
  "retries": 2
}

Os operadores de correspondência suportados são equals, notEquals, contains, matches, gt, lt, gte, lte, exists, notExists, isType, isArray e hasLength.

Encadear um fluxo de trabalho autenticado

{
  "baseUrl": "https://api.example.com",
  "steps": [
    {
      "name": "login",
      "request": {
        "url": "/auth/login",
        "method": "POST",
        "headers": { "Content-Type": "application/json" },
        "body": "{\"username\":\"test\",\"password\":\"<password>\"}"
      },
      "extract": { "token": "$.token" }
    },
    {
      "name": "create-user",
      "request": {
        "url": "/users",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer {{token}}",
          "Content-Type": "application/json"
        },
        "body": "{\"name\":\"Test User\"}"
      },
      "extract": { "id": "$.id" }
    },
    {
      "name": "verify",
      "request": {
        "url": "/users/{{id}}",
        "headers": { "Authorization": "Bearer {{token}}" }
      },
      "assertions": [
        {
          "path": "$.name",
          "match": { "op": "equals", "expected": "Test User" }
        }
      ]
    }
  ]
}

Verificar um contrato OpenAPI

{
  "specUrl": "https://api.example.com/openapi.json",
  "baseUrl": "https://api.example.com",
  "headers": {
    "Authorization": "Bearer <token>"
  },
  "paths": ["/users"],
  "methods": ["get", "post"],
  "previousSpecUrl": "/absolute/path/to/previous-openapi.yaml"
}

specUrl pode ser uma URL HTTP(S), um caminho de arquivo absoluto, um caminho file:// ou um documento JSON inline.

Teste de carga com limites

{
  "url": "https://api.example.com/auth",
  "connections": 100,
  "duration": 60,
  "headers": {
    "Authorization": "Bearer <token>"
  },
  "thresholds": {
    "maxP95": 200,
    "maxP99": 500,
    "maxErrorRate": 1
  }
}

Fuzzing de um corpo de requisição JSON

Use body para uma string JSON, ou bodyTemplate ao chamar a ferramenta com um objeto estruturado:

{
  "url": "https://api.example.com/users",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
  },
  "bodyTemplate": {
    "name": "Alice",
    "age": 30
  },
  "depth": "normal",
  "strategies": ["boundary", "injection", "type-swap", "missing-fields"]
}

A configuração depth controla a intensidade da mutação: quick, normal (padrão) ou thorough. Por padrão, uma requisição de linha de base é enviada primeiro e os status 500, 502, 503 e 504 são tratados como falhas graves.

Executar uma varredura de segurança

{
  "url": "https://api.example.com/users/123",
  "headers": {
    "Authorization": "Bearer <token>"
  },
  "authToken": "<token>",
  "resourceId": "123",
  "checks": [
    "auth-bypass",
    "security-headers",
    "data-exposure",
    "idor",
    "path-traversal"
  ]
}

Apenas escaneie sistemas que você possui ou está autorizado a testar. Verificações de segurança e fuzzing enviam requisições adicionais e podem alterar dados quando apontadas para endpoints que mudam de estado.

Resultados e linhas de base

Latência

Resultados de desempenho relatam latência p50, p95, p99 e p999, além de throughput e taxa de erro. Percentis de cauda são mais úteis que médias para SLAs: uma média pode parecer saudável enquanto uma pequena porcentagem de requisições é muito lenta.

Aquecimento e estado estável

Ferramentas baseadas em benchmark dividem a execução em fases de aquecimento e estado estável. O aquecimento é mantido na saída, enquanto o load-test e outras verificações de limite usam métricas de estado estável para que o aquecimento de cache e JIT não distorça resultados de aprovação/reprovação.

Linhas de base de regressão

benchmark pode salvar um resultado com saveAs; regression lê e escreve linhas de base nomeadas em .reqstorm/. Mantenha este diretório junto ao projeto ou workspace de CI ao comparar execuções entre execuções.

Desenvolvimento

npm install
npm run build   # compile src/ to dist/
npm run dev     # watch TypeScript changes

Para publicar uma versão:

npm run build
npm publish

prepublishOnly executa o build automaticamente. O pacote requer autenticação npm e o pacote publicado contém dist/, README.md e LICENSE.

Licença

MIT