blackwell-systems/mcp-assert

O que mcp-assert faz?

O padrão de teste determinístico para servidores MCP. Conecte-se via transporte stdio/SSE/HTTP real, chame ferramentas com argumentos reais e afirme resultados com 18 tipos de asserção definidos em YAML. Qualquer linguagem, qualquer transporte, sem mocks. Binário Go único.

Visão Geral

mcp-assert é uma ferramenta de teste projetada para validar servidores MCP (Model Context Protocol) de forma determinística. Diferente de frameworks de teste tradicionais que dependem de mocks, o mcp-assert conecta-se ao seu servidor MCP real usando os transportes padrão (stdio, SSE, HTTP) e executa chamadas de ferramentas reais com argumentos reais. Os resultados são então verificados usando um conjunto rico de tipos de asserção, todos definidos em arquivos YAML simples.

Recursos

• Sem mocks: Testes contra servidores reais, refletindo o comportamento de produção.
• 18 tipos de asserção: Cobertura abrangente para validar resultados, incluindo igualdade, correspondência de padrões, verificações de tipo, intervalo, comprimento, existência e mais.
• YAML-driven: Defina casos de teste em arquivos YAML reutilizáveis e com controle de versão.
• Qualquer transporte: Suporta stdio, SSE e HTTP.
• Qualquer linguagem: Funciona com servidores MCP escritos em qualquer linguagem.
• Binário único: Implementado em Go, sem dependências de runtime.

Instalação

Baixe o binário mais recente da página de releases ou compile da fonte:

go install github.com/blackwell-systems/mcp-assert/cmd/mcp-assert@latest

Uso

1. Defina seu caso de teste

Crie um arquivo YAML (por exemplo, test.yaml):

name: Teste de calculadora

transport:
  type: stdio
  command: ["python", "mcp_server.py"]
  # Ou para HTTP:
  # type: http
  # url: "http://localhost:8000/mcp"
  # Ou para SSE:
  # type: sse
  # url: "http://localhost:8000/sse"

tools:
  - name: soma
    arguments:
      a: 1
      b: 2
    assertions:
      - type: equal
        expected: 3
  - name: divisao
    arguments:
      a: 10
      b: 0
    assertions:
      - type: notEqual
        expected: Infinity
      - type: hasField
        field: error

2. Execute o teste

mcp-assert test.yaml

Isso conecta-se ao servidor especificado, chama cada ferramenta com os argumentos fornecidos e executa todas as asserções.

Tipos de Asserção

O mcp-assert suporta 18 tipos de asserção. Aqui estão alguns dos mais comuns:

Tipo	Descrição	Exemplo
equal	Comparação de igualdade estrita	expected: 42
notEqual	Comparação de desigualdade estrita	expected: 0
contains	A string contém uma substring	value: "erro"
notContains	A string não contém uma substring	value: "pânico"
match	A string corresponde a um padrão regex	pattern: "\\d+"
type	Verifica o tipo (string, number, boolean, object, array)	expected: "number"
greaterThan	Número maior que	threshold: 5
lessThan	Número menor que	threshold: 100
hasField	Objeto tem um campo	field: "resultado"
length	Array ou string tem comprimento	expected: 3

Veja a documentação completa em docs/assertions.md.

Exemplo de CI/CD

Integre em seu pipeline CI:

# .github/workflows/test-mcp-server.yml
name: Testar servidor MCP
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Instalar mcp-assert
        run: |
          wget https://github.com/blackwell-systems/mcp-assert/releases/latest/download/mcp-assert-linux-amd64.tar.gz
          tar -xzf mcp-assert-linux-amd64.tar.gz
          sudo mv mcp-assert /usr/local/bin/
      - name: Executar testes
        run: mcp-assert tests/*.yaml

Suporte

• Problemas: GitHub Issues
• Discussões: GitHub Discussions
• Contribuições: Pull requests são bem-vindas!

Licença

MIT