Microsoft Binlog MCP Server

O que é um arquivo binlog

O arquivo .binlog é o log binário estruturado do MSBuild. Ele registra, de forma comprimida e completa, praticamente tudo o que acontece durante uma compilação.

Um único arquivo pode conter a cadeia completa de imports de .props e .targets, os valores de todas as propriedades avaliadas e os itens processados. Além disso, guarda os erros com contexto completo de projeto, target e task, e os arquivos embutidos durante a build.

Para gerar um .binlog, basta adicionar o argumento /bl (ou -bl) a um comando do .NET CLI. Também é possível informar o nome do arquivo de saída.

# Gera msbuild.binlog no diretório atual
dotnet build /bl

# Gera arquivos com nomes específicos
dotnet test /bl:tests.binlog
dotnet pack /bl:package.binlog

Por padrão, o arquivo se chama msbuild.binlog e fica no diretório corrente. Segundo o artigo original, um .binlog costuma ser de 10 a 20 vezes menor do que um log de texto no nível de diagnóstico, mas traz muito mais detalhes.

A documentação do Microsoft Learn sobre logs do MSBuild mostra ainda como capturar binlogs dentro do Visual Studio. Para isso, você define a variável MSBUILDDEBUGENGINE como 1 antes de abrir a IDE.

O que é o Model Context Protocol

O Model Context Protocol (MCP) é um padrão aberto que permite a assistentes de IA invocar ferramentas externas de forma estruturada. Se o conceito for novo para você, vale ler antes o artigo o que é MCP.

Ao encapsular a análise de logs binários no Binlog MCP Server, a Microsoft permite que o assistente investigue sozinho. Assim, o desenvolvedor não precisa interpretar manualmente o conteúdo do arquivo.

O modelo de interação é simples. Primeiro, você faz uma pergunta em linguagem natural; em seguida, o assistente chama as ferramentas do servidor e sintetiza o resultado em uma resposta acionável.

Como funciona o Binlog MCP Server

O Binlog MCP Server é especializado na análise de arquivos .binlog do MSBuild. No lançamento, ele expunha 15 ferramentas organizadas em quatro categorias: investigação de build, arquivos embutidos, análise de performance e comparação de builds.

Com o servidor ativo, você pode perguntar ao assistente "por que meu build falhou?" ou "o que está deixando meu build lento?". Então, o assistente faz a investigação de forma autônoma, chamando as ferramentas necessárias na sequência correta.

O anúncio oficial foi assinado por Yuliia Kovalova e Jan Krivanek, engenheiros do time do .NET. Você encontra todos os detalhes no post AI-Powered MSBuild Investigation do .NET Blog.

As 15 ferramentas do Binlog MCP Server

No Binlog MCP Server, cada ferramenta tem um nome com o prefixo binlog_. Dessa forma, fica fácil reconhecer no chat quando o assistente está consultando o log.

Como configurar o Binlog MCP Server

O Binlog MCP Server é distribuído pelo repositório dotnet/skills no GitHub, por meio do plugin dotnet-msbuild. Esse é o mesmo repositório de skills do time do .NET apresentado no artigo a skill do time .NET para agentes de IA.

Por baixo, o Binlog MCP Server roda como uma ferramenta do .NET, o Microsoft.AITools.BinlogMcp. Portanto, você precisa do .NET SDK instalado na máquina.

{
  "chat.plugins.enabled": true,
  "chat.plugins.marketplaces": ["dotnet/skills"]
}

{
  "servers": {
    "binlog-mcp": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["tool", "run", "Microsoft.AITools.BinlogMcp"]
    }
  }
}

{
  "servers": {
    "binlog-mcp": {
      "type": "stdio",
      "command": "dotnet",
      "args": [
        "tool", "run", "Microsoft.AITools.BinlogMcp",
        "--", "--binlog", "msbuild.binlog"
      ]
    }
  }
}

/plugin marketplace add dotnet/skills
/plugin install dotnet-msbuild@dotnet-agent-skills

Diagnosticando uma falha com o Binlog MCP Server

O fluxo de trabalho com o Binlog MCP Server é direto e iterativo. Primeiro, gere o arquivo de log com /bl na build que apresenta o problema.

dotnet build /bl

Depois, faça a pergunta ao assistente de IA.

"Meu build falhou. Você consegue investigar o arquivo msbuild.binlog e me dizer o que deu errado?"

O assistente começa chamando binlog_overview para obter o status geral. Em seguida, invoca binlog_errors para recuperar os erros com contexto completo.

Dependendo do problema, ele pode usar binlog_explain_property para rastrear uma propriedade que causou o erro. Também pode recorrer ao binlog_search para localizar referências a um target específico.

No fim, você recebe uma síntese das descobertas com sugestões concretas de correção. Ou seja, não precisa abrir o Structured Log Viewer e navegar manualmente pela árvore de eventos.

Comparando dois builds

Um dos usos mais poderosos do Binlog MCP Server é comparar dois builds diferentes. Isso ajuda a descobrir o que mudou entre uma versão estável e uma branch de feature com lentidão ou comportamento inesperado.

O processo começa com dois arquivos .binlog, gerados a partir de estados diferentes do repositório.

# Build da branch principal
git checkout main
dotnet build /bl:build-a.binlog

# Build da branch de feature
git checkout my-feature
dotnet build /bl:build-b.binlog

Em seguida, faça a pergunta ao assistente.

"Compare build-a.binlog e build-b.binlog. Quais propriedades e versões de pacotes mudaram, e alguma dessas mudanças afetou a performance da build?"

Internamente, o assistente chama binlog_compare para listar as diferenças em propriedades e pacotes. Depois, usa binlog_expensive_projects e binlog_expensive_targets nos dois logs para correlacionar as mudanças com o tempo de execução.

