{"id":49176554,"url":"https://github.com/ryo-zen/zig-docs-mcp","last_synced_at":"2026-06-09T12:30:57.071Z","repository":{"id":356658734,"uuid":"1145098275","full_name":"ryo-zen/zig-docs-mcp","owner":"ryo-zen","description":"MCP server providing comprehensive access to Zig 0.16 language documentation, standard library references, and working code examples.","archived":false,"fork":false,"pushed_at":"2026-05-24T04:31:52.000Z","size":1285,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T06:33:40.011Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ryo-zen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-29T12:25:54.000Z","updated_at":"2026-05-24T04:31:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ryo-zen/zig-docs-mcp","commit_stats":null,"previous_names":["ryo-zen/zig-docs-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ryo-zen/zig-docs-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-zen%2Fzig-docs-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-zen%2Fzig-docs-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-zen%2Fzig-docs-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-zen%2Fzig-docs-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryo-zen","download_url":"https://codeload.github.com/ryo-zen/zig-docs-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-zen%2Fzig-docs-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34107865,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-22T23:00:22.081Z","updated_at":"2026-06-09T12:30:57.066Z","avatar_url":"https://github.com/ryo-zen.png","language":"Zig","funding_links":[],"categories":["Development Tools","Fundamentals"],"sub_categories":["Documentation and Testing"],"readme":"# Zig Documentation MCP Server\n\nMCP server providing comprehensive access to Zig 0.16.0 language documentation, standard library references, and working code examples.\n\n**Target Zig Version:** `0.16.0` (locked by `zig-version-contract.json`)\n\n## Quick Start\n\n### Prerequisites\n- Node.js 18.x or later\n- npm (comes with Node.js)\n\n### Setup \u0026 Build\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the TypeScript source\nnpm run build\n\n# Start the server\nnpm start\n```\n\nThe server compiles from TypeScript (`src/index.ts`) to JavaScript (`build/index.js`).\n\n### Running Tests\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Run tests with UI\nnpm run test:ui\n\n# Generate coverage report\nnpm run test:coverage\n```\n\n### Auditing Stdlib Docs\n\n```bash\n# Audit all std namespace/type docs against the locked local Zig stdlib source\nnpm run audit:stdlib-docs\n\n# Audit one doc or directory while fixing stale coverage\nnpm run audit:stdlib-docs -- --path zig_docs_std/Namespaces/process/std.process.ArgExpansion.md --include-ok\n```\n\n## MCP Integration\n\n### Claude Code (CLI)\n\n```bash\n# Build first\nnpm run build\n\n# Add server (user scope)\nclaude mcp add -s user zig-docs -- bash -lc \"cd /absolute/path/to/zig-docs-mcp \u0026\u0026 node build/index.js\"\n\n# Verify\nclaude mcp list\n```\n\nOptional config-file form (`.mcp.json` in your project root):\n\n```json\n{\n  \"mcpServers\": {\n    \"zig-docs\": {\n      \"type\": \"stdio\",\n      \"command\": \"bash\",\n      \"args\": [\"-lc\", \"cd /absolute/path/to/zig-docs-mcp \u0026\u0026 node build/index.js\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\nOptional CLI import of the same JSON entry:\n\n```bash\nclaude mcp add-json -s user zig-docs '{\"type\":\"stdio\",\"command\":\"bash\",\"args\":[\"-lc\",\"cd /absolute/path/to/zig-docs-mcp \u0026\u0026 node build/index.js\"],\"env\":{}}'\n```\n\nScope options:\n- `-s user` = global config for your user account.\n- `-s project` or `-s local` = repo-scoped config.\n- `.mcp.json` = file-based repo-scoped config.\n\n**Important:**\n- Replace `/absolute/path/to/zig-docs-mcp` with the actual absolute path\n- Ensure you've run `npm run build` before starting the server\n\n### Codex CLI\n\n```bash\n# Build first\nnpm run build\n\n# Add server\ncodex mcp add zig-docs -- bash -lc \"cd /absolute/path/to/zig-docs-mcp \u0026\u0026 node build/index.js\"\n\n# Verify\ncodex mcp list\n```\n\nOptional config-file form (`~/.codex/config.toml`):\n\n```toml\n[mcp_servers.zig-docs]\ncommand = \"bash\"\nargs = [\"-lc\", \"cd /absolute/path/to/zig-docs-mcp \u0026\u0026 node build/index.js\"]\n```\n\nScope notes:\n- `codex mcp add` persists server config in `~/.codex/config.toml` (user/global).\n- Codex CLI does not currently expose a dedicated `--scope` flag for MCP server add.\n\n### Gemini CLI\n\n```bash\n# Build first\nnpm run build\n\n# Add server (user scope, stdio transport)\ngemini mcp add --scope user --transport stdio zig-docs bash -lc \"cd /absolute/path/to/zig-docs-mcp \u0026\u0026 node build/index.js\"\n\n# Verify\ngemini mcp list\n```\n\nOptional config-file form (`~/.gemini/settings.json`):\n\n```json\n{\n  \"mcp\": {\n    \"allowed\": [\"zig-docs\"]\n  },\n  \"mcpServers\": {\n    \"zig-docs\": {\n      \"command\": \"bash\",\n      \"args\": [\"-lc\", \"cd /absolute/path/to/zig-docs-mcp \u0026\u0026 node build/index.js\"]\n    }\n  }\n}\n```\n\nScope notes:\n- `--scope user` stores config in your user settings (for this machine/user).\n- `--scope project` stores config in project scope managed by Gemini CLI.\n\n### OpenCode CLI\n\n```bash\n# Build first\nnpm run build\n\n# Verify\nopencode mcp list\n```\n\nPreferred setup: add MCP in OpenCode config (`~/.config/opencode/opencode.json` or `~/.config/opencode/opencode.jsonc`):\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"zig-docs\": {\n      \"type\": \"local\",\n      \"command\": [\"bash\", \"-lc\", \"cd /absolute/path/to/zig-docs-mcp \u0026\u0026 node build/index.js\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\nOptional environment variables:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"zig-docs\": {\n      \"type\": \"local\",\n      \"command\": [\"bash\", \"-lc\", \"cd /absolute/path/to/zig-docs-mcp \u0026\u0026 node build/index.js\"],\n      \"environment\": {\n        \"NODE_ENV\": \"production\"\n      }\n    }\n  }\n}\n```\n\nOpenCode notes:\n- OpenCode loads global config from `~/.config/opencode/config.json`, `~/.config/opencode/opencode.json`, and `~/.config/opencode/opencode.jsonc`.\n- MCP server config uses `mcp.\u003cname\u003e` with `type: \"local\"` or `type: \"remote\"`.\n- If you see `MCP error -32000: Connection closed`, verify `command` is a proper argv array (not a broken quoted string split into bad tokens).\n\n### Notes\n\n- Transport for this server is **stdio**.\n- The server must run from the repository root because docs are resolved via `process.cwd()`.\n- If you pull new changes, run `npm run build` again before reconnecting.\n\n## Features\n\n### Resources\nThe server exposes four types of resources:\n- **Language Documentation** (`zig://doc/*`) - Zig language features, syntax, and concepts\n- **Standard Library** (`zig://std/*`) - Type and namespace documentation\n- **Working Examples** (`zig://examples/*`) - Runnable Zig code examples\n- **Coding Patterns** (`zig://patterns/*`) - Practical Zig coding patterns organized by category\n\n### Tools\n- `search_zig_docs` - Search across all documentation with smart scoring and fuzzy matching\n- `get_builtin_info` - Get details about builtin functions (e.g., `@import`, `@sizeof`) with suggestions\n- `explain_concept` - Get explanations of Zig concepts (comptime, defer, optionals, etc.)\n- `get_syntax_examples` - Get code examples for language constructs\n- `get_example` - Retrieve working code examples by topic\n- `server_diagnostics` - Get server health, cache stats, and diagnostic information\n- `introspect_type` - Introspect a Zig type to see its methods, fields, and structure\n- `validate_code` - Validate a Zig code snippet and get compilation errors if any\n- `query_stdlib_source` - Query the Zig standard library source code for a specific file/module\n\n## Documentation Structure\n\n- `zig_docs/` - Language documentation (syntax, features, concepts)\n- `zig_docs_std/` - Standard library documentation\n  - `Types/` - Type documentation (ArrayList, ArrayHashMap, etc.)\n  - `Examples/` - Working Zig code examples (167 examples)\n- `zig_patterns/` - Coding patterns organized by category\n  - `memory/` - Memory management patterns\n  - `errors/` - Error handling patterns\n  - `iterators/` - Iterator patterns\n  - `comptime/` - Compile-time patterns\n  - `io/` - I/O patterns\n  - `testing/` - Testing patterns\n- `templates/` - Documentation templates\n\n## What's Included\n\n- **75 Language Documentation Files** - Covering Zig language features and migration notes\n- **386 Standard Library Docs** - Type and namespace documentation\n- **167 Working Code Examples** - Runnable Zig code demonstrating patterns and APIs\n- **14 Coding Patterns** - Practical patterns organized by category\n- **642 Total Cached Resources** - Loaded into memory at startup\n\n## Working Examples\n\nThe server includes 167 working Zig examples covering:\n- Data structures (ArrayList, ArrayHashMap)\n- I/O operations (Reader, Writer, std.Io)\n- JSON parsing and serialization\n- Async/await patterns\n- File operations\n- Network programming\n- And more\n\nAccess examples via:\n- Resources: `zig://examples/arraylist`, `zig://examples/reader`, etc.\n- Tool: `get_example(\"arraylist\")`\n\n## Coding Patterns\n\nThe server includes 14 practical coding patterns organized by category:\n- **Memory Management** - Arena allocators, defer cleanup, errdefer rollback\n- **Error Handling** - Custom error sets, try propagation\n- **Iterators** - Split parsing, window iteration\n- **Compile-time** - Compile-time validation, generic functions\n- **I/O** - Buffered I/O patterns\n- **Testing** - Allocator testing patterns\n\nAccess patterns via:\n- Resources: `zig://patterns/memory/arena_allocator`, etc.\n- Search: `search_zig_docs(\"arena allocator\")`\n\n## Documentation\n\n- **CLAUDE.md** - Comprehensive guide for development and contributing\n- **IMPROVEMENTS.md** - Detailed improvement plan and roadmap\n- Run `server_diagnostics` tool for real-time server statistics\n\n## Testing\n\nAll code is tested with a comprehensive test suite:\n- 49 automated tests covering core functionality\n- URI parsing and file path resolution\n- Search algorithm and scoring\n- Error handling and suggestions\n- Cache behavior and performance\n\nRun `npm test` to verify everything works.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryo-zen%2Fzig-docs-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryo-zen%2Fzig-docs-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryo-zen%2Fzig-docs-mcp/lists"}