mcp-server-zig CLAUDE.md

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

Tool	Backend	What it does
zig_diagnostics	ZLS	Errors/warnings from publishDiagnostics cache
zig_format	zig fmt	Format file in-place or code string via temp file
zig_hover	ZLS	textDocument/hover — type info and docs
zig_definition	ZLS	textDocument/definition — jump to definition
zig_references	ZLS	textDocument/references — find all usages
zig_completions	ZLS	textDocument/completion — suggestions at cursor
zig_document_symbols	ZLS	textDocument/documentSymbol — file outline
zig_build	zig build	Run build, return stdout/stderr + success bool