zig-docs-mcp

Локальный MCP-сервер с открытым исходным кодом + навыки агента, которые предоставляют всегда актуальную официальную документацию Zig для последнего релиза, курируемый корпус рекомендаций по высокопроизводительному легковесному ПО и безопасное автообновление с предварительным пробным запуском для устаревшего локального инструментария Zig.

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 быстро меняется, и ответы из памяти обучения устаревают между минорными релизами — в 0.16 заменили весь слой ввода-вывода и перенесли Dir из std.fs в std.Io. Этот сервер загружает официальную документацию и исходники std при каждом вызове (с повторной проверкой по короткому TTL), поэтому каждый ответ ссылается на версию, из которой он получен. Когда ваш локальный компилятор отстаёт от документации, сервер сообщает об этом и предлагает обновление с подтверждением. Он никогда не изменяет вашу систему без явного согласия.

Содержание

1. Зачем

2. Как поддерживается актуальность

3. Требования

4. Установка сервера

5. Подключение MCP-клиента

6. Интеграция с Prime Agent

7. Справочник инструментов MCP

8. Автообновление инструментария

9. Корпус рекомендаций

10. Конфигурация

11. Разработка

12. Устранение неполадок

13. Лицензия

Зачем

• Документация быстро устаревает. Структура стандартной библиотеки Zig меняется между минорными релизами. Обслуживание реальных исходников последнего релиза — единственный честный источник истины об API. zig_std разрешает символы, обходя реальные реэкспорты в опубликованном дереве, а не по снимку.

• Советы по производительности должны быть механическими. Встроенный корпус объясняет стратегию выделения памяти, компоновку данных, comptime, размер бинарника, задержку запуска, SIMD, конкурентность и бенчмаркинг — на основе реального поведения оборудования и среды выполнения (линии кэша, системные вызовы, страничные прерывания), а не общих соображений.

• Устаревший компилятор незаметно обесценивает всё. zig_version_status сравнивает ваш инструментарий с индексом вышестоящего репозитория при каждой проверке, а zig_update предлагает конкретный, проверяемый план обновления.

• Всё локально. Сервер работает на вашей машине через stdio. Никаких учётных записей, токенов и телеметрии. Сеть используется только для ziglang.org: документация, примечания к выпускам и архивы исходников.

Как поддерживается актуальность

• Кэшированные ответы повторно проверяются на ziglang.org, если они старше 6 часов (force=true выполняет проверку немедленно). Повторная проверка использует условные GET-запросы (ETag / Last-Modified), поэтому она дёшева.

• Работа в офлайне: если сеть недоступна, кэшированное содержимое отдаётся с флагом stale вместо ошибки. (Первый запуск требует сети один раз.)

• Исходники std берутся из официального архива src для каждого релиза — каноническое содержимое, даже если теги релизов на GitHub отстают (0.16.0 не был отмечен на GitHub на момент создания). Архив загружается один раз для каждой версии, извлекается только lib/std/**.

• Параметр channel выбирает stable (последний релиз, по умолчанию) или master (ночная сборка), что позволяет просматривать изменения следующего релиза.

Структура кэша (~/.cache/zig-docs-mcp/, переопределяется через 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)

Требования

• Python ≥ 3.10 и uv

• macOS или Linux (автообновление поддерживает Homebrew и автономные установки; для Windows выводится рабочий план, но стратегии для архивов пока нет)

• Доступ к ziglang.org для первых загрузок и повторных проверок

Установка сервера

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

Не хотите устанавливать? Запустите прямо из клона:

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

Подключение MCP-клиента

Любой MCP-клиент, поддерживающий stdio. Укажите команду zigdocs:

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

Без глобальной установки используйте клон напрямую:

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

Интеграция с Prime Agent

В этом репозитории два навыка. Создайте символические ссылки и перезапустите сеанс (или выполните /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

Затем из ядра агента:

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

Вызовы возвращают результат в виде JSON-строки (полные руководства возвращают необработанный Markdown); используйте json.loads(...), когда нужны такие поля, как version или docs. Аргументы — только ключевые. Команда сервера разрешается в порядке: ZIG_DOCS_MCP_CMD, zigdocs из PATH, затем uv run --project для ZIG_DOCS_MCP_REPO (по умолчанию ~/zig-docs-mcp).

skills/zig-docs/SKILL.md содержит правила, которым следует агент: сначала проверка версии, документация перед кодом, указание версии документации и никаких обновлений без явного согласия пользователя.

Справочник инструментов MCP

zig_version_status

Сравнивает локальную zig version с последним вышестоящим релизом.

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

Если локальный инструментарий устарел, ответ добавляет behind и suggestion, указывающий на zig_update (иллюстративный пример):

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

Обновляет локальный инструментарий. По умолчанию — пробный запуск: выводится точный план, ничего не меняется. Для применения требуются dry_run=false, confirm=true. См. Автообновление инструментария.

zig_langref

Официальное языковое руководство, загружается свежим для версии канала.

• section="Errors" → полный текст раздела (с сохранением блоков кода):

### 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" → ранжированные совпадения по разделам:

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

• без аргументов → список всех идентификаторов разделов.

zig_std

Документация стандартной библиотеки из точного исходного кода релиза. Разрешение символов обходит реальные реэкспорты (std.zig → heap.zig → heap/ArenaAllocator.zig), следует псевдонимам @import и возвращает документацию /// и текст объявления из этого релиза:

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

Если имя не является простым объявлением верхнего уровня в обойдённом пространстве имён (компоновка меняется между релизами), инструмент переключается на поиск по всему корпусу объявлений верхнего уровня, сначала лучшие совпадения — например, std.fs.Dir в 0.16 корректно находит lib/std/Io/Dir.zig. query="arena" ищет непосредственно в комментариях документации std.

zig_changelog

Сводка примечаний к выпуску для текущей версии канала: заголовки разделов и краткое описание каждого. Полезно сразу после выхода релиза (zig_changelog(force=true)).

perf_guidance

Курируемые рекомендации по высокопроизводительному лёгкому ПО. Без аргументов выводит список тем; topic="allocation-strategy" возвращает полное руководство (необработанный Markdown с разделами «Принцип / Механика / Идиомы Zig / Антипаттерны / Эмпирические правила»); query=... ищет по всем руководствам.

zig_search

Единый поиск по языковому руководству, комментариям документации std и рекомендациям:

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

scope сужает область: all (по умолчанию) | langref | std | guidance.

Автообновление инструментария

zig_update выбирает стратегию автоматически:

1. zig под управлением Homebrew (бинарник находится в префиксе 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. Автономная установка (официальный архив, любое другое расположение) → загружает архив для платформы из индекса вышестоящего репозитория, распаковывает в ~/.local/opt/zig-<version> и создаёт симлинк ~/.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"
}

Если ~/.local/bin не первым в PATH, план явно сообщает об этом — иначе старый компилятор будет иметь приоритет, и инструмент подскажет, как исправить порядок.

Правила безопасности:

• По умолчанию — пробный запуск. Ничего не загружается, не перемещается и не связывается.

• Для применения требуются dry_run=false, confirm=true вместе.

• Агентам, использующим этот сервер, предписано показывать план и получать явное согласие пользователя перед подтверждением.

Корпус рекомендаций

Двенадцать тем в guidance/, поставляются в составе пакета и обслуживаются через perf_guidance. Принципы универсальны; фрагменты относятся к эпохе Zig 0.16; точная истина API всегда берётся из zig_std, а не из корпуса.

Конфигурация

Разработка

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

Для e2e-тестов при первом запуске требуется сеть (прогрев кэша). Модульные тесты, проверяющие разрешение символов, работают с тёплым кэшем исходников std и корректно пропускаются при его отсутствии.

Устранение неполадок

• zigdocs server not found (навык Prime Agent): установите с помощью uv tool install . из клона или задайте ZIG_DOCS_MCP_REPO как путь к клону, или ZIG_DOCS_MCP_CMD как полную командную строку.

• Первый запуск не работает в офлайне: кэш изначально пуст; один раз загрузитесь в сети. После этого запасной вариант с устаревшим кэшем обеспечивает работу всех инструментов.

• Результаты выглядят устаревшими после нового релиза: передайте force=true (иначе действует TTL 6 часов).

• zig version по-прежнему старая после обновления: нужна новая оболочка, и ~/.local/bin должен предшествовать предыдущему каталогу установки в PATH. План пробного запуска точно укажет ситуацию для вашей машины.

• Homebrew zig отстаёт от новейшего релиза: формулы brew отстают от релизов; используйте автономную стратегию (удалите формулу brew, установите автономно), если нужны версии в день выхода.

Лицензия

MIT — см. LICENSE.