Testando Seu Servidor MCP Como Se Importasse

A parte final da série ZeroMcp. A parte um abordou a exposição da sua API ASP.NET Core como um servidor MCP. A parte dois cobriu tudo o que cresceu desde então. A parte três abordou o ZeroMcp.Relay para qualquer API suportada por OpenAPI. Esta parte fecha o ciclo sobre a pergunta que você deve estar fazendo agora: como eu testo tudo isso?

Eu provavelmente deveria ter começado com isso: por profissão, sou um arquiteto de automação de testes que se especializa em ferramentas. Isso não é um contexto incidental — é por isso que o ZeroMcp existe da maneira que existe, uma forma de fornecer endpoints consistentes sem o fator "erro humano".

Quando você passa uma carreira construindo infraestrutura de testes, um instinto particular se torna automático: você não considera algo concluído até que possa verificar que funciona e detectar quando para de funcionar. Cada ferramenta no ecossistema ZeroMcp foi construída com esse instinto operando em segundo plano. O atributo [Mcp] executa seu pipeline real para que seus testes reais ainda passem. A interface do usuário do Tool Inspector permite que você execute ferramentas e inspecione resultados. O Relay valida especificações antes de começar a servir ferramentas. Mas nada disso respondeu à pergunta que realmente importava para mim: como você escreve um teste que prova que seu servidor MCP se comporta corretamente?

Há uma versão do desenvolvimento MCP onde você inicia seu servidor, abre o Claude Desktop e conversa manualmente com ele para ver se as ferramentas funcionam. Isso te leva bastante longe no início. Não te dá um pipeline CI, proteção contra regressões ou qualquer confiança de que uma mudança de esquema não quebrou silenciosamente as saídas das ferramentas.

O TestKit é onde o ciclo se fecha: ZeroMcp.TestKit.

A Arquitetura: Dois Repositórios, Uma Decisão de Design

O TestKit é dividido em dois repositórios, e essa divisão é intencional e vale a pena entender antes de qualquer outra coisa.

ZeroMcp.TeskKitEngine é um binário Rust autônomo chamado mcptest. Ele aceita definições de teste em JSON, conecta-se a qualquer servidor MCP, executa os testes e produz resultados estruturados em JSON. Ele não sabe nada sobre .NET, xUnit ou qualquer linguagem específica. Ele valida a correção do protocolo MCP, conformidade com o JSON Schema, determinismo, caminhos de erro e metadados da ferramenta — para qualquer servidor MCP, independentemente de como foi construído.

ZeroMcp.TestKit.dotnet é um DSL fluente em C# que envolve o motor. Você escreve testes em .NET idiomático, o DSL os serializa em JSON, chama o mcptest e analisa os resultados de volta. A integração com xUnit ([McpFact], [McpTheory], McpAssert) faz com que os testes apareçam no Visual Studio Test Explorer como qualquer outro projeto de teste.

A implicação: mcptest é o oráculo de correção. O DSL .NET é uma maneira conveniente de se comunicar com ele. Se você está construindo servidores MCP em Python ou Go, o motor funciona para você também — o binário Rust é a parte portátil.

Seu projeto de teste xUnit
        │
        ▼
ZeroMcp.TestKit (.NET DSL)
        │  serializa para JSON, chama
        ▼
mcptest (binário Rust)
        │  fala o protocolo MCP
        ▼
Seu servidor MCP (qualquer linguagem, qualquer transporte)

Início Rápido

using ZeroMcp.TestKit;

await McpTest
    .Server("http://localhost:8000/mcp")
    .Tool("search")
        .WithParams(new { query = "hello" })
        .ExpectSchemaMatch()
        .ExpectDeterministic()
    .RunAsync();

Esse é um teste completo. Ele se conecta ao seu servidor MCP, chama a ferramenta search com { "query": "hello" }, valida que a resposta está em conformidade com o JSON Schema declarado da ferramenta e afirma que chamá-la novamente produz o mesmo resultado. Se qualquer verificação falhar, RunAsync() lança McpTestException com os detalhes.

Instale:

Adicione ZeroMcp.TestKit e ZeroMcp.TestKit.Xunit via Nuget

O binário mcptest é resolvido automaticamente — primeiro do MCPTEST_PATH, depois do diretório bin, depois dos ativos nativos do NuGet (runtimes/{rid}/native/mcptest), depois do seu sistema PATH. Na maioria das vezes, você não precisa pensar sobre isso.

A API Fluente

O construtor é projetado para ler como uma especificação do que você espera:

await McpTest
    .Server("http://localhost:8000/mcp")
    .WithTimeout(TimeSpan.FromSeconds(30))
    .WithDeterminismRuns(5)
    .ValidateProtocol()
    .ValidateMetadata()
    .WithAutoErrorTests()
    .Tool("search")
        .WithParams(new { query = "hello" })
        .ExpectSchemaMatch()
        .ExpectDeterministic()
        .WithIgnorePaths("$.result.timestamp")
    .Tool("create_order")
        .WithParams(new { customerName = "Alice", product = "Widget", quantity = 2 })
        .ExpectSchemaMatch()
    .Tool(