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はI/Oレイヤー全体を置き換え、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のstdライブラリ構成はマイナーリリース間で変わります。最新リリースの実際のソースを提供することだけが、APIの真実の唯一の情報源です。zig_std は、リリース済みツリー内の実際の再エクスポートを辿ってシンボルを解決します。スクレイピングしたスナップショットではありません。

• パフォーマンスの助言は機械的であるべきです。 同梱のコーパスは、アロケーション戦略、データレイアウト、comptime、バイナリサイズ、起動レイテンシ、SIMD、並行性、ベンチマークについて、感覚ではなくハードウェアとランタイムが実際にどう動作するか（キャッシュライン、システムコール、ページフォールト）に基づいて説明します。

• 古いコンパイラは静かにすべてを無効化します。 zig_version_status はチェックのたびにツールチェーンをアップストリームのインデックスと比較し、zig_update は具体的でレビュー可能なアップグレード計画を提示します。

• すべてがローカルファーストです。 サーバーはstdioでお使いのマシン上で実行されます。アカウントもトークンもテレメトリもありません。ネットワークは、ドキュメント、リリースノート、ソースtarballを取得するためだけにziglang.orgへ接続します。

鮮度を保つ仕組み

• キャッシュされたレスポンスは、6時間より古くなると ziglang.org に対して再検証 されます（force=true で即時再検証）。再検証は条件付きGET（ETag / Last-Modified）を使うため、コストは低いです。

• オフライン対応：ネットワークがダウンしている場合、失敗する代わりにキャッシュされたコンテンツが stale フラグ付きで提供されます。（初回実行時だけネットワークが一度必要です。）

• stdソースは 公式のリリース別 src tarball から取得します。これは、GitHubのリリースタグが遅れている場合でも正規の内容です（これを構築した時点では0.16.0はGitHubにタグがありませんでした）。tarballはバージョンごとに一度だけダウンロードされ、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は動作する計画の出力のみで、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

MCPクライアントの接続

stdioに対応した任意のMCPクライアント。zigdocs コマンドを指定してください：

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

グローバルインストールなしで、クローンを直接使用する場合：

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

Prime Agent統合

このリポジトリには2つのスキルが同梱されています。シンボリックリンクを作成してセッションを再起動（または /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を返します）。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 には、エージェントが従う運用ルールが含まれています：まずバージョン確認、コードよりドキュメント、ドキュメントのバージョンを引用、そしてユーザーの明示的な承諾なしにアップデートを適用しない。

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

公式言語リファレンス。チャネルバージョン用に毎回取得します。

• 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" はstdのドキュメントコメントを直接検索します。

zig_changelog

現在のチャネルバージョンのリリースノートダイジェスト：各セクションのタイトルと短い要約。リリース直後に便利です（zig_changelog(force=true)）。

perf_guidance

高性能・軽量ソフトウェアのための厳選されたガイダンス。引数なしでトピックを一覧表示し、topic="allocation-strategy" で完全なガイドを返します（原則 / 仕組み / Zigのイディオム / アンチパターン / 経験則 を含む生のMarkdown）。query=... はすべてのガイドを横断検索します。

zig_search

langref、stdのドキュメントコメント、ガイダンスにわたる統合検索：

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

scope で絞り込めます：all（デフォルト）| langref | std | guidance。

ツールチェーンの自動アップデート

zig_update は戦略を自動的に選択します：

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

2. スタンドアロンインストール（公式tarball、その他の場所）→ アップストリームのインデックスからプラットフォーム用tarballをダウンロードし、~/.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/ にある12のトピック。wheel内に同梱され、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 を渡してください（そうしないと6時間のTTLが適用されます）。

• アップデート後も zig version が古いまま：新しいシェルが必要です。また、~/.local/bin がPATH内で以前のインストールディレクトリより前にある必要があります。ドライラン計画には、お使いのマシンの正確な状況が記載されています。

• Homebrewのzigが最新リリースに追いつかない：brewのformulaはリリースに遅れます。リリース当日のバージョンが必要な場合は、スタンドアロン戦略を使用してください（brewのformulaを削除し、スタンドアロンをインストール）。

ライセンス

MIT — LICENSE を参照してください。