Servidor MCP para SDD: como validar código contra a spec

Linters e analisadores estáticos

Linters respondem se o código segue as convenções do projeto. No ecossistema .NET, isso inclui os analyzers do Roslyn, o dotnet format e as regras do .editorconfig.

Quando essas checagens rodam por meio de uma tool, o agente recebe a lista de avisos logo depois de escrever o arquivo. Dessa forma, ele corrige o problema na mesma iteração, antes que o erro chegue ao pull request.

Validadores de OpenAPI e JSON Schema

Validadores de contrato respondem se a API faz o que a spec promete. Aqui entram ferramentas como o Spectral, que faz lint de documentos OpenAPI, e bibliotecas que verificam se um payload respeita o JSON Schema declarado.

O ASP.NET Core facilita muito esse trabalho. Desde o .NET 9 o framework gera documentos OpenAPI nativamente, e o pacote Microsoft.Extensions.ApiDescription.Server produz esse documento durante o build.

Além disso, no .NET 10 o documento segue o OpenAPI 3.1 e usa o JSON Schema draft 2020-12. Ou seja, o mesmo validador serve tanto para o contrato quanto para a implementação.

Checadores de conformidade

Checadores de conformidade respondem se o código respeita regras que não cabem em um schema. No Spec Kit, essas regras vivem na constitution, o documento com princípios que nenhuma feature pode quebrar.

Por exemplo, uma regra pode exigir que todo endpoint de escrita retorne ProblemDetails em caso de erro. Outra pode proibir dependências entre dois módulos específicos.

Essas checagens costumam ser scripts ou testes de arquitetura. Quando o servidor MCP as expõe como tools, o agente consegue executá-las sozinho, sem que alguém precise lembrar de rodar cada uma.

Reprovação não é erro de execução

A especificação do MCP separa dois tipos de falha. Erros de protocolo, como um método inexistente, voltam como erros JSON-RPC, enquanto erros de execução da tool voltam como um resultado comum com isError: true.

Essa distinção existe para que o cliente devolva a falha ao modelo e ele tente se corrigir. Contudo, uma implementação reprovada não representa uma falha da tool, porque a validação rodou e chegou a uma conclusão.

Por isso, um servidor MCP bem desenhado reserva o isError para quando a verificação não consegue rodar, como um contrato ausente ou um build quebrado. Já a reprovação volta como resultado normal, com approved: false e o conteúdo estruturado.

Assim, o agente distingue "não consegui verificar" de "verifiquei e você violou a spec". São situações diferentes, e cada uma pede uma reação diferente.

Configurando o servidor MCP no projeto

O servidor MCP roda como uma aplicação de console com transporte stdio. Esse formato é o mais simples para uso local, porque o host inicia o processo e conversa com ele pela entrada e saída padrão.

dotnet new console -n SpecArbiter
cd SpecArbiter
dotnet add package ModelContextProtocol
dotnet add package Microsoft.Extensions.Hosting
dotnet add package JsonSchema.Net

O Program.cs registra o servidor e os serviços de apoio. Em seguida, ele descobre automaticamente as tools e os resources do assembly.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using SpecArbiter;

var builder = Host.CreateApplicationBuilder(args);

// No transporte stdio, todo log precisa ir para o stderr
builder.Logging.AddConsole(options =>
    options.LogToStandardErrorThreshold = LogLevel.Trace);

builder.Services.AddSingleton<ActiveSpec>();
builder.Services.AddSingleton<OpenApiSnapshot>();

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly()
    .WithResourcesFromAssembly();

await builder.Build().RunAsync();

Note que todo log vai para o stderr. Como o stdout carrega as mensagens JSON-RPC, qualquer texto extra nesse canal quebraria a comunicação com o cliente.

Expondo a especificação ativa

A classe ActiveSpec localiza o contrato da feature em andamento. Para manter o exemplo direto, a pasta chega por variável de ambiente.

using System.Text.Json.Nodes;
using ModelContextProtocol;

namespace SpecArbiter;

public sealed class ActiveSpec
{
    // Pasta da feature ativa do Spec Kit, por exemplo specs/003-orders
    private readonly string _featureDirectory =
        Environment.GetEnvironmentVariable("ACTIVE_SPEC_DIR")
        ?? throw new InvalidOperationException("ACTIVE_SPEC_DIR is not set.");

    public string ContractPath =>
        Path.Combine(_featureDirectory, "contracts", "openapi.json");

