
zshref-mcp
io.github.carlwr/zshref-mcp
Offline zsh reference: look up syntax, search the manual, print docs. No shell, no network.
Documentation
zsh-lexicon
Status: pre-release. Published alphas exist to exercise CI and release workflows, not for use: they may not work, and their docs and links may be stale. The first non-alpha release has not yet been cut.
A structured zsh reference — a typed TS library and its JSON lexicon, parsed from the zsh manual — plus the tools built on it: a VS Code extension, a CLI and MCP server, a browser search SPA.
Packages
| Package | Purpose | Lives in | Distribution |
|---|---|---|---|
@carlwr/zsh-lexicon | Structured zsh reference: typed Lexicon, closed DocCategory taxonomy, resolve/renderRecord. Parsed from upstream zsh-5.9 Yodl source. | packages/zsh-lexicon/ | npm, JSON release assets |
zshref | Rust crate: the single-file executable zshref CLI (JSON on stdout) and the zshref-mcp Model Context Protocol server over stdio for MCP-aware clients (Claude Code, Claude Desktop, Cursor, VS Code MCP, Zed, …). Offline; no Node, Python, or zsh runtime dependency. | crates/zshref/ | crates.io, npm, GitHub release binaries; Homebrew planned |
better-zsh | VS Code extension: hovers, completions, semantic tokens, diagnostics. | packages/vscode-better-zsh/ | VS Code Marketplace, Open VSX |
zsh-lexicon-web | Browser SPA: local semantic search over the same reference — embeddings computed in the browser; index built from zsh-lexicon at build time. | packages/zsh-lexicon-web/ | static site: https://carlwr.github.io/zsh-lexicon/ |
Pick the package that matches your runtime; all wrap the same static zsh reference.
Architecture in one paragraph
Two layers, two adapters. zsh-lexicon (the knowledge layer) releases the reference as JSON; the Rust crate bakes it in at build time and owns the tool set (zsh_docs, zsh_search, zsh_list: name, JSON-Schema input and output, brief + long description, pure (lexicon, input) → output implementation). Each adapter — CLI, MCP — is thin transport glue over those definitions. The VS Code extension and the web SPA consume zsh-lexicon directly — the extension for its editor features, the SPA at build time for its search index.
No shell execution, no subprocess, no network, no filesystem, no environment reads in the tool layer — structurally enforced by a scope-fence test. This is a product feature, not just policy.
Status and roadmap
- Pre-release alphas are cut from this monorepo for CI/infra exercise.
- A first non-alpha release bundle is planned; no date committed.
Contributing
docs/design.md— architectural rationaleAGENTS.md— contributor conventions, testing, packaging, code styleSECURITY.md— security reporting
License
MIT. See LICENSE. Upstream zsh documentation notices: THIRD_PARTY_NOTICES.md.
@carlwr/zshref-mcpnpm install @carlwr/zshref-mcp