docs-search

Docs Search

Search the local Grounded Docs index for library documentation. These commands print JSON by default and never change the index.

When to use

• You need to answer a question about a library's API or behavior.
• You want to check which libraries and versions are indexed.
• You need the indexed version that best matches a version constraint.

Run list first if you are unsure whether a library is indexed. If it is not, use the docs-manage skill to index it before searching.

Commands

All three commands accept these flags:

Flag	Description
--output json|yaml|toon	Output format (default: JSON)
--server-url <url>	Use a remote worker (e.g. http://localhost:8080/api) instead of the local store
--quiet	Log errors only
--verbose	Log debug output

list

List every indexed library and its versions.

npx @arabold/docs-mcp-server@latest list --output yaml

Example output:

- name: react
  versions:
    - id: 1
      version: 19.0.0
      documentCount: 412
      uniqueUrlCount: 198
      indexedAt: 2026-10-18T22:28:47.000Z
      status: completed
      sourceUrl: https://react.dev/reference/react
      preserveHashes: false

An empty version is the library's unversioned documentation. A version with status: completed is fully indexed. Other statuses (queued, running, updating, failed, cancelled, not_indexed) mean the content may be missing or incomplete, and such a version may carry a progress field. An empty index prints [].

search

Search an indexed library with a natural-language query.

npx @arabold/docs-mcp-server@latest search <library> "<query>" [options]

Flag	Alias	Default	Description
--version <ver>	-v	newest version	Exact version or range (e.g. 18.x, 5.2.x). An exact version also matches the closest older version.
--limit <n>	-l	5	Maximum number of results (1 to 100)
--exact-match	-e	false	Match only the exact --version, without falling back to an older one. Requires --version.
--embedding-model <model>			Embedding model, e.g. openai:text-embedding-3-small

Example:

npx @arabold/docs-mcp-server@latest search react "useEffect cleanup" --version 18.x --limit 3 --output yaml

The output is a list of passages. Matches close together in a page share one passage, and matches far apart in the same page come back as separate entries, so a url can appear more than once. Each entry has:

• url: the page's URL
• content: the matching passage with surrounding context, as Markdown or text
• score: relevance score
• mimeType, sourceMimeType: the stored and original content types
• contentUrl: present when the content came from a different URL than url

No matches print []. A library that is not indexed makes the command fail with an error that suggests similar library names.

find-version

Resolve the indexed version that best matches a pattern.

npx @arabold/docs-mcp-server@latest find-version <library> [--version <pattern>]

Flag	Alias	Description
--version <pattern>	-v	Exact version or range; omit it for the newest version

Example:

npx @arabold/docs-mcp-server@latest find-version react --version "18.x" --output yaml

bestMatch: 18.3.1
hasUnversioned: false
message: "Best match: 18.3.1."

bestMatch is null when no version matches but unversioned documentation exists (hasUnversioned: true). When neither exists, the command fails.

Interpreting output

Results go to stdout as JSON unless --output names another format. Logs go to stderr; outside a terminal only errors are logged. Set LOG_LEVEL=INFO or pass --verbose to see progress messages. A failed command exits with a non-zero status.

Typical workflow

# 1. Check what is indexed
npx @arabold/docs-mcp-server@latest list --output yaml

# 2. Search for relevant docs
npx @arabold/docs-mcp-server@latest search react "server components" --version 19.x --output yaml

# 3. If the library is missing, index it first (docs-manage skill), then search again