mcp-server-zig: Instructions file for Claude Code

CLAUDE.md

MCP server exposing Zig language intelligence (via ZLS) as 8 tools for Claude Code. TypeScript, no framework beyond the MCP SDK.

Build & Run

pnpm install           # Install dependencies
pnpm build             # Compile TypeScript → build/
pnpm start             # Run the server (stdio transport)
pnpm dev               # Watch mode (recompile on change)

Requires zig and zls on PATH for tools to work. The server itself starts without them — errors surface per-tool.

Architecture

Claude Code ←(MCP/stdio)→ index.ts ←(LSP/stdio)→ ZLS subprocess
                                    ←(execSync)→  zig fmt / zig build

• src/index.ts — Entry point. Creates McpServer, registers all 8 tools with zod schemas, connects StdioServerTransport. All tool handlers follow the same pattern: call the tool function, return { content: [{ type: "text", text }] }, catch errors and return isError: true.
• src/zls-client.ts — ZlsClient class. Manages ZLS subprocess lifecycle: lazy start on first use, LSP initialize handshake, document open/close/re-sync, diagnostics collection via textDocument/publishDiagnostics notification, auto-restart on crash (3 attempts with backoff), graceful shutdown.
• src/tools/*.ts — One file per tool. Each exports a single function. ZLS-backed tools take a ZlsClient + params, CLI tools (format.ts, build.ts) call zig directly via execSync.
• src/utils.ts — Helpers: file↔URI conversion, severity/symbol/completion kind formatting.

Tools