Assim, o que antes exigia uma comparação manual e demorada vira uma única conversa.

O motor por baixo do Binlog MCP Server

O Binlog MCP Server usa a biblioteca do MSBuild Structured Log Viewer, o mesmo motor do popular aplicativo desktop de análise de binlogs. Isso garante fidelidade na interpretação, porque o assistente usa a mesma lógica de parse da ferramenta visual de referência.

A ferramenta binlog_search aceita a DSL completa do Structured Log Viewer. Ela inclui filtros por tipo de nó, como $error, $warning, $task, $target e $project, escopo hierárquico com under() e busca de frases exatas entre aspas.

Veja alguns exemplos de consultas nessa DSL.

$error under(MyProject.csproj)
$warning MSB3277
$task Csc under(Release)

A primeira consulta lista os erros de um projeto específico. Já a segunda filtra um código de warning, enquanto a terceira localiza a task do compilador C# dentro de um escopo.

Se você quiser inspecionar um arquivo sem instalar nada, existe ainda o Live Structured Log Viewer, que roda no navegador. Segundo a documentação do MSBuild, ele não captura dados dos binlogs abertos.

Telemetria e privacidade no Binlog MCP Server

O Binlog MCP Server emite telemetria anônima de uso por padrão, na mesma linha do .NET SDK. Os dados se limitam ao nome da ferramenta, latência, tamanho do resultado e status de sucesso ou falha.

Nenhum conteúdo do .binlog, caminho de arquivo ou mensagem de erro sai da máquina em formato legível. Os nomes de arquivo passam por hash HMAC-SHA256 apenas para correlação.

Para desativar a telemetria, defina a variável de ambiente padrão do .NET SDK.

export DOTNET_CLI_TELEMETRY_OPTOUT=1

No Windows, o equivalente com setx é o seguinte.

setx DOTNET_CLI_TELEMETRY_OPTOUT 1

Segurança ao compartilhar um binlog

A documentação do Microsoft Learn destaca um ponto importante. O .binlog captura quase tudo da build, inclusive o conteúdo dos arquivos de projeto, entradas e saídas das tasks e as variáveis de ambiente acessadas pela sessão do MSBuild.

Esse cuidado vale mesmo quando você usa o Binlog MCP Server localmente.

Em pipelines de CI/CD, segredos costumam chegar como variáveis de ambiente, como tokens de API e credenciais de feeds NuGet privados. Por isso, verifique o conteúdo do arquivo antes de compartilhá-lo externamente.

O próprio Structured Log Viewer permite inspecionar o arquivo visualmente antes de qualquer distribuição. Vale lembrar que o binlog geralmente não inclui o código-fonte compilado, mas registra nomes e caminhos completos dos arquivos.

Quando o Binlog MCP Server faz diferença

Em projetos pequenos, um dotnet build com a saída do terminal costuma resolver. No entanto, soluções de médio e grande porte acumulam dezenas de projetos, imports encadeados e pacotes com versões centralizadas.

Nesses cenários, o Binlog MCP Server encurta o caminho entre o sintoma e a causa. Por exemplo, um aviso de conflito de versão como o MSB3277 vira uma explicação objetiva, com o pacote e o projeto responsáveis.

O ganho também aparece em pipelines. Assim, basta publicar o .binlog como artefato do CI, baixá-lo e pedir a análise ao assistente.

Outro cenário comum é a lentidão que cresce aos poucos. Nesse caso, o Binlog MCP Server aponta os targets e tasks mais caros e mostra onde vale investir em otimização, por exemplo em builds incrementais que recompilam mais do que deveriam.

Para acompanhar as mudanças recentes do próprio MSBuild, leia também as novidades do MSBuild no .NET 11 Preview 1.

Conclusão

O Binlog MCP Server representa uma evolução significativa na forma como o ecossistema .NET diagnostica builds. Ao transformar a análise do .binlog em uma capacidade nativa dos assistentes de IA, a Microsoft reduz o tempo gasto para entender por que um build falhou ou ficou lento.

O servidor chegou em preview, com feedback coletado pelas issues do repositório dotnet/skills. Para times com soluções .NET de médio e grande porte, a integração com GitHub Copilot ou Claude Code via MCP pode encurtar bastante o diagnóstico em pipelines complexos.

FAQ

O servidor funciona com projetos que não usam o formato SDK-style?

Sim, segundo o artigo original. O servidor usa a biblioteca do Structured Log Viewer, que lê qualquer .binlog gerado pelo MSBuild, seja de projeto SDK-style ou de .csproj legado.

Preciso ter o .NET instalado para rodar o servidor MCP?

Sim. O servidor é distribuído como uma ferramenta do .NET, o Microsoft.AITools.BinlogMcp, que exige o .NET SDK na máquina onde o assistente roda.

O conteúdo do binlog é enviado para alguma API externa?

O servidor processa o arquivo localmente e a telemetria se limita a metadados anônimos de uso. Porém, lembre-se de que o modelo de IA recebe os trechos que o assistente consulta para montar a resposta.

Qual a diferença entre o servidor MCP e o Structured Log Viewer?

O Structured Log Viewer é um aplicativo visual para inspeção manual do .binlog. Já o servidor MCP expõe as mesmas capacidades como ferramentas que um assistente de IA chama automaticamente.

Posso usar o servidor com outros assistentes além do GitHub Copilot?

Sim. Qualquer assistente compatível com o Model Context Protocol pode usá-lo, incluindo o Claude Code no terminal.

Como gero um binlog para o dotnet test?

O argumento /bl funciona com dotnet build, dotnet test e dotnet pack. Para testes, use dotnet test /bl:tests.binlog.