zig-mcp

zig-mcp

Servidor MCP para Zig que conecta assistentes de codificação de IA ao ZLS por meio do Protocolo de Servidor de Linguagem.

Funciona com Claude Code, Cursor, Windsurf e qualquer cliente compatível com MCP.

AI assistant  <--(MCP stdio)-->  zig-mcp  <--(LSP pipes)-->  ZLS
                                    |
                             zig build / test / check

Requisitos

• Zig 0.17.0-dev.1415+64dfaa568 ou mais recente
• ZLS (detectado automaticamente no PATH, ou especifique com --zls-path)

Instalação

Plugin do Claude Code (recomendado)

Instale diretamente pela interface do Claude Code — sem necessidade de compilação manual:

# 1. Add the marketplace
/plugin marketplace add nzrsky/zig-mcp

# 2. Install the plugin
/plugin install zig-mcp@zig

Ou como um comando único no terminal:

claude plugin marketplace add nzrsky/zig-mcp && claude plugin install zig-mcp@zig

O binário é compilado automaticamente no primeiro uso. Apenas certifique-se de que zig e zls estejam no seu PATH.

Compilação manual

git clone https://github.com/nzrsky/zig-mcp.git
cd zig-mcp
zig build -Doptimize=ReleaseFast

O binário está em zig-out/bin/zig-mcp.

Configuração (somente instalação manual)

Se você instalou pelo sistema de plugins, pule esta seção — tudo já está configurado automaticamente.

Claude Code

# add globally
claude mcp add zig-mcp -- /absolute/path/to/zig-mcp --workspace /path/to/your/zig/project

# add for current project only
claude mcp add --scope project zig-mcp -- /absolute/path/to/zig-mcp --workspace /path/to/your/zig/project

Ou edite ~/.claude/mcp_servers.json:

{
  "mcpServers": {
    "zig-mcp": {
      "command": "/absolute/path/to/zig-mcp",
      "args": ["--workspace", "/path/to/your/zig/project"]
    }
  }
}

Se você omitir --workspace, o zig-mcp usa o diretório de trabalho atual.

Cursor

Adicione a .cursor/mcp.json no seu projeto:

{
  "mcpServers": {
    "zig-mcp": {
      "command": "/absolute/path/to/zig-mcp",
      "args": ["--workspace", "/path/to/your/zig/project"]
    }
  }
}

Windsurf

Adicione a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "zig-mcp": {
      "command": "/absolute/path/to/zig-mcp",
      "args": ["--workspace", "/path/to/your/zig/project"]
    }
  }
}

Opções

--workspace, -w <path>   Project root directory (default: cwd)
--zls-path <path>        Path to ZLS binary (default: auto-detect from PATH)
--help, -h               Show help
--version                Show version

Ferramentas

Todas respondem a partir do modelo semântico do ZLS — a parte que um shell e uma busca de texto não conseguem alcançar.

Ferramenta	O que ela sabe que o grep não sabe
zig_definition	A única declaração verdadeira, rastreada por imports e aliases. Aceita symbol ou file+line+character
zig_references	Usos reais, cientes de escopo; ignora identificadores homônimos, comentários e strings. O modo symbol também busca por re-exports
zig_hover	O tipo após avaliação comptime e inferência — invisível no texto-fonte
zig_diagnostics	Erros de um arquivo sem compilar o projeto, ressincronizado com o disco antes
zig_workspace_symbols	Declarações por nome, não toda linha que as menciona
zig_document_symbols	O esboço de um arquivo: declarações, tipos, aninhamento
zig_completion	O que pode legalmente vir a seguir em uma posição, com tipos
zig_signature_help	A assinatura real, incluindo parâmetros comptime e genéricos
zig_rename	Quais arquivos uma renomeação afeta, ciente de escopo
zig_code_action	Correções rápidas que o ZLS oferece para um intervalo
zig_inlay_hints	Todos os tipos inferidos em um arquivo de uma vez — nada disso está no texto-fonte
zig_type_definition	A declaração do tipo de um valor, não do valor
zig_ast_query	Código por forma: catch {} vazio, inicializadores de catch unreachable, undefined, unreachable, @panic. Correspondência na árvore sintática, então comentários e literais de string nunca coincidem e formas multilinha sempre coincidem
zig_unused_private	Declarações privadas às quais nada se refere — exato, porque um nome não-pub não pode escapar do seu arquivo

O que está deliberadamente ausente

Não há zig_build, zig_test, zig_format, zig_version, zig_check ou zig_manage. Eles existiam e envolviam zig build, zig test, zig fmt, zig version, zig ast-check e zvm — e um wrapper perde para o shell que ele envolve: sem pipes, sem redirecionamento, sem diretório de trabalho próprio. Transcrições de sessão resolvem isso: 526 invocações de zig build através do shell, zero chamadas à ferramenta. Execute-as com o seu shell.

Como funciona

O zig-mcp inicia o ZLS como processo filho e conversa com ele via stdin/stdout usando o protocolo LSP (enquadramento Content-Length). Do outro lado, ele fala MCP (JSON-RPC delimitado por nova linha) com o assistente de IA.

Três threads:

• main — lê requisições MCP, despacha chamadas de ferramentas, escreve respostas
• reader — lê respostas LSP do ZLS, correlaciona por ID de requisição
• stderr — encaminha o stderr do ZLS para o log do servidor

Se o ZLS travar, o zig-mcp o reinicia automaticamente e reabre todos os documentos rastreados.

Os arquivos são abertos no ZLS de forma preguiçosa no primeiro acesso e ressincronizados (didChange) sempre que seu conteúdo mudar no disco — sem necessidade de gerenciar o estado dos documentos manualmente.

Desenvolvimento

# build
zig build

# run tests (162 unit tests, including a fake-ZLS harness)
zig build test

# quality gates: lint, coverage, dead code, mutants
make lint cov deadcode mutants

# run manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | \
  zig-out/bin/zig-mcp --workspace . 2>/dev/null

Licença

MIT