    public JsonNode LoadContract()
    {
        if (!File.Exists(ContractPath))
            throw new McpException($"Contract not found at {ContractPath}. Run /speckit.plan first.");

        return JsonNode.Parse(File.ReadAllText(ContractPath))!;
    }
}

Quando o contrato não existe, a classe lança uma McpException. Nesse caso, o SDK converte a exceção em um resultado com isError: true, e a mensagem orienta o agente a rodar o /speckit.plan primeiro.

Depois disso, um resource disponibiliza o contrato como contexto. Dessa forma, o agente lê a fonte da verdade antes de escrever a primeira linha.

using System.ComponentModel;
using ModelContextProtocol.Server;

namespace SpecArbiter;

[McpServerResourceType]
public sealed class SpecResources(ActiveSpec spec)
{
    [McpServerResource(
        UriTemplate = "spec://active/contract",
        Name = "active_contract",
        MimeType = "application/json")]
    [Description("OpenAPI contract of the feature currently being implemented.")]
    public string GetContract() => spec.LoadContract().ToJsonString();
}

Comparando o contrato com a implementação

Para saber o que o código realmente expõe, o servidor MCP não lê os arquivos C#. Em vez disso, ele usa o próprio ASP.NET Core para gerar o documento OpenAPI da implementação durante o build.

Para isso, o projeto da API recebe o pacote Microsoft.Extensions.ApiDescription.Server e estas propriedades no .csproj.

<PropertyGroup>
  <!-- Gera o OpenAPI da implementação a cada build -->
  <OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild>
  <OpenApiDocumentsDirectory>openapi</OpenApiDocumentsDirectory>
  <OpenApiGenerateDocumentsOptions>--file-name implementation</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

A classe OpenApiSnapshot dispara o build e lê o documento gerado. Se a compilação falhar, ela lança uma exceção, porque não faz sentido validar o contrato de um código que nem compila.

using System.Diagnostics;
using System.Text.Json.Nodes;
using ModelContextProtocol;

namespace SpecArbiter;

public sealed class OpenApiSnapshot
{
    private readonly string _apiProject =
        Environment.GetEnvironmentVariable("API_PROJECT_PATH")
        ?? throw new InvalidOperationException("API_PROJECT_PATH is not set.");

    public async Task<JsonNode> GenerateAsync(CancellationToken cancellationToken)
    {
        // O build dispara a geração do OpenAPI pelo ApiDescription.Server
        using var process = Process.Start(new ProcessStartInfo(
            "dotnet", $"build \"{_apiProject}\" --nologo -v q")
        {
            RedirectStandardOutput = true
        })!;

        var output = await process.StandardOutput.ReadToEndAsync(cancellationToken);
        await process.WaitForExitAsync(cancellationToken);

        if (process.ExitCode != 0)
            throw new McpException($"Build failed. Fix compilation errors first.{Environment.NewLine}{output}");

        var file = Path.Combine(
            Path.GetDirectoryName(_apiProject)!, "openapi", "implementation.json");

        return JsonNode.Parse(await File.ReadAllTextAsync(file, cancellationToken))!;
    }
}

Com os dois documentos em mãos, a tool check_api_conformance compara as operações e os status codes. Ela reprova endpoints ausentes, status codes faltando e qualquer rota que não esteja na spec.

using System.ComponentModel;
using System.Text.Json.Nodes;
using ModelContextProtocol.Server;

namespace SpecArbiter;

public sealed record Violation(string Rule, string Location, string Message);

public sealed record Verdict(bool Approved, int TotalViolations, IReadOnlyList<Violation> Violations);

[McpServerToolType]
public sealed partial class ConformanceTools(ActiveSpec spec, OpenApiSnapshot snapshot)
{
    private static readonly string[] HttpMethods = ["get", "post", "put", "patch", "delete"];

    [McpServerTool(Name = "check_api_conformance", ReadOnly = true, UseStructuredContent = true)]
    [Description("Builds the API and compares every endpoint with the active OpenAPI contract. " +
                 "Call it before marking any task as done. " +
                 "Approved=false means the implementation violates the spec and must be fixed.")]
    public async Task<Verdict> CheckApiConformanceAsync(CancellationToken cancellationToken)
    {
        var expected = ListOperations(spec.LoadContract());
        var actual = ListOperations(await snapshot.GenerateAsync(cancellationToken));
        var violations = new List<Violation>();

        foreach (var (operation, statusCodes) in expected)
        {
            if (!actual.TryGetValue(operation, out var implementedCodes))
            {
                violations.Add(new("missing-operation", operation,
                    "Endpoint defined in the spec was not implemented."));
                continue;
            }

            foreach (var code in statusCodes.Except(implementedCodes))
                violations.Add(new("missing-status-code", operation,
                    $"Status code {code} is required by the spec."));
        }

        // Rotas que existem no código mas não na spec também reprovam
        foreach (var operation in actual.Keys.Except(expected.Keys))
            violations.Add(new("undocumented-operation", operation,
                "Endpoint is not part of the spec. Remove it or update the spec first."));

        return new Verdict(violations.Count == 0, violations.Count, violations);
    }

