lockdocs

lockdocs

Exact-version library docs from your lockfile — local, offline, no rate limits.

Reads your lockfile. Answers from the docs and type declarations of the exact version you installed.

npm · PyPI · crates.io · Go. MCP server + CLI in one Rust binary. No account, no API key. MIT.

npx -y @sylphx/lockdocs setup

Docs · Quickstart · Tools · Benchmarks · Compare · How it works

A real terminal: one question, two installs. pydantic 1.10.18 answers BaseModel.dict() (pydantic/main.py:427), pydantic 2.9.2 answers model_dump() (pydantic/main.py:352). It opens with Next.js 14 vs 15 cookies().

See it work

Ask for the exact signature of BaseModel.model_dump in a project that pins pydantic 2.9.2 (the run in the demo above):

$ lockdocs api BaseModel.model_dump --tokens 300

pydantic@2.9.2 · pypi · .venv/lib/python3.12/site-packages · pinned in uv.lock

pydantic.main.BaseModel.model_dump (method) — pydantic@2.9.2 pydantic/main.py:352

def model_dump(self, *, mode: Literal['json', 'python'] | str = 'python', include: IncEx | None = None, …) -> dict[str, Any] Usage docs: https://docs.pydantic.dev/2.9/concepts/serialization/#modelmodel_dump

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

The same call in a pydantic 1 project answers that pydantic 1.10.18 has no model_dump, and shows the closest documentation instead.

Quickstart

npx -y @sylphx/lockdocs setup     # add lockdocs to Claude Code, Codex, Cursor, VS Code, Claude Desktop, Windsurf, Gemini CLI

That's it. Using Claude Code only? claude mcp add lockdocs -- npx -y @sylphx/lockdocs mcp. setup detects the clients you have, writes their MCP config, and prints every change. Run it again and nothing changes. Then ask your agent something like *"Use lockdocs: how do I reject unknown keys with the zod we use?"*

From a terminal, inside any project:

npx -y @sylphx/lockdocs zod "reject unknown keys"          # docs for the zod version in your lockfile

npx -y @sylphx/lockdocs api axum::Router::route # exact signature + doc comment npx -y @sylphx/lockdocs resolve # every pinned version, and whether its docs are here npx -y @sylphx/lockdocs fetch # once: add upstream docs at each version's git tag

Cursor and VS Code, one click

· Install in VS Code

Requires Node 18+. Confirm the install in your editor, open your project, and enable the server. Both links run npx -y @sylphx/lockdocs mcp locally; no API key is needed.

For VS Code from a terminal:

code --add-mcp '{"name":"lockdocs","command":"npx","args":["-y","@sylphx/lockdocs","mcp"]}'

Or add the server to .cursor/mcp.json:

{

"mcpServers": { "lockdocs": { "command": "npx", "args": [ "-y", "@sylphx/lockdocs", "mcp" ] } } }

For .vscode/mcp.json, use the VS Code servers format:

{

"servers": { "lockdocs": { "type": "stdio", "command": "npx", "args": [ "-y", "@sylphx/lockdocs", "mcp" ] } } }

<!-- editor-install:end -->

Manual MCP config

{

"mcpServers": { "lockdocs": { "command": "npx", "args": ["-y", "@sylphx/lockdocs", "mcp"] } } }

Claude Code: claude mcp add lockdocs -- npx -y @sylphx/lockdocs mcp Claude Code plugin: /plugin marketplace add SylphxAI/lockdocs, then /plugin install lockdocs@lockdocs Codex (~/.codex/config.toml):

[mcp_servers.lockdocs]

command = "npx" args = ["-y", "@sylphx/lockdocs", "mcp"]

The server answers for the client's workspace root (or its working directory, or LOCKDOCS_ROOT). Every tool also takes root.

Why

Your agent writes code against the library version it remembers, not the one you installed. So it calls .dict() on a pydantic 2 model, cookies() without await on Next.js 15, and /:id routes on axum 0.8. Hosted doc servers help, but they guess the version from the prompt, cap free usage, and cannot see your private packages.

lockdocs takes the version question off the table:

• Exact version, zero config. It reads package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock, Cargo.lock, uv.lock, poetry.lock, Pipfile.lock, requirements*.txt and go.mod. No library IDs, no "use v14" in the prompt.
• Docs that ship with the code. READMEs, changelogs and docs/ folders, plus the API reference in the package itself: .d.ts declarations with JSDoc, Python docstrings and stubs, rustdoc comments, Go doc comments. If it is installed, it is documented, including your private and internal packages.
• Offline and unlimited after caching. Package files are read from node_modules, your virtualenv, ~/.cargo/registry and the Go module cache. The optional model downloads once (129 MB, kept as 32 MB). Use --offline (or LOCKDOCS_OFFLINE=1) to prohibit all downloads; LOCKDOCS_EMBED=0 disables only the model. No account or hosted query quota. First-use upstream requests reveal the public repository and version being fetched, not your question or project files.
• Upstream docs on first use. Packages like Next.js, Django and FastAPI ship no docs. Queries automatically add public GitHub docs at the immutable commit resolved from your pinned release tag, anonymously and with bounded downloads. --no-fetch or LOCKDOCS_FETCH=0 opts out; cached docs still work offline. Failures are reported alongside local answers, never replaced with latest-version docs.
• Meaning, not just words. Hybrid retrieval: BM25 fused with a small local embedding model (downloaded once, 32 MB on disk), plus API redirects from deprecation notes ("use model_validate instead").
• Small, cited answers. Packed into a token budget (1,200 by default), every section cited as package@version path:line.

What your agent gets

Three tools, cheap enough to call before every unfamiliar API:

Ecosystems

Legacy copies bundled inside a package (zod/v3 inside zod 4, pydantic/v1 inside pydantic 2) rank below the current API.

Upstream docs on first use

The first docs or api query adds the selected dependencies' public release-tag docs once: it finds the GitHub repository in the package's own metadata and the git tag of your pinned version, resolves that tag to an immutable commit, and downloads only its docs folders (Markdown, MDX, reStructuredText, docs examples). It does not use ambient GitHub credentials or download major-version website docs by default. Previously opted-in docs-site caches are preserved and their provenance stays visible. lockdocs fetch remains available to prewarm docs and explicitly add major-version docs sites. Answers then cite next@15.1.0 upstream:docs/01-app/.../cookies.mdx:12. See Upstream docs and fetching.

Not installed? Fetch the exact version (opt-in)

Registry package downloads remain opt-in; default upstream enrichment uses installed package metadata (plus the one-time embedding model download). If a pinned package is not installed (a fresh clone, CI, a lockfile you are reviewing), it says so and tells you how to install it. Pass --fetch (or set LOCKDOCS_FETCH=1, or lockdocs setup --fetch) to let it download exactly that version from the registry (npm tarball, PyPI wheel or sdist, crates.io .crate, Go module proxy zip) into its cache. Fetched answers say fetched from registry.npmjs.org. You can also ask for a version you do not use: lockdocs npm:zod@4.1.5 "strict object" --fetch.

Benchmarks

105 questions whose correct answer depends on the version, over 15 libraries (zod, Next.js, React Router, pydantic, axum, tokio, Tailwind CSS, ESLint, Prisma, React, Vite, Express, SQLAlchemy, Django, FastAPI), each asked in a real project with that version installed. An answer passes when it contains the version-correct API and none of the other version's. Same questions and grader against