Testando Servidores MCP Sem Configuração

Ao construir servidores do Protocolo de Contexto de Modelo (MCP) ou agentes de IA que os consomem, as ferramentas tradicionais de teste de API ficam aquém. Um servidor MCP não é apenas um endpoint REST básico—é uma interface dinâmica exposta a LLMs não determinísticos através de stdio, HTTP ou transportes SSE.

Os esquemas das ferramentas de teste, falhas transitórias de rede e comportamentos de agentes geralmente exigem a escrita de uma montanha de código boilerplate.

Eu construí o bubblemcp-test-kit para eliminar essa fricção: sem contas de backend, sem configuração de teste complexa e zero instrumentação necessária.

O que é o bubblemcp-test-kit?
O bubblemcp-test-kit é um kit de ferramentas de teste leve e autônomo, projetado especificamente para desenvolvedores de servidores MCP e engenheiros de agentes de IA.

Os principais recursos incluem:

Independente de Transporte: Trabalhe com stdio, HTTP ou SSE por trás de uma API unificada.

Aserções Fluentes: Matchers nativos adaptados para estruturas de resposta MCP e Esquemas JSON.

Mocking & Replay: Fabricar saídas de ferramentas localmente ou gravar execuções reais de servidores para reproduzir em ambientes CI offline.

Rastreamento de Agentes & Injeção de Falhas: Teste se seu agente de IA chama ferramentas na ordem correta e lida com erros adequadamente.

Exemplo de Início Rápido
Você pode executar um conjunto completo de testes simulados sem iniciar um servidor ao vivo:

import {
  createMockMcpClient,
  expectMcp,
  validateAgainstSchema,
  withRecording,
  createReplayClient,
} from 'bubblemcp-test-kit'

// 1. Defina o contrato da sua ferramenta
const healthCheckTool = {
  name: 'health_check',
  description: 'Relata a saúde do serviço',
  inputSchema: {
    type: 'object',
    properties: { service: { type: 'string' } },
    required: ['service'],
  },
  outputSchema: {
    type: 'object',
    properties: {
      service: { type: 'string' },
      status: { type: 'string', enum: ['ok', 'degraded', 'down'] },
      latencyMs: { type: 'number' },
    },
    required: ['service', 'status', 'latencyMs'],
  },
}

// 2. Configure um cliente MCP simulado
const mock = createMockMcpClient({ tools: [healthCheckTool] })
mock.mockTool('health_check').resolves({ service: 'weather', status: 'ok', latencyMs: 12 })
mock.mockTool('flaky_tool').rejects('limite de taxa')

// 3. Encadeie as asserções fluentes
const result = await mock.callTool('health_check', { service: 'weather' })

expectMcp(result)
  .toBeValidMcpResponse()
  .not.toBeError()
  .toContainText('weather')
  .toMatchOutputSchema(healthCheckTool)