zig-docs-mcp

Lokaler Open-Source-MCP-Server + Agent-Fähigkeiten, die immer aktuelle offizielle Zig-Dokumentation für die neueste Version, ein kuratiertes Hochleistungs-Leichtgewicht-Software-Leitfaden-Korpus und ein sicheres, Dry-Run-zuerst-Auto-Update für eine veraltete lokale Zig-Toolchain bereitstellen.

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 verändert sich schnell, und Antworten aus dem Trainingsspeicher werden zwischen Minor-Releases veraltet – 0.16 ersetzte die gesamte I/O-Schicht und verschob Dir von std.fs zu std.Io. Dieser Server ruft offizielle Dokumente und veröffentlichte Std-Quellen pro Aufruf ab (mit Kurz-TTL-Revalidierung), sodass jede Antwort die Version zitiert, aus der sie stammt. Wenn Ihr lokaler Compiler hinter den Dokumenten zurückbleibt, sagt der Server das und bietet ein abgesichertes Upgrade an. Er verändert Ihr System nie ohne ausdrückliche Bestätigung.

Inhaltsverzeichnis

1. Warum

2. Wie es aktuell bleibt

3. Anforderungen

4. Server installieren

5. MCP-Client verbinden

6. Prime-Agent-Integration

7. MCP-Tool-Referenz

8. Toolchain-Auto-Update

9. Leitfaden-Korpus

10. Konfiguration

11. Entwicklung

12. Fehlerbehebung

13. Lizenz

Warum

• Dokumente verrotten schnell. Die Layout der Zig-Stdlib verschiebt sich zwischen Minor Releases. Die echten Quellen der aktuellen Version auszuliefern ist die einzige ehrliche Quelle der API-Wahrheit. zig_std löst Symbole auf, indem es tatsächliche Re-Exports im veröffentlichten Baum durchläuft – keine gescrapte Momentaufnahme.

• Performance-Ratschläge sollten mechanisch sein. Das gebündelte Korpus erklärt Allokationsstrategie, Datenlayout, Comptime, Binary-Größe, Startlatenz, SIMD, Nebenläufigkeit und Benchmarking – fundiert darin, wie Hardware und Laufzeit tatsächlich funktionieren (Cache-Lines, Syscalls, Page Faults), nicht nach Bauchgefühl.

• Ein zurückgebliebener Compiler macht still alles ungültig. zig_version_status vergleicht Ihre Toolchain bei jedem Check mit dem Upstream-Index, und zig_update bietet einen konkreten, überprüfbaren Upgrade-Plan.

• Alles ist lokal-zuerst. Der Server läuft auf Ihrem Rechner über stdio. Keine Konten, keine Tokens, keine Telemetrie. Netzwerk geht nur zu ziglang.org für Dokumente, Release-Notizen und Quell-Tarballs.

Wie es aktuell bleibt

• Zwischengespeicherte Antworten revalidieren gegen ziglang.org, wenn sie älter als 6 Stunden sind (force=true revalidiert sofort). Revalidierung verwendet bedingte GETs (ETag / Last-Modified), ist also günstig.

• Offline-sicher: Wenn das Netzwerk ausfällt, werden zwischengespeicherte Inhalte mit einem stale-Flag ausgeliefert, statt zu scheitern. (Der erste Lauf braucht einmal Netzwerk.)

