Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ryo-zen/zig-docs-mcp

MCP server providing comprehensive access to Zig 0.16 language documentation, standard library references, and working code examples.
https://github.com/ryo-zen/zig-docs-mcp

Last synced: 8 days ago
JSON representation

MCP server providing comprehensive access to Zig 0.16 language documentation, standard library references, and working code examples.

Awesome Lists containing this project

README 

          
# Zig Documentation MCP Server



MCP server providing comprehensive access to Zig 0.16.0 language documentation, standard library references, and working code examples.



**Target Zig Version:** `0.16.0` (locked by `zig-version-contract.json`)



## Quick Start



### Prerequisites

- Node.js 18.x or later

- npm (comes with Node.js)



### Setup & Build



```bash

# Install dependencies

npm install



# Build the TypeScript source

npm run build



# Start the server

npm start

```



The server compiles from TypeScript (`src/index.ts`) to JavaScript (`build/index.js`).



### Running Tests



```bash

# Run all tests

npm test



# Run tests in watch mode

npm run test:watch



# Run tests with UI

npm run test:ui



# Generate coverage report

npm run test:coverage

```



### Auditing Stdlib Docs



```bash

# Audit all std namespace/type docs against the locked local Zig stdlib source

npm run audit:stdlib-docs



# Audit one doc or directory while fixing stale coverage

npm run audit:stdlib-docs -- --path zig_docs_std/Namespaces/process/std.process.ArgExpansion.md --include-ok

```



## MCP Integration



### Claude Code (CLI)



```bash

# Build first

npm run build



# Add server (user scope)

claude mcp add -s user zig-docs -- bash -lc "cd /absolute/path/to/zig-docs-mcp && node build/index.js"



# Verify

claude mcp list

```



Optional config-file form (`.mcp.json` in your project root):



```json

{

  "mcpServers": {

    "zig-docs": {

      "type": "stdio",

      "command": "bash",

      "args": ["-lc", "cd /absolute/path/to/zig-docs-mcp && node build/index.js"],

      "env": {}

    }

  }

}

```



Optional CLI import of the same JSON entry:



```bash

claude mcp add-json -s user zig-docs '{"type":"stdio","command":"bash","args":["-lc","cd /absolute/path/to/zig-docs-mcp && node build/index.js"],"env":{}}'

```



Scope options:

- `-s user` = global config for your user account.

- `-s project` or `-s local` = repo-scoped config.

- `.mcp.json` = file-based repo-scoped config.



**Important:**

- Replace `/absolute/path/to/zig-docs-mcp` with the actual absolute path

- Ensure you've run `npm run build` before starting the server



### Codex CLI



```bash

# Build first

npm run build



# Add server

codex mcp add zig-docs -- bash -lc "cd /absolute/path/to/zig-docs-mcp && node build/index.js"



# Verify

codex mcp list

```



Optional config-file form (`~/.codex/config.toml`):



```toml

[mcp_servers.zig-docs]

command = "bash"

args = ["-lc", "cd /absolute/path/to/zig-docs-mcp && node build/index.js"]

```



Scope notes:

- `codex mcp add` persists server config in `~/.codex/config.toml` (user/global).

- Codex CLI does not currently expose a dedicated `--scope` flag for MCP server add.



### Gemini CLI



```bash

# Build first

npm run build



# Add server (user scope, stdio transport)

gemini mcp add --scope user --transport stdio zig-docs bash -lc "cd /absolute/path/to/zig-docs-mcp && node build/index.js"



# Verify

gemini mcp list

```



Optional config-file form (`~/.gemini/settings.json`):



```json

{

  "mcp": {

    "allowed": ["zig-docs"]

  },

  "mcpServers": {

    "zig-docs": {

      "command": "bash",

      "args": ["-lc", "cd /absolute/path/to/zig-docs-mcp && node build/index.js"]

    }

  }

}

```



Scope notes:

- `--scope user` stores config in your user settings (for this machine/user).

- `--scope project` stores config in project scope managed by Gemini CLI.



### OpenCode CLI



```bash

# Build first

npm run build



# Verify

opencode mcp list

```



Preferred setup: add MCP in OpenCode config (`~/.config/opencode/opencode.json` or `~/.config/opencode/opencode.jsonc`):



```json

{

  "$schema": "https://opencode.ai/config.json",

  "mcp": {

    "zig-docs": {

      "type": "local",

      "command": ["bash", "-lc", "cd /absolute/path/to/zig-docs-mcp && node build/index.js"],

      "enabled": true

    }

  }

}

```



