Repository avatar
Search & Data Extraction
v0.1.0-alpha.5
active

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

PackagePurposeLives inDistribution
@carlwr/zsh-lexiconStructured zsh reference: typed Lexicon, closed DocCategory taxonomy, resolve/renderRecord. Parsed from upstream zsh-5.9 Yodl source.packages/zsh-lexicon/npm, JSON release assets
zshrefRust 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-zshVS Code extension: hovers, completions, semantic tokens, diagnostics.packages/vscode-better-zsh/VS Code Marketplace, Open VSX
zsh-lexicon-webBrowser 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 rationale
  • AGENTS.md — contributor conventions, testing, packaging, code style
  • SECURITY.md — security reporting

License

MIT. See LICENSE. Upstream zsh documentation notices: THIRD_PARTY_NOTICES.md.

NPM
@carlwr/zshref-mcp
Install Command
npm install @carlwr/zshref-mcp