zig-docs-mcp

Servidor MCP local de código abierto + habilidades de agente que sirven documentación oficial de Zig siempre actualizada para la última versión, un corpus de guía de software ligero de alto rendimiento seleccionado, y una auto-actualización segura con simulación previa (dry-run) para una cadena de herramientas Zig local desactualizada.

zig-docs-mcp
├── zigdocs                 MCP server (stdio, local, no accounts)
├── guidance/               curated performance guidance (12 topics)
├── skills/zig-docs         agent skill: operating rules for Zig work
└── skills/zig-docs-mcp     agent skill: Python integration (`zdoc` singleton)

Zig cambia rápido, y las respuestas de la memoria de entrenamiento se quedan obsoletas entre versiones menores — 0.16 reemplazó toda la capa de E/S y movió Dir de std.fs a std.Io. Este servidor obtiene documentación oficial y fuentes std publicadas en cada llamada (con revalidación TTL corta), de modo que cada respuesta cita la versión de la que proviene. Cuando tu compilador local se queda atrás respecto a la documentación, el servidor lo indica y ofrece una actualización controlada. Nunca modifica tu sistema sin confirmación explícita.

Tabla de contenido

1. Por qué

2. Cómo se mantiene actualizado

3. Requisitos

4. Instalar el servidor

5. Conectar un cliente MCP

6. Integración con Prime Agent

7. Referencia de herramientas MCP

8. Auto-actualización de la cadena de herramientas

9. Corpus de guía

10. Configuración

11. Desarrollo

12. Solución de problemas

13. Licencia

Related MCP server: Zignet

Por qué

• La documentación se queda obsoleta rápidamente. El diseño de la biblioteca estándar de Zig cambia entre versiones menores. Servir las fuentes reales de la última versión es la única fuente fiable de verdad de la API. zig_std resuelve símbolos recorriendo las re-exportaciones reales en el árbol publicado, no una instantánea extraída.

• El consejo de rendimiento debería ser mecánico. El corpus incluido explica estrategia de asignación, diseño de datos, comptime, tamaño del binario, latencia de arranque, SIMD, concurrencia y benchmarks, basándose en cómo se comportan realmente el hardware y el runtime (líneas de caché, syscalls, fallos de página), no en sensaciones.

• Un compilador desactualizado invalida silenciosamente todo. zig_version_status compara tu cadena de herramientas con el índice ascendente en cada comprobación, y zig_update ofrece un plan de actualización concreto y revisable.

• Todo es local-primero. El servidor se ejecuta en tu máquina a través de stdio. Sin cuentas, sin tokens, sin telemetría. La red solo se usa para ziglang.org para documentación, notas de versión y archivos fuente.

Cómo se mantiene actualizado

• Las respuestas en caché se revalidan contra ziglang.org cuando tienen más de 6 horas (force=true revalida inmediatamente). La revalidación usa GET condicionales (ETag / Last-Modified), por lo que es económica.

• Seguro sin conexión: si la red no está disponible, el contenido en caché se sirve con una marca stale en lugar de fallar. (La primera ejecución necesita red una vez).