    private static Dictionary<string, HashSet<string>> ListOperations(JsonNode document)
    {
        var operations = new Dictionary<string, HashSet<string>>(StringComparer.OrdinalIgnoreCase);

        if (document["paths"] is not JsonObject paths)
            return operations;

        foreach (var (path, item) in paths)
        foreach (var method in HttpMethods)
        {
            if (item?[method] is not JsonObject operation)
                continue;

            HashSet<string> codes = operation["responses"] is JsonObject responses
                ? responses.Select(response => response.Key).ToHashSet()
                : [];

            operations[$"{method.ToUpperInvariant()} {path}"] = codes;
        }

        return operations;
    }
}

Repare na descrição da tool. Ela diz ao modelo quando chamar a ferramenta e o que significa um Approved falso, e essa instrução pesa tanto quanto o código.

Também vale notar o ReadOnly = true. Esse atributo vira uma anotação que informa ao host que a tool não altera nada no ambiente.

Validando respostas contra o JSON Schema

Bater rotas e status codes ainda não basta. Um endpoint pode existir, retornar 201 e mesmo assim devolver um corpo que não respeita o schema da spec.

A segunda tool do servidor MCP recebe um payload real e valida o corpo contra o schema declarado no contrato. O agente pode obter esse payload em um teste de integração ou chamando a API local.

using System.ComponentModel;
using System.Text.Json;
using System.Text.Json.Nodes;
using Json.Schema;
using ModelContextProtocol.Server;

namespace SpecArbiter;

public sealed partial class ConformanceTools
{
    [McpServerTool(Name = "validate_response_payload", ReadOnly = true, UseStructuredContent = true)]
    [Description("Validates a JSON payload returned by an endpoint against the response schema of the active contract.")]
    public Verdict ValidateResponsePayload(
        [Description("HTTP method, for example POST")] string method,
        [Description("Path exactly as in the contract, for example /orders/{id}")] string path,
        [Description("Response status code, for example 201")] string statusCode,
        [Description("Raw JSON returned by the endpoint")] string payload)
    {
        var contract = spec.LoadContract();
        var schemaNode = contract["paths"]?[path]?[method.ToLowerInvariant()]
            ?["responses"]?[statusCode]?["content"]?["application/json"]?["schema"];

        if (schemaNode is null)
            return new Verdict(false, 1,
            [
                new("missing-schema", $"{method} {path} {statusCode}",
                    "The spec declares no JSON schema for this response.")
            ]);

        // Copia os componentes do contrato para $defs e resolve os $ref
        var root = new JsonObject
        {
            ["$schema"] = "https://json-schema.org/draft/2020-12/schema",
            ["$defs"] = contract["components"]?["schemas"]?.DeepClone() ?? new JsonObject(),
            ["allOf"] = new JsonArray(schemaNode.DeepClone())
        };

        var schema = JsonSchema.FromText(
            root.ToJsonString().Replace("#/components/schemas/", "#/$defs/"));

        using var instance = JsonDocument.Parse(payload);
        var result = schema.Evaluate(instance.RootElement,
            new EvaluationOptions { OutputFormat = OutputFormat.List });

        var violations = (result.Details ?? [])
            .Where(detail => detail.Errors is { Count: > 0 })
            .SelectMany(detail => detail.Errors!.Select(error => new Violation(
                $"schema:{error.Key}", detail.InstanceLocation.ToString(), error.Value)))
            .ToList();

        return new Verdict(result.IsValid, violations.Count, violations);
    }
}

O truque está na montagem do schema, já que o OpenAPI guarda os tipos em components/schemas. Por isso, a tool copia esses tipos para $defs e reescreve as referências, resolvendo cada $ref sem carregar o documento inteiro.

Com o formato de saída em lista, cada erro traz o caminho exato dentro do JSON. Então o agente recebe algo como /total com a mensagem de tipo incorreto, e não apenas um aviso genérico de payload inválido.