Connecting an agent

There are two ways to give an agent the documentation. The command line is the simpler one and works everywhere; MCP is there for clients that prefer a declared tool.

The command line, which is the recommended way

Any agent that can run a shell command can use docspack:

npx docspack ask "how do I verify a webhook signature"

Tell the agent the command exists, with one line in AGENTS.md or CLAUDE.md. One command writes it for you, into whichever of those files the project already has:

npx docspack agent install

Run `docspack ask "<question>"` for documentation on this project's dependencies.
It answers from the installed versions.

That is the whole setup. There is no server to configure, nothing per-agent, and nothing resident when nobody is asking. It works in Claude Code, Cursor, Codex, Aider, a shell script, or a CI job, including agents that do not speak MCP at all.

ask prints exactly what the MCP tool returns: the best-ranked chunks with their package, version and file, bounded by the same token budget. The two interfaces are the same code path, so neither is second class.

Writing the wiring, and keeping it current

docspack agent install writes a block delimited by <!-- docspack:start --> and <!-- docspack:end -->. Everything outside the markers is left exactly as it was, and re-running rewrites the block in place rather than appending a second copy — so a repository wired a year ago gets the current text by running the command again.

It writes more than the block when the project has somewhere to put it:

npx docspack agent check

check writes nothing and exits non-zero when the wiring is missing or out of date. It needs no flags: it reads back which of those surfaces the project chose and compares them against what this version would write, so it belongs in CI. A pasted instruction that has drifted from what the tool does is otherwise something nobody ever notices.

Letting an agent report a problem

An agent reading documentation is unusually well placed to notice it is wrong. Add a second block to AGENTS.md if you want it to write those observations down:

If the documentation is wrong, record it: `docspack feedback add --chunk <id>
--kind <drift|incorrect|missing> --evidence "<claim>"`. The chunk id is the
heading above each answer. Only claims that can be shown false; incorrect and
missing also need --expected, --actual and --repro. It writes to a local file
for a human to review, and sends nothing.

The chunk id is the ## @acme/docspack@1.4.0/webhooks heading printed above every answer, so an agent already has what --chunk needs without another query.

The last sentence is the one that matters. An agent that thinks it is filing an issue behaves differently from one that knows it is appending to a file a human will read, and only the second is true. See the chunk on trust and safety for what add refuses and why.

This block is deliberately separate. Reading documentation and reporting on it are two decisions, and a team that only wants the first pastes only the first.

What a query costs

A query spawns a process, which sounds expensive and is not: about 101 milliseconds, of which roughly 41 is Node itself starting. That is invisible next to the seconds a model spends thinking, and it is only paid when a question is actually asked.

Commands that need heavier machinery load it when they run, not at startup. Importing the whole library costs about 263 milliseconds, against about 16 for the query path alone, so ask imports only what it needs.

MCP, for clients that prefer a tool

claude mcp add docspack -- npx -y docspack mcp

Or, for Cursor and other clients that read a JSON configuration:

{
  "mcpServers": {
    "docspack": { "command": "npx", "args": ["-y", "docspack", "mcp"] }
  }
}

The server exposes two tools. query_local_docs takes a free-text query and an optional packageFilter, and returns text identical to docspack ask. record_docs_problem is the MCP equivalent of docspack feedback add, taking chunkId, kind, evidence and — for anything but drift — expected, actual and repro. The server speaks the protocol on stdout and writes diagnostics to stderr.

record_docs_problem is the only tool that writes anything, and what it writes is a line in a local file. It cannot reach a maintainer: docspack has no code that can send a report, over MCP or otherwise. Its description says so, because a model that believes it is filing an issue behaves differently from one that knows a human reads the file first.

Every rule is enforced in one place, so MCP is not a looser way in than the command line. A kind outside drift, incorrect and missing is refused by the schema; an incorrect finding without a reproduction is refused by the same check the CLI uses; a chunk that is not installed is refused before anything is written. When a call is refused, the reason comes back naming the field that was missing, so an agent can correct itself instead of guessing.

The trade is real in both directions. A declared tool advertises itself: the agent sees the name, the schema and the description, and knows when to reach for it without being told. In exchange, the tool definition occupies the context window for the whole session whether or not it is used, the server process stays resident, and every client configures MCP differently.

Choose MCP when you want the agent to discover the capability by itself. Choose the command line when you want zero setup and nothing running in the background — which is most of the time.

How results are scoped

Both interfaces read the package.json of the directory they run in, and restrict results to the package versions that project installed.

This matters because the index is shared. Another project on the same machine may have indexed a different major version of the same library. That version is in the database, but it is invisible to this project’s queries. An agent cannot accidentally answer from documentation for a version you are not running.

How much context a query returns

Agents over-fetch. Left alone, a retrieval tool will happily return more than the model can use and crowd out the rest of the conversation.

docspack bounds every response, over MCP and on the command line alike. It returns the three best-ranked chunks by default and stops adding chunks once the response would exceed 3,000 tokens, using the token count recorded for each chunk rather than measuring after the fact. A single chunk larger than the budget is still returned, so a query never comes back empty because of the limit.