• Las fuentes std provienen del archivo src oficial por versión, el contenido canónico incluso cuando las etiquetas de versión de GitHub se retrasan (0.16.0 no estaba etiquetado en GitHub cuando se construyó esto). El archivo se descarga una vez por versión y solo se extrae lib/std/**.

• El parámetro channel selecciona stable (última versión, por defecto) o master (nocturno), para que puedas previsualizar los cambios de la próxima versión.

Diseño de caché (~/.cache/zig-docs-mcp/, se puede sobrescribir con ZIG_DOCS_MCP_CACHE):

~/.cache/zig-docs-mcp/
├── http/                    upstream bodies + ETag/Last-Modified metadata
├── langref-0.16.0.json      parsed reference sections (per version)
├── notes-0.16.0.json        release-notes digest
├── zig-0.16.0-src.tar.xz    source tarball cache
└── src/0.16.0/lib/std/      extracted std sources (550 files)

Requisitos

• Python ≥ 3.10 y uv

• macOS o Linux (la auto-actualización soporta instalaciones Homebrew y autónomas; Windows obtiene un plan de impresión funcional pero aún no una estrategia de archivos)

• Acceso de red a ziglang.org para las primeras descargas y revalidación

Instalar el servidor

git clone https://github.com/gbrlpzz/zig-docs-mcp
cd zig-docs-mcp
uv tool install .          # installs the `zigdocs` command on your PATH
zigdocs --help             # verify

¿Prefieres no instalarlo? Ejecútalo directamente desde el clon:

uv run --project ~/zig-docs-mcp zigdocs

Conectar un cliente MCP

Cualquier cliente MCP que hable stdio. Apúntalo al comando zigdocs:

{
  "mcpServers": {
    "zig-docs": {
      "command": "zigdocs"
    }
  }
}

Sin una instalación global, usa el clon directamente:

{
  "mcpServers": {
    "zig-docs": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/zig-docs-mcp", "zigdocs"]
    }
  }
}

Integración con Prime Agent

Dos habilidades se incluyen en este repositorio. Crea enlaces simbólicos y reinicia la sesión (o ejecuta /reload):

ln -sfn ~/zig-docs-mcp/skills/zig-docs     ~/.agents/skills/zig-docs
ln -sfn ~/zig-docs-mcp/skills/zig-docs-mcp ~/.agents/skills/zig-docs-mcp

Luego, desde el kernel del agente:

from zig_docs_mcp import zdoc

await zdoc.zig_version_status()                       # local vs latest upstream
await zdoc.zig_update()                               # dry-run upgrade plan
await zdoc.zig_update(dry_run=False, confirm=True)    # apply after user agrees
await zdoc.zig_langref(section="Errors")              # fresh language reference
await zdoc.zig_std(symbol="std.heap.ArenaAllocator")  # std docs from released source
await zdoc.zig_changelog()                            # what changed in the release
await zdoc.perf_guidance(topic="allocation-strategy") # curated guidance
await zdoc.zig_search(query="vectorization")          # search everything at once

Las llamadas devuelven su resultado como una cadena JSON (las lecturas de guía de tema completo devuelven markdown sin procesar); analiza con json.loads(...) cuando necesites campos como version o docs. Los argumentos son solo de palabra clave. El comando del servidor se resuelve en orden: ZIG_DOCS_MCP_CMD, un zigdocs en PATH, luego uv run --project contra ZIG_DOCS_MCP_REPO (por defecto ~/zig-docs-mcp).

skills/zig-docs/SKILL.md contiene las reglas operativas que sigue el agente: comprobar versión primero, documentación antes que código, citar la versión de la documentación y nunca aplicar una actualización sin la aprobación explícita del usuario.

Referencia de herramientas MCP

zig_version_status

Compara el zig version local con la última versión ascendente.

{
 "local_version": "0.16.0",
 "local_path": "/opt/homebrew/bin/zig",
 "latest_stable": "0.16.0",
 "master": "0.17.0-dev.1818+7051f8e73",
 "up_to_date": true
}

Cuando la cadena de herramientas local es más antigua, la respuesta añade behind y una suggestion que apunta a zig_update (ejemplo ilustrativo):

{
 "local_version": "0.15.2",
 "latest_stable": "0.16.0",
 "up_to_date": false,
 "behind": "local 0.15.2 < latest 0.16.0",
 "suggestion": "Call the zig_update tool (dry-run first) to upgrade the local toolchain to the latest stable release."
}

zig_update

Actualiza la cadena de herramientas local. La simulación previa (dry-run) es el valor predeterminado: imprime el plan exacto y no cambia nada. Aplicar requiere dry_run=false, confirm=true. Consulta Auto-actualización de la cadena de herramientas.

zig_langref

Referencia oficial del lenguaje, obtenida recientemente para la versión del canal.

• section="Errors" → texto completo de la sección (los bloques de código se conservan):

### Error Set Type
An error set is like an enum. However, each error name across the entire
compilation gets assigned an unsigned integer greater than 0. ...

• query="vector" → secciones clasificadas:

[{"section_id": "Vectors", "title": "Vectors§"},
 {"section_id": "Builtin-Functions", "title": "Builtin Functions§"}]

• sin argumentos → la lista de todos los ids de sección.

zig_std

Documentación de la biblioteca estándar de la fuente publicada exacta. La resolución de símbolos recorre las re-exportaciones reales (std.zig → heap.zig → heap/ArenaAllocator.zig), sigue los alias de @import y devuelve la documentación /// más el texto de la declaración de esa versión:

{
 "symbol": "std.ArrayList",
 "version_source": "0.16.0",
 "file": "lib/std/std.zig",
 "line": 49,
 "declaration": "pub fn ArrayList(comptime T: type) type {\n    return array_list.Aligned(T, null);\n}",
 "docs": "A contiguous, growable list of items in memory. This is a wrapper around a\nslice of `T` values. ..."
}

Si un nombre no es una declaración de nivel superior simple en el espacio de nombres recorrido (los diseños se mueven entre versiones), la herramienta recurre a una búsqueda en todo el corpus de declaraciones de nivel superior, mejor coincidencia primero, por ejemplo, std.fs.Dir en 0.16 muestra correctamente lib/std/Io/Dir.zig. query="arena" busca directamente en los comentarios de documentación de std.

zig_changelog

Resumen de notas de versión para la versión del canal actual: títulos de sección más un breve resumen de cada una. Útil justo después de que se publique una versión (zig_changelog(force=true)).

perf_guidance

Guía seleccionada para software ligero de alto rendimiento. Sin argumentos lista temas; topic="allocation-strategy" devuelve la guía completa (markdown sin procesar con Principio / Mecánica / Modismo de Zig / Anti-patrones / Reglas generales); query=... busca en todas las guías.

zig_search

Búsqueda unificada en langref, comentarios de documentación de std y guía:

{"query": "vectorization", "langref": [...], "guidance": [...], "std": [...], "std_version": "0.16.0"}

scope lo reduce: all (predeterminado) | langref | std | guidance.

Auto-actualización de la cadena de herramientas

zig_update elige una estrategia automáticamente:

1. Zig gestionado por Homebrew (el binario se resuelve dentro del prefijo de brew) → brew upgrade zig:

{
 "mode": "dry-run (nothing changed). Re-run with confirm=true to apply.",
 "target_version": "0.16.0",
 "current": "0.16.0",
 "strategy": "homebrew",
 "command": ["brew", "upgrade", "zig"],
 "note": "Homebrew formula may lag the newest release slightly."
}

2. Instalación autónoma (archivo oficial, cualquier otra ubicación) → descarga el archivo de la plataforma del índice ascendente, lo extrae en ~/.local/opt/zig-<version> y crea un enlace simbólico ~/.local/bin/zig:

{
 "strategy": "standalone-tarball",
 "download": "https://ziglang.org/download/0.16.0/zig-aarch64-macos-0.16.0.tar.xz",
 "install_dir": "~/.local/opt/zig-0.16.0",
 "steps": ["download ...", "extract ...", "symlink ~/.local/bin/zig -> .../zig/zig"],
 "activation": "~/.local/bin is first on PATH; new zig takes effect immediately"
}

Si ~/.local/bin no es lo primero en PATH, el plan lo dice explícitamente: el compilador antiguo seguiría ganando, y la herramienta te dice cómo arreglar el orden.

Reglas de seguridad:

• El valor predeterminado es una simulación. No se descarga, mueve ni enlaza nada.

• Aplicar requiere dry_run=false, confirm=true juntos.

• Se instruye a los agentes que usan este servidor para que muestren el plan y obtengan la aprobación explícita del usuario antes de confirmar.

Corpus de guía

Doce temas en guidance/, incluidos en la rueda y servidos por perf_guidance. Los principios son universales; los fragmentos son de la era Zig 0.16; la verdad exacta de la API siempre proviene de zig_std, nunca del corpus.

Configuración

Desarrollo

make sync    # deps
make test    # unit tests (offline; std-source tests skip without warm cache)
make e2e     # spawns the real server over stdio, calls every tool
make fmt     # ruff format + check

El conjunto de pruebas e2e necesita red en la primera ejecución (calienta la caché). Las pruebas unitarias que ejercitan la resolución de símbolos se ejecutan contra la caché de fuentes std caliente y se omiten limpiamente cuando no está presente.

Solución de problemas

• zigdocs server not found (habilidad de Prime Agent): instala con uv tool install . desde el clon, o establece ZIG_DOCS_MCP_REPO a la ruta del clon, o establece ZIG_DOCS_MCP_CMD a una línea de comandos completa.

• La primera ejecución falla sin conexión: la caché comienza vacía; obtén una vez mientras estés en línea. Después, la alternativa de caché obsoleta mantiene todas las herramientas funcionando.

• Los resultados parecen obsoletos después de una nueva versión: pasa force=true (de lo contrario, se aplica el TTL de 6 horas).

• zig version sigue siendo antiguo después de una actualización: se necesita un nuevo shell, y ~/.local/bin debe preceder al directorio de instalación anterior en PATH. El plan de simulación indica la situación exacta de tu máquina.

• El zig de Homebrew se retrasa con la versión más reciente: las fórmulas de brew se retrasan con las versiones; usa la estrategia autónoma (elimina la fórmula de brew, instala autónoma) si necesitas versiones del primer día.

Licencia

MIT — consulta LICENSE.