• Std-Quellen stammen aus dem offiziellen src-Tarball pro Release – dem kanonischen Inhalt, selbst wenn GitHub-Release-Tags nachhinken (0.16.0 war auf GitHub nicht getaggt, als dies gebaut wurde). Der Tarball wird einmal pro Version heruntergeladen und nur lib/std/** wird extrahiert.

• Der Parameter channel wählt stable (aktuelles Release, Standard) oder master (nächtlich), sodass Sie Änderungen des nächsten Releases Vorschau ansehen können.

Cache-Layout (~/.cache/zig-docs-mcp/, überschreibbar mit 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)

Voraussetzungen

• Python ≥ 3.10 und uv

• macOS oder Linux (Auto-Update unterstützt Homebrew und eigenständige Installationen; Windows bekommt einen funktionierenden Plan-Ausdruck, aber noch keine Tarball-Strategie)

• Netzwerkzugriff auf ziglang.org für erste Abrufe und Revalidierung

Server installieren

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

Lieber nicht installieren? Führen Sie ihn direkt aus dem Klon aus:

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

MCP-Client verbinden

Jeder MCP-Client, der stdio spricht. Zeigen Sie ihn auf den zigdocs-Befehl:

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

Ohne globale Installation verwenden Sie den Klon direkt:

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

Prime-Agent-Integration

Zwei Fähigkeiten sind in diesem Repository enthalten. Verlinken Sie sie und starten Sie die Sitzung neu (oder führen Sie /reload aus):

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

Dann, aus dem Agent-Kernel:

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

Aufrufe geben ihr Ergebnis als JSON-String zurück (Vollthemen-Leitfaden-Lesevorgänge geben rohes Markdown zurück); parsen Sie mit json.loads(...), wenn Sie Felder wie version oder docs benötigen. Argumente sind nur-Schlüsselwort. Der Serverbefehl wird in dieser Reihenfolge aufgelöst: ZIG_DOCS_MCP_CMD, ein zigdocs auf dem PATH, dann uv run --project gegen ZIG_DOCS_MCP_REPO (Standard ~/zig-docs-mcp).

skills/zig-docs/SKILL.md enthält die Betriebsregeln, denen der Agent folgt: zuerst Version prüfen, Dokumente vor Code, die Dokumentversion zitieren und niemals ein Update ohne ausdrückliche Zustimmung des Benutzers anwenden.

MCP-Tool-Referenz

zig_version_status

Vergleicht das lokale zig version mit dem neuesten Upstream-Release.

{
 "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
}

Wenn die lokale Toolchain älter ist, fügt die Antwort behind und einen suggestion hinzu, der auf zig_update verweist (illustratives Beispiel):

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

Aktualisiert die lokale Toolchain. Dry-Run ist die Standardeinstellung – er gibt den genauen Plan aus und ändert nichts. Anwenden erfordert dry_run=false, confirm=true. Siehe Toolchain-Auto-Update.

zig_langref

Offizielle Sprachreferenz, frisch für die Kanalversion abgerufen.

• section="Errors" → vollständiger Abschnittstext (Codeblöcke erhalten):

### 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" → nach Rangfolge sortierte Abschnittstreffer:

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

• keine Argumente → die Liste aller Abschnitts-IDs.

zig_std

Stdlib-Dokumentation aus der exakten veröffentlichten Quelle. Symbolauflösung läuft durch echte Re-Exports (std.zig → heap.zig → heap/ArenaAllocator.zig), folgt @import-Aliasen und gibt die ///-Dokumente plus den Deklarationstext aus dieser Version zurück:

{
 "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. ..."
}

Wenn ein Name keine einfache Top-Level-Deklaration im durchlaufenen Namespace ist (Layouts verschieben sich zwischen Releases), fällt das Tool auf eine korpusweite Suche nach Top-Level-Deklarationen zurück, beste Übereinstimmung zuerst – z. B. std.fs.Dir auf 0.16 zeigt korrekt lib/std/Io/Dir.zig. query="arena" durchsucht Std-Doc-Kommentare direkt.

zig_changelog

Release-Notizen-Digest für die aktuelle Kanalversion: Abschnittstitel plus eine kurze Zusammenfassung jeweils. Nützlich direkt nach einem Release (zig_changelog(force=true)).

perf_guidance

Kuratierte Hinweise für Hochleistungs-Leichtgewicht-Software. Keine Argumente listet Themen auf; topic="allocation-strategy" gibt den vollständigen Leitfaden zurück (rohes Markdown mit Prinzip / Mechanik / Zig-Idiom / Anti-Muster / Faustregeln); query=... durchsucht alle Leitfäden.

zig_search

Einheitliche Suche über Langref, Std-Doc-Kommentare und Leitfäden:

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

scope grenzt ein: all (Standard) | langref | std | guidance.

Toolchain-Auto-Update

zig_update wählt automatisch eine Strategie:

1. Homebrew-verwaltetes Zig (Binary löst innerhalb des Brew-Präfixes auf) → 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. Eigenständige Installation (offizieller Tarball, jeder andere Ort) → lädt den Plattform-Tarball aus dem Upstream-Index herunter, extrahiert nach ~/.local/opt/zig-<version> und legt einen Shim ~/.local/bin/zig an:

{
 "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"
}

Wenn ~/.local/bin nicht zuerst auf dem PATH steht, sagt der Plan das ausdrücklich – der alte Compiler würde sonst gewinnen, und das Tool sagt Ihnen, wie Sie die Reihenfolge korrigieren.

Sicherheitsregeln:

• Standard ist ein Dry-Run. Nichts wird heruntergeladen, verschoben oder verlinkt.

• Anwenden erfordert dry_run=false, confirm=true zusammen.

• Agenten, die diesen Server verwenden, werden angewiesen, den Plan zu zeigen und die ausdrückliche Zustimmung des Benutzers einzuholen, bevor sie bestätigen.

Leitfaden-Korpus

Zwölf Themen in guidance/, im Rad ausgeliefert und von perf_guidance bedient. Prinzipien sind universell; Snippets sind Zig-0.16-Ära; exakte API-Wahrheit kommt immer von zig_std, nie aus dem Korpus.

Konfiguration

Entwicklung

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

Die E2E-Suite braucht beim ersten Lauf Netzwerk (sie wärmt den Cache auf). Unit-Tests, die Symbolauflösung üben, laufen gegen den warmen Std-Quellen-Cache und werden sauber übersprungen, wenn er fehlt.

Fehlerbehebung

• zigdocs server not found (Prime-Agent-Fähigkeit): installieren Sie mit uv tool install . aus dem Klon, oder setzen Sie ZIG_DOCS_MCP_REPO auf den Klonpfad, oder setzen Sie ZIG_DOCS_MCP_CMD auf eine vollständige Befehlszeile.

• Erster Lauf schlägt offline fehl: Der Cache startet leer; holen Sie einmal online ab. Danach hält der Stale-Cache-Fallback jedes Tool am Laufen.

• Ergebnisse wirken nach einem neuen Release veraltet: übergeben Sie force=true (sonst gilt die 6-Stunden-TTL).

• zig version ist nach einem Update immer noch alt: eine neue Shell ist nötig, und ~/.local/bin muss vor dem vorherigen Installationsverzeichnis auf dem PATH stehen. Der Dry-Run-Plan nennt die genaue Situation für Ihren Rechner.

• Homebrew-Zig hinkt dem neuesten Release hinterher: Brew-Formeln hinken Releases hinterher; verwenden Sie die eigenständige Strategie (Brew-Formel entfernen, eigenständig installieren), wenn Sie Tag-eins-Versionen brauchen.

Lizenz

MIT – siehe LICENSE.