# mcp-server-zig

MCP server that provides Zig language intelligence for Claude Code. Wraps [ZLS](https://github.com/zigtools/zls) (Zig Language Server) and exposes 8 tools for diagnostics, formatting, hover info, go-to-definition, references, completions, document symbols, and building.

## Prerequisites

- **Node.js** >= 18
- **Zig** compiler on PATH (`zig version`)
- **ZLS** on PATH (`zls --version`)

```bash
# macOS
brew install zig zls

# Or download from:
# https://ziglang.org/download/
# https://github.com/zigtools/zls/releases
```

## Installation

Add to Claude Code:

```bash
claude mcp add --transport stdio mcp-server-zig -- npx -y mcp-server-zig
```

Or from source:

```bash
git clone https://github.com/sadopc/mcp-server-zig.git
cd mcp-server-zig
pnpm install && pnpm build
claude mcp add --transport stdio zig -- node $(pwd)/build/index.js
```

## Tools

### `zig_diagnostics`

Get errors and warnings for a Zig source file.

| Parameter | Type | Description |
|-----------|------|-------------|
| `file_path` | string | Absolute path to the .zig file |

### `zig_format`

Format Zig code using `zig fmt`.

| Parameter | Type | Description |
|-----------|------|-------------|
| `file_path` | string? | Path to .zig file to format in-place |
| `code` | string? | Zig source code string to format |

Provide either `file_path` or `code`, not both.

### `zig_hover`

Get type information and documentation for a symbol at a position.

| Parameter | Type | Description |
|-----------|------|-------------|
| `file_path` | string | Absolute path to the .zig file |
| `line` | number | Zero-based line number |
| `character` | number | Zero-based character offset |

### `zig_definition`

Go to definition — find where a symbol is defined.

| Parameter | Type | Description |
|-----------|------|-------------|
| `file_path` | string | Absolute path to the .zig file |
| `line` | number | Zero-based line number |
| `character` | number | Zero-based character offset |

### `zig_references`

Find all references to a symbol.

| Parameter | Type | Description |
|-----------|------|-------------|
| `file_path` | string | Absolute path to the .zig file |
| `line` | number | Zero-based line number |
| `character` | number | Zero-based character offset |

### `zig_completions`

Get completion suggestions at a position.

| Parameter | Type | Description |
|-----------|------|-------------|
| `file_path` | string | Absolute path to the .zig file |
| `line` | number | Zero-based line number |
| `character` | number | Zero-based character offset |
| `limit` | number? | Max completions to return (default: 20) |

### `zig_document_symbols`

Get the document symbol outline (functions, structs, variables, etc.).

| Parameter | Type | Description |
|-----------|------|-------------|
| `file_path` | string | Absolute path to the .zig file |

### `zig_build`

Run `zig build` in a project directory.

| Parameter | Type | Description |
|-----------|------|-------------|
| `project_path` | string | Path to project directory (containing build.zig) |
| `args` | string[]? | Additional args for `zig build` |

## How It Works

```
Claude Code ←(MCP/stdio)→ mcp-server-zig ←(LSP/stdio)→ ZLS subprocess
                                          ←(shell exec)→ zig fmt / zig build
```

- **ZLS tools** (diagnostics, hover, definition, references, completions, symbols): The server spawns ZLS as a subprocess, communicates via LSP over stdio. ZLS is started lazily on first tool call and auto-restarts on crash.
- **CLI tools** (format, build): These call `zig fmt` and `zig build` directly — no ZLS needed.

## Troubleshooting

**"ZLS spawn error"** — ZLS is not installed or not on PATH. Run `which zls` to verify.

**"zig fmt failed"** — Zig compiler is not installed or not on PATH. Run `which zig` to verify.

**Diagnostics are empty** — ZLS needs time to analyze the file. The server waits 200ms by default. For large projects, diagnostics may take longer to appear.

**Tools hang** — Check that ZLS is compatible with your Zig version. ZLS and Zig versions should match.

## License

MIT