zig-mcp

zig-mcp

Servidor MCP para Zig que conecta asistentes de codificación con IA a ZLS a través del Protocolo de Servidor de Lenguaje.

Funciona con Claude Code, Cursor, Windsurf y cualquier cliente compatible con MCP.

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

Requisitos

• Zig 0.17.0-dev.1415+64dfaa568 o más reciente
• ZLS (detección automática desde PATH, o especificar con --zls-path)

Instalación

Plugin de Claude Code (recomendado)

Instala directamente desde la interfaz de Claude Code — no se necesita compilación manual:

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

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

O como una línea desde la terminal:

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

El binario se compila automáticamente en el primer uso. Solo asegúrate de que zig y zls estén en tu PATH.

Compilación manual

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

El binario está en zig-out/bin/zig-mcp.

Configuración (solo instalación manual)

Si instalaste mediante el sistema de plugins, omite esta sección — todo está configurado automáticamente.

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

O edita ~/.claude/mcp_servers.json:

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

Si omites --workspace, zig-mcp usa el directorio de trabajo actual.

Cursor

Añade a .cursor/mcp.json en tu proyecto:

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

Windsurf

Añade a ~/.codeium/windsurf/mcp_config.json:

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

Opciones

--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

Herramientas

Todas responden desde el modelo semántico de ZLS — la parte que un shell y una búsqueda de texto no pueden alcanzar.

Herramienta	Lo que sabe que grep no sabe
zig_definition	La única declaración verdadera, seguida a través de imports y alias. Toma symbol o file+line+character
zig_references	Usos reales, conscientes del ámbito; omite identificadores con el mismo nombre, comentarios y cadenas. El modo symbol también busca a través de re-exportaciones
zig_hover	El tipo después de la evaluación comptime y la inferencia — invisible en el texto fuente
zig_diagnostics	Errores para un archivo sin compilar el proyecto, re-sincronizado contra el disco primero
zig_workspace_symbols	Declaraciones por nombre, no cada línea que las menciona
zig_document_symbols	El esquema de un archivo: declaraciones, tipos, anidamiento
zig_completion	Lo que legalmente puede seguir en una posición, con tipos
zig_signature_help	La firma real, incluidos parámetros comptime y genéricos
zig_rename	Qué archivos toca un renombrado, consciente del ámbito
zig_code_action	Correcciones rápidas que ZLS ofrece para un rango
zig_inlay_hints	Todos los tipos inferidos en un archivo a la vez — nada de esto está en el texto fuente
zig_type_definition	La declaración del tipo de un valor, no del valor
zig_ast_query	Código por forma: catch {} vacío, inicializadores catch unreachable, undefined, unreachable, @panic. Coincide sobre el árbol de sintaxis, por lo que los comentarios y literales de cadena nunca coinciden y las formas multilínea siempre lo hacen
zig_unused_private	Declaraciones privadas a las que nada se refiere — exacto, porque un nombre no-pub no puede escapar de su archivo

Lo que está deliberadamente ausente

No hay zig_build, zig_test, zig_format, zig_version, zig_check ni zig_manage. Solían existir y envolvían zig build, zig test, zig fmt, zig version, zig ast-check y zvm — y un envoltorio pierde contra el shell que envuelve: sin tuberías, sin redirección, sin directorio de trabajo propio. Las transcripciones de sesión lo confirman: 526 invocaciones de zig build a través del shell, cero llamadas a la herramienta. Ejecuta esas con tu shell.

Cómo funciona

zig-mcp lanza ZLS como un proceso hijo y se comunica con él a través de stdin/stdout usando el protocolo LSP (encuadre Content-Length). En el otro lado, habla MCP (JSON-RPC delimitado por nuevas líneas) con el asistente de IA.

Tres hilos:

• main — lee solicitudes MCP, despacha llamadas de herramientas, escribe respuestas
• reader — lee respuestas LSP de ZLS, correlaciona por ID de solicitud
• stderr — reenvía el stderr de ZLS al registro del servidor

Si ZLS falla, zig-mcp lo reinicia automáticamente y reabre todos los documentos rastreados.

Los archivos se abren en ZLS de forma perezosa en el primer acceso y se re-sincronizan (didChange) cuando su contenido cambia en disco — no es necesario gestionar el estado del documento manualmente.

Desarrollo

# 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

Licencia

MIT