read-mcp-server

A small Model Context Protocol server that lets an AI assistant (Claude Code, Claude Desktop, Cursor, …) search and read documentation from a single docs website. Point it at a docs site's base URL; it reads that site's sitemap.xml as its index — no search engine, no API key, no crawler.

Tools

Tool	Input	What it does
search_docs	query (string), limit (number, optional, default 10)	Ranks pages from the site's sitemap against the query and returns candidate titles + URLs. Does not return page content.
read_doc	url (string)	Fetches one page on the configured site, strips navigation/footer/scripts, and returns the main content as Markdown. Off-site URLs are refused.

The intended flow is search_docs → pick a URL → read_doc.

How it finds pages

On the first search_docs call the server fetches the site's sitemap.xml (following a <sitemapindex> if present) and caches the URL list in memory. Searching scores each URL's title and path slug against the query — whole-word matches beat prefix matches, title matches beat slug matches, and shallower pages win ties. If the site has no sitemap, it falls back to an llms.txt index at the site root.

This means matching is against page titles and URL slugs, not full page text. It is deterministic and self-contained, but a term that appears only in a page's body won't be found.

Requirements

• Node.js ≥ 20
• A documentation site that publishes a sitemap.xml (or an llms.txt)

Protocol support

Speaks MCP revision 2026-07-28 and the 2025 revisions (2024-10-07 … 2025-11-25) from the same process, over stdio. Which one a connection uses is the client's choice: hosts that predate 2026-07-28 open with the usual initialize handshake and see no change, so no config below needs updating. Hosts that negotiate 2026-07-28 get the stateless request model, and a tools/list result they may cache for an hour.

Install & build

npm install
npm run build

Configuration

Configured entirely through environment variables:

Variable	Required	Default	Purpose
DOCS_BASE_URL	✅	—	Root of the docs site. Only URLs under it are searched or read.
DOCS_SITEMAP_URL	N/A	<origin>/sitemap.xml	Override when the sitemap isn't at the site root.
DOCS_INDEX_TTL_MS	N/A	3600000 (1h)	How long the in-memory index is cached before refetching.
DOCS_MAX_CONTENT_CHARS	N/A	15000	Max characters returned by read_doc before truncation.
DOCS_USER_AGENT	N/A	read-mcp-server/<version>	User-Agent sent with every request.

Use with an MCP client

Add to your client's MCP config (e.g. .mcp.json for Claude Code, or claude_desktop_config.json for Claude Desktop). The simplest way is to run the published package with npx — no clone or build required:

{
  "mcpServers": {
    "blue-docs": {
      "command": "npx",
      "args": ["-y", "read-mcp-server"],
      "env": {
        "DOCS_BASE_URL": "https://modelcontextprotocol.io"
      }
    }
  }
}

Prefer to run a local checkout instead? Build it (see Install & build) and point the client at the built entry:

{
  "mcpServers": {
    "blue-docs": {
      "command": "node",
      "args": ["/absolute/path/to/read-mcp-server/dist/index.js"],
      "env": {
        "DOCS_BASE_URL": "https://modelcontextprotocol.io"
      }
    }
  }
}

Restart the client; the search_docs and read_doc tools should appear.

Try it locally

Inspect the tools interactively with the MCP Inspector:

DOCS_BASE_URL=https://modelcontextprotocol.io \
  npx @modelcontextprotocol/inspector node dist/index.js

Security

read_doc refuses any URL whose origin differs from DOCS_BASE_URL. Because the URL it receives comes from the model — whose context may include text from the docs pages themselves — this origin check is a deliberate guard against a prompt injection turning the tool into an SSRF vector (e.g. cloud metadata endpoints or internal services).

Project docs

This repo tracks its own work as structured documentation with @koniverse/koni-docs. Stories live in docs/sprints/stories/; the generated roll-up is docs/sprints/STATUS.md.

npm run docs:status     # regenerate docs/sprints/STATUS.md from story frontmatter
npm run docs:validate   # check the epic/sprint reference graph (exits non-zero on error)

STATUS.md is generated — edit stories, not the roll-up. It embeds a "Last generated" timestamp, so re-running docs:status always produces a diff even when no story changed; a timestamp-only change is expected.

Development

npm test          # run the test suite (vitest)
npm run test:watch
npm run typecheck
npm run dev        # run from source with tsx, e.g. DOCS_BASE_URL=… npm run dev

License

MIT