Optional environment variables:



```json

{

  "$schema": "https://opencode.ai/config.json",

  "mcp": {

    "zig-docs": {

      "type": "local",

      "command": ["bash", "-lc", "cd /absolute/path/to/zig-docs-mcp && node build/index.js"],

      "environment": {

        "NODE_ENV": "production"

      }

    }

  }

}

```



OpenCode notes:

- OpenCode loads global config from `~/.config/opencode/config.json`, `~/.config/opencode/opencode.json`, and `~/.config/opencode/opencode.jsonc`.

- MCP server config uses `mcp.` with `type: "local"` or `type: "remote"`.

- If you see `MCP error -32000: Connection closed`, verify `command` is a proper argv array (not a broken quoted string split into bad tokens).



### Notes



- Transport for this server is **stdio**.

- The server must run from the repository root because docs are resolved via `process.cwd()`.

- If you pull new changes, run `npm run build` again before reconnecting.



## Features



### Resources

The server exposes four types of resources:

- **Language Documentation** (`zig://doc/*`) - Zig language features, syntax, and concepts

- **Standard Library** (`zig://std/*`) - Type and namespace documentation

- **Working Examples** (`zig://examples/*`) - Runnable Zig code examples

- **Coding Patterns** (`zig://patterns/*`) - Practical Zig coding patterns organized by category



### Tools

- `search_zig_docs` - Search across all documentation with smart scoring and fuzzy matching

- `get_builtin_info` - Get details about builtin functions (e.g., `@import`, `@sizeof`) with suggestions

- `explain_concept` - Get explanations of Zig concepts (comptime, defer, optionals, etc.)

- `get_syntax_examples` - Get code examples for language constructs

- `get_example` - Retrieve working code examples by topic

- `server_diagnostics` - Get server health, cache stats, and diagnostic information

- `introspect_type` - Introspect a Zig type to see its methods, fields, and structure

- `validate_code` - Validate a Zig code snippet and get compilation errors if any

- `query_stdlib_source` - Query the Zig standard library source code for a specific file/module



## Documentation Structure



- `zig_docs/` - Language documentation (syntax, features, concepts)

- `zig_docs_std/` - Standard library documentation

  - `Types/` - Type documentation (ArrayList, ArrayHashMap, etc.)

  - `Examples/` - Working Zig code examples (167 examples)

- `zig_patterns/` - Coding patterns organized by category

  - `memory/` - Memory management patterns

  - `errors/` - Error handling patterns

  - `iterators/` - Iterator patterns

  - `comptime/` - Compile-time patterns

  - `io/` - I/O patterns

  - `testing/` - Testing patterns

- `templates/` - Documentation templates



## What's Included



- **75 Language Documentation Files** - Covering Zig language features and migration notes

- **386 Standard Library Docs** - Type and namespace documentation

- **167 Working Code Examples** - Runnable Zig code demonstrating patterns and APIs

- **14 Coding Patterns** - Practical patterns organized by category

- **642 Total Cached Resources** - Loaded into memory at startup



## Working Examples



The server includes 167 working Zig examples covering:

- Data structures (ArrayList, ArrayHashMap)

- I/O operations (Reader, Writer, std.Io)

- JSON parsing and serialization

- Async/await patterns

- File operations

- Network programming

- And more



Access examples via:

- Resources: `zig://examples/arraylist`, `zig://examples/reader`, etc.

- Tool: `get_example("arraylist")`



## Coding Patterns



The server includes 14 practical coding patterns organized by category:

- **Memory Management** - Arena allocators, defer cleanup, errdefer rollback

- **Error Handling** - Custom error sets, try propagation

- **Iterators** - Split parsing, window iteration

- **Compile-time** - Compile-time validation, generic functions

- **I/O** - Buffered I/O patterns

- **Testing** - Allocator testing patterns



Access patterns via:

- Resources: `zig://patterns/memory/arena_allocator`, etc.

- Search: `search_zig_docs("arena allocator")`



## Documentation



- **CLAUDE.md** - Comprehensive guide for development and contributing

- **IMPROVEMENTS.md** - Detailed improvement plan and roadmap

- Run `server_diagnostics` tool for real-time server statistics



## Testing



All code is tested with a comprehensive test suite:

- 49 automated tests covering core functionality

- URI parsing and file path resolution

- Search algorithm and scoring

- Error handling and suggestions

- Cache behavior and performance



Run `npm test` to verify everything works.