Nowdocs

nowdocs is a local-first CLI tool and MCP server with built-in document management and hybrid retrieval, enabling coding agents to securely search current third-party documentation offline.

Comment

Inspiration

Coding agents are powerful, but they often work from stale or incomplete knowledge of fast-moving third-party frameworks. I wanted a way to give an agent current documentation without turning every query into a request to a hosted RAG service.

The design goal was simple: keep documentation retrieval local by default, expose it through the tools agents already use, and make every state-changing action explicit.

What it does

Nowdocs is an open-source, local-first documentation retrieval server for coding agents.

It lets tools such as Codex CLI, Claude Code, Cursor, and other MCP clients search current third-party documentation from a local index.

Key properties:

  • Hybrid local retrieval: vector search + BM25 + Reciprocal Rank Fusion.
  • MCP over stdio/NDJSON: no hosted service and no open network port.
  • Documentation, embeddings, and indexes stay on the user's machine.
  • Retrieved text is sanitized before it reaches an LLM.
  • MCP exposes read-only search and list tools only.
  • Installation, ingestion, updates, rebuilds, and rollback remain explicit CLI actions.
  • Optional remote reranking is explicit opt-in and retains a local fallback.

How we built it

Nowdocs is built in Rust as a single local binary.

Documentation is ingested and chunked locally, embedded with a pinned model, and stored in a local LanceDB index. At query time, Nowdocs combines vector retrieval with BM25 full-text search and fuses the results with Reciprocal Rank Fusion.

The server speaks the Model Context Protocol over standard input/output, so it can be connected to coding-agent clients without opening a port or running a hosted backend.

We also added agent-oriented setup, verification, and rollback flows. These flows make it possible to connect supported clients while keeping writes deliberate, inspectable, and reversible.

Challenges we ran into

The hardest part was not retrieval itself; it was defining safe operational boundaries.

Documentation can contain untrusted instructions, so retrieval results need sanitization before an LLM sees them. Client configuration writes also need to be defensive: no following symlinks, no silent overwrites, precondition checks before applying changes, and rollback that cannot be replayed indefinitely.

Another challenge was preserving the local-first promise while still allowing optional quality improvements. The result is an opt-in reranking path with bounded inputs and a local fallback, rather than a hidden remote dependency.

Finally, we wanted release artifacts to be practical for users. Prebuilt binaries and checksums are published for major platforms so users do not need to wait for a large local Rust compilation just to try the project.

Accomplishments that we're proud of

  • A local-first MCP server with no public service and no open port.
  • Read-only MCP tools paired with explicit, approval-gated CLI writes.
  • Hybrid retrieval that combines semantic and lexical search.
  • Safety boundaries for sanitization, configuration writes, verification, and one-shot rollback authorization.
  • Setup support for Codex CLI, Claude Code, Cursor, and generic MCP workflows.
  • A v0.2.0 release with prebuilt cross-platform binaries, checksums, CI gates, and an open-source codebase.

What we learned

Agent integrations need more than a configuration snippet. A trustworthy setup flow needs to answer: what will change, how can it be verified, what happens if the environment drifts, and can the change be safely rolled back?

We also learned that “local-first” has to be enforced in the architecture, not just stated in the README. Transport choices, storage design, write boundaries, update behavior, and optional remote features all need to make that promise concrete.

What's next for Nowdocs

Next, we are focusing on improving retrieval quality and source-level citations, expanding curated documentation coverage, and refining agent setup workflows based on real user feedback.

We also plan to keep strengthening the local-first and security model: better ranking diagnostics, clearer verification output, and more robust operational tooling for users who want current documentation without giving up control of their data.

Built With

  • bm25
  • candle
  • cli
  • codex
  • cohere
  • context
  • embeddings
  • face
  • github
  • hugging
  • jina
  • lancedb
  • model
  • openai
  • protocol
  • rust
Share this project:

Updates