A
licenseNot graded
qualityD
maintenanceIndexes local files (PDF, TXT, CSV, Markdown) with embeddings for semantic search. Provides both CLI and MCP server interfaces so Claude Desktop can search and read your local documents.
MIT
Citepath
by arif-js
Citepath
Self-hosted search over your documentation, with citations, for AI assistants and apps.
Index docs websites and local folders, then let Claude, Cursor, or any MCP client answer from the current docs, with a link to every section it used.
Quick start · Demo · Why not RAG? · Commands · Docs · Contributing
Status: pre-release (0.1). Expect breaking changes before 1.0.
What it does
📚 Indexes your docs: documentation websites (from the sitemap or by following links, respecting robots.txt) and local Markdown, MDX, or text folders.
🔗 Returns cited passages: each search result links to the exact page section or file lines it came from.
🧠 Understands code and plain English:
getUserName,--dry-run, and "how do I configure caching" all work.🤖 Connects to AI assistants: Claude Code, Cursor, and other MCP clients search your docs; your own tools use the CLI or a local HTTP API.
🔒 Runs locally: no account, no API keys, no telemetry. Assistants get read-only access, and a failed sync never deletes good data.
Citepath finds passages; it doesn't write answers. Your assistant writes the answer from those passages and cites them, so you can check every claim.
Related MCP server: Alcove
Demo
Index the current Next.js docs once, then search them:
citepath add nextjs --url https://nextjs.org/docs/app --include '/docs/app/**' --sync
The same search works inside your assistant:
You: Using citepath, how do I set how long cached data lives in Next.js?
Claude: Add
'use cache'to the function and callcacheLife('hours'), or pass{ stale, revalidate, expire }. This requirescacheComponents: trueinnext.config.ts. Sources: cacheLife, use cache, cacheComponents
Who it's for
Developers using AI coding assistants: answers based on the current docs of your frameworks and services, not on what the model remembers.
Builders of AI tools: a retrieval layer that returns ranked, cited passages as JSON for any model.
Small teams: internal wikis, runbooks, and docs folders searchable by assistants, without a hosted platform.
Open-source maintainers: an easy way for users to connect your project's docs to their assistants.
Why not RAG or web search?
It is RAG: the retrieval half, run locally. Instead of embeddings and a vector database, Citepath uses a keyword index. That means no embedding API or keys, exact matches on identifiers like cacheLife, the same results for the same query, and citations down to the section. The trade-off: it matches words, not meaning, so "sign in" won't find a page that only says "authentication".
Web search is better for broad, one-off questions. Citepath is better when:
the docs are private: internal wikis, runbooks, and repo docs aren't on the web;
the version matters: you choose what's indexed, and search prefers the current copy of a page over old versions;
you want less to read: on the Next.js docs, 5 cited passages for "how do I set the cache lifetime" are about 4,200 characters, while the five pages they come from hold about 51,000 characters of text (the
cacheLifepage alone is about 1 MB of HTML);you're offline, or your assistant has no web search.
"The model already knows the docs." Only the version it was trained on. Fast-moving APIs, such as Next.js cacheLife, cacheComponents, or the new two-argument revalidateTag, are where models answer from outdated memory.
"Why not paste the docs into the prompt?" That works for a few pages. The Next.js docs are 845 pages; search picks the few passages that matter.
Costs and limits. Measured on a laptop with the Next.js and Vercel docs:
Free to run: no account, API keys, or per-search fees. Searches take milliseconds (p95 13 ms across about 30,000 passages).
Setup time and disk: syncing 845 Next.js pages took about 7.5 minutes at the polite default of 2 requests per second; the two sites use 83 MB.
Freshness: results are as current as your last sync. There is no built-in scheduler, so run
citepath syncfrom cron.Not indexed: sites that need JavaScript to render, PDFs, and docs behind a login.
Single user: one API token, no per-user permissions.
Use something else for broad questions (web search), meaning-based search (embeddings), or team access control. See Known limitations.
Quick start
Requires Node.js 22.16 or later.
npm install -g citepath
citepath add my-docs --path ~/work/project/docs --sync
citepath search "how do I configure authentication"
# Connect Claude Code (all projects)
claude mcp add citepath -s user -- citepath mcpRun /mcp in Claude Code to check the connection. For other assistants and scope options, see MCP setup. To run from source, see CONTRIBUTING.md.
Commands
Command | What it does |
| Create the config file. |
| Add a docs website. Repeat |
| Add a local docs folder. Repeat |
| Remove a source and its indexed content. |
| Fetch and index sources, with live progress. Run again to pick up changes or retry failures. |
| List sources with document counts and last sync status. |
| Show index locations, or a source's last sync: failures, removals, warnings. |
| Find matching passages with citations. Filter with |
| Show a passage in full, with |
| MCP server for AI assistants. Your assistant starts it; you don't run it yourself. |
| Read-only local HTTP API on |
| Export as JSONL, measure search quality, optimize the index, clear a stuck sync lock. |
Global options: --json, --quiet, --config <file>, --data-dir <dir>. See the CLI reference for all options.
Documentation
CLI · Configuration · How sync works · MCP setup · Local API · Result contract · Evaluation · Limitations · Design
Contributing
Contributions are welcome. Read CONTRIBUTING.md, open an issue before a larger feature, and report security problems privately as described in SECURITY.md.
License
Available Tools
3 toolsget_passageRead a passageARead-onlyIdempotent
Reads one passage in full by its ID, after search has found it. Use it when a search result was shortened, or when you need the text around a passage: neighbors adds up to 3 passages before and after it from the same page, in document order. Returns { passage, before, after }, each passage with its citation_url. To find passages, use search instead. Read-only; fails if the ID is unknown or its source was removed.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id field of a passage from a search result. IDs stay stable across syncs. | |
| neighbors | No | How many passages from the same page to include before and after it, in document order (0-3, default 0). |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: the failure conditions ('fails if the ID is unknown or its source was removed') and the returned shape { passage, before, after }. It stops short of discussing pagination or size limits, but that is minor here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and ID requirement, then usage, then return shape and failure modes. Dense but every sentence carries information; the only slight cost is that the neighbors detail is repeated from the schema, which costs a clause rather than a sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description supplies the return structure and citation_url detail, plus failure conditions and neighbor semantics. For a simple two-parameter read tool with full annotation coverage, an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are documented in the schema, including the neighbors 0-3 range, same-page scope, and document order. The description's neighbors sentence largely restates the schema, so it adds little beyond the baseline when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Reads one passage in full by its ID') and immediately scopes it to post-search retrieval, distinguishing it from the sibling search tool. An agent can tell what it does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('when a search result was shortened, or when you need the text around a passage'), names the alternative ('To find passages, use search instead'), and states the precondition that it follows a search. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_sourcesList sourcesARead-onlyIdempotent
Lists the configured documentation sources: id, name, type, document and passage counts, and the last sync status. Use the ids to narrow search with source_ids. Sources are added and synced only from the citepath CLI, not through MCP. Read-only.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read-only' is partly redundant. However, the description adds genuinely new behavioral context: sources can only be created/synced via the CLI, which no annotation conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no filler. The purpose and returned fields are front-loaded, followed by the downstream usage hint and the CLI-only constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema available, the description compensates by enumerating the returned fields (id, name, type, counts, sync status). For a zero-parameter, read-only list tool this is fully sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so per the rubric the baseline is 4. The mention of source_ids belongs to the sibling search tool, not to this schema, so no additional parameter semantics are needed here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Lists) and resource (configured documentation sources), and enumerates the returned fields: id, name, type, document/passage counts, and last sync status. An agent can distinguish this from search and get_passage without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent how to use the result ('Use the ids to narrow search with source_ids') and states an exclusion ('Sources are added and synced only from the citepath CLI, not through MCP'), preventing futile attempts to mutate sources through MCP.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
searchSearch documentationARead-onlyIdempotent
Start here: full-text search over the documentation indexed on this machine. Returns ranked passages, each with an id, title, heading path, citation_url, and text (long passages are shortened; read them in full with get_passage). Works with natural-language questions and code identifiers (getUserName, --dry-run, a.b.c). Results come from the current docs version; other_versions lists older versions that also matched, each with a path_prefix to pass back as path_prefix to search that version. Use list_sources to see which sources exist. Read-only.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of passages (default 5, max 25). | |
| query | Yes | What to look for: a question, keywords, or identifiers. | |
| source_ids | No | Only search these source IDs, as returned by list_sources. Omit to search all sources. | |
| path_prefix | No | Only passages whose URL (web sources) or root-relative path (local sources) starts with this prefix, for example a docs section or an other_versions path_prefix from a previous search. |
TDQS
A4.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description's 'Read-only' restates that. It earns credit beyond the annotations by disclosing result behavior: ranked passages with specific fields, long passages being truncated and requiring get_passage, and the fact that other versions are surfaced separately with a path_prefix to re-query.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose ('Start here') before result shape and versioning details. Dense and mostly waste-free, though the run-on sentence covering results, truncation, identifier support, versioning, and source listing packs a lot into one block.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the return fields (id, title, heading path, citation_url, text) and explaining truncation, versioning, and source scoping. An agent has everything needed to call it correctly and to follow up with siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so 3 is the baseline, but the description adds interpretation the schema lacks: query accepts natural-language questions and code identifiers (getUserName, --dry-run, a.b.c), and path_prefix can carry an other_versions prefix from a previous search. Default limit and source_ids behavior are covered in the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('full-text search over the documentation indexed on this machine') and immediately distinguishes itself from siblings by pointing to get_passage for full reads and list_sources for source discovery. An agent can tell what this tool does and what it is not without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Start here' explicitly frames this as the entry point, and the description names the alternatives with their triggering conditions: read shortened passages with get_passage, enumerate sources with list_sources, and pass an other_versions path_prefix back into search to query older versions. Explicit when/when-not/alternatives routing is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
2 tool updates
v0.1.1- Changed
get_passage2 fields changed- changed
Input schema / properties / id / descriptionPrevious value: -"Passage ID from a search result."New value: +"The id field of a passage from a search result. IDs stay stable across syncs." - changed
Input schema / properties / neighbors / descriptionPrevious value: -"Passages to include before and after (0-3)."New value: +"How many passages from the same page to include before and after it, in document order (0-3, default 0)."
- Changed
search2 fields changed- changed
Input schema / properties / path_prefix / descriptionPrevious value: -"Only passages whose URL or path starts with this prefix."New value: +"Only passages whose URL (web sources) or root-relative path (local sources) starts with this prefix, for example a docs section or an other_versions path_prefix from a previous search." - changed
Input schema / properties / source_ids / descriptionPrevious value: -"Only search these sources (see list_sources)."New value: +"Only search these source IDs, as returned by list_sources. Omit to search all sources."
3 tool updates
v0.1.0- First observed
get_passage - First observed
list_sources - First observed
search
TDQS
A4.6/5.0
Scored across 3 tools
Disambiguation5/5
Each tool targets a distinct action: search finds passages, get_passage retrieves a specific passage by ID, and list_sources enumerates available sources. The descriptions explicitly clarify the intended workflow (e.g., 'Start here' for search, 'after search has found it' for get_passage), leaving no overlap.
Naming Consistency4/5
Two tools follow a clear verb_noun pattern (get_passage, list_sources) in snake_case, but 'search' is a bare verb without a noun. This minor deviation is readable and common, but not fully consistent with the established pattern.
Tool Count5/5
The server's narrow purpose (documentation search and passage retrieval) is served by exactly three well-scoped tools: finding content, drilling into specific passages, and listing sources. Each tool is necessary, and the count sits at the low end of the recommended 3-15 range without feeling thin.
Completeness5/5
The read-only surface covers the essential workflow: discover sources, search across them, and retrieve full passages with neighborhood context. Source management is intentionally delegated to the CLI, so no obvious gaps exist for the MCP role.
Maintenance
ActivityNo data
ResponsivenessNo issues
Related MCP Connectors
Query any docs site via MCP. Submit a URL, ask questions, get cited answers.
A second brain for your AI agent. Shared memory for your team's AI agents, plus public and private knowledge bases — works with ChatGPT, Claude, Cursor and any MCP client.
Search the official docs of Claude Code, Cursor, OpenAI Codex and MCP, refreshed daily.
- docs2mcpOAuthcom.docs2mcp
Query your own PDFs and documents from any MCP client. Every answer cites the page it came from.
Related MCP Servers
- AlicenseAqualityAmaintenanceMCP server that gives AI coding agents on-demand access to private project docs via BM25 ranked search. One setup for Claude Code, Cursor, Codex, Gemini CLI, and more. Docs stay private, never in public repos.1516Apache 2.0
- FlicenseNot gradedqualityDmaintenanceIndexes documentation sites by base URL and serves keyword search, optional semantic search, and Markdown page retrieval as MCP tools, all from a single SQLite file.-
- AlicenseNot gradedqualityCmaintenanceIndex any documentation website and search it from AI coding assistants via the Model Context Protocol (MCP).11 npm11MIT