本地、开源的 MCP 服务器 + agent 技能，为最新发布提供始终新鲜的官方 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 替换了整个 I/O 层，并将 Dir 从 std.fs 移到了 std.Io。此服务器每次调用都会获取官方文档和已发布的标准库源码（带短 TTL 重新验证），因此每个答案都引用其来源的版本。当你的本地编译器落后于文档时，服务器会明确说明，并提供受控升级。未经明确确认，它绝不会修改你的系统。
Related MCP server: Zignet
文档腐化得快。 Zig 的标准库布局在次要版本之间就会变动。提供最新发布的真实源码是 API 真相的唯一可靠来源。zig_std 通过遍历发布树中实际的再导出（re-export）来解析符号，而不是抓取的快照。
性能建议应该是机械性的。 随附的语料库解释了分配策略、数据布局、comptime、二进制大小、启动延迟、SIMD、并发和基准测试——基于硬件和运行时实际行为（缓存行、系统调用、缺页），而非感觉。
落后的编译器会悄悄使一切失效。 zig_version_status 每次检查时将你的工具链与上游索引进行比较，zig_update 则提供具体、可审查的升级计划。
一切以本地优先。 服务器通过 stdio 在你的机器上运行。没有账户、没有令牌、没有遥测。网络只流向 ziglang.org 以获取文档、发布说明和源码 tarball。
缓存的响应在超过 6 小时时会对 ziglang.org 重新验证（force=true 立即重新验证）。重新验证使用条件 GET 请求（ETag / Last-Modified），因此成本很低。
离线安全：如果网络不可用，缓存内容会以 stale 标志提供，而不是失败。（首次运行需要一次网络。）
标准库源码来自官方按版本发布的 src tarball——即使 GitHub 发布标签滞后，这也是权威内容（构建此工具时 0.16.0 在 GitHub 上尚未打标签）。tarball 每个版本只下载一次，且只解压 lib/std/**。
channel 参数选择 stable（最新发布，默认）或 master（nightly），以便预览下一版本变更。
缓存布局（~/.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 会得到可用的计划输出，但尚无 tarball 策略）
需要网络访问 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任何支持 stdio 的 MCP 客户端。将其指向 zigdocs 命令：
{
"mcpServers": {
"zig-docs": {
"command": "zigdocs"
}
}
}如果没有全局安装，直接使用克隆：
{
"mcpServers": {
"zig-docs": {
"command": "uv",
"args": ["run", "--project", "/path/to/zig-docs-mcp", "zigdocs"]
}
}
}本仓库附带两个技能。将它们符号链接并重启会话（或运行 /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然后，从 agent 内核：
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）；当需要 version 或 docs 等字段时，用 json.loads(...) 解析。参数仅限关键字。服务器命令按顺序解析：ZIG_DOCS_MCP_CMD、PATH 上的 zigdocs，然后是对 ZIG_DOCS_MCP_REPO（默认 ~/zig-docs-mcp）执行 uv run --project。
skills/zig-docs/SKILL.md 包含 agent 遵循的操作规则：先进行版本门控，先文档后代码，引用文档版本，未经用户明确同意绝不应用更新。
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 和指向 zig_update 的 suggestion（示例）：
{
"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官方语言参考，为 channel 版本获取最新内容。
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§"}]无参数 → 所有章节 ID 的列表。
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. ..."
}如果名称不是遍历的命名空间中的普通顶层声明（布局在版本之间会变动），工具会回退到对整个语料库的顶层声明搜索，最佳匹配优先——例如，0.16 上的 std.fs.Dir 会正确呈现 lib/std/Io/Dir.zig。query="arena" 直接搜索标准库文档注释。
zig_changelog当前 channel 版本的发布说明摘要：每个章节的标题加简短摘要。在发布刚落地时很有用（zig_changelog(force=true)）。
perf_guidance精选的高性能轻量软件指导。无参数时列出主题；topic="allocation-strategy" 返回完整指南（原始 markdown，包含原则 / 机制 / Zig 惯用法 / 反模式 / 经验法则）；query=... 在所有指南中搜索。
zig_search跨 langref、std 文档注释和指导的统一搜索：
{"query": "vectorization", "langref": [...], "guidance": [...], "std": [...], "std_version": "0.16.0"}scope 可缩小范围：all（默认）| langref | std | guidance。
zig_update 自动选择策略：
Homebrew 管理的 zig（二进制文件解析在 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."
}独立安装（官方 tarball，任何其他位置）→ 从上游索引下载平台 tarball，解压到 ~/.local/opt/zig-<version>，并在 ~/.local/bin/zig 创建 shim：
{
"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。
使用此服务器的 agent 被要求先展示计划，并在确认前获得用户的明确同意。
guidance/ 中的十二个主题，随 wheel 一起分发，由 perf_guidance 提供。原则是通用的；代码片段是 Zig 0.16 时代的；确切的 API 事实始终来自 zig_std，而非语料库。
主题 | 一句话摘要 |
| 将分配器与生命周期匹配；arena 指针成本与通用分配器记账成本；隐藏分配。 |
| 64 字节缓存行上的 SoA 与 AoS 字节计算；热/冷数据分离； |
| comptime 结果变为 rodata/立即数；运行时表产生脏页成本。 |
| 切片是 16 字节；按 token 分配会带来一次分配、一次 memcpy 和每个 token 的缓存行成本。 |
| 大小 = 可达性；剥离、panic 模式、依赖卫生；更小的文本 = 更少的启动缺页。 |
| 无 init_array、惰性文本缺页、惰性初始化、argv 之前不做任何工作。 |
| 填充计算、字段排序、打包结构体、 |
| 自动向量化障碍、逐通道累加 + 单次归约、 |
| 共享写入的 MESI 成本、futex 停放、系统调用批处理、伪共享填充。 |
| 错误是 u16 值； |
| 发布构建、预热、最小值/中位数而非平均值、用 sink 对抗 DCE、计数器。 |
| 标准库优先；依赖增加链接代码和构建脆弱性；内置小型工具。 |
变量 | 含义 | 默认值 |
| 缓存目录 |
|
| 完整服务器命令行（skill 覆盖） | — |
|
|
|
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端到端测试套件首次运行需要网络（它会预热缓存）。涉及符号解析的单元测试针对预热的标准库源码缓存运行，当缓存不存在时会干净地跳过。
zigdocs server not found（Prime Agent 技能）：从克隆中执行 uv tool install . 安装，或将 ZIG_DOCS_MCP_REPO 设置为克隆路径，或将 ZIG_DOCS_MCP_CMD 设置为完整命令行。
首次运行在离线时失败：缓存初始为空；在线时获取一次。之后，过期缓存回退可让所有工具正常工作。
新发布后结果看起来过时：传递 force=true（否则适用 6 小时 TTL）。
更新后 zig version 仍较旧：需要新 shell，并且 ~/.local/bin 必须在 PATH 中位于之前的安装目录之前。试运行计划会说明你机器的确切情况。
Homebrew zig 落后于最新发布：brew 公式滞后于发布；如果你需要首发版本，请使用独立安装策略（移除 brew 公式，独立安装）。
MIT — 见 LICENSE。
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
DevDocs.io keyless docs index + entry search + content (Angular, MDN, Rust, etc.).
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
Scrape, crawl, map & search the web. Open-source, self-hostable Rust crawler & search for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/gbrlpzz/zig-docs-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server