Cairn MCP server
Commit Oct 28, 2026Provides AI agents with a navigable documentation graph for repositories and structured documents using hierarchical summaries and semantic search.
Also known as jokeuncle/cairn
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 28, 2026
- License
- Apache-2.0
What is Cairn MCP?
Cairn provides AI agents with a navigable documentation graph for repositories and structured documents using hierarchical summaries and semantic search.
Summary generated from the project's README
About Cairn MCP server
Cairn provides a local-first documentation graph designed to help AI agents navigate software repositories and large structured documents. Instead of providing raw text chunks, it creates a navigable map consisting of document catalogs, hierarchical sections, multi-granularity summaries, and semantic vector overlays. This allows agents to fetch specific information at the required granularity using stable anchors rather than consuming entire files.
Developers use the tool by installing the docsgraph package via pip and initializing a repository. The system indexes various file types including Markdown, PDFs, and ADRs, as well as Office or web files converted via MarkItDown. It operates as an MCP-native server, exposing tools like list_documents, search_documents, and repo_context to any compliant AI client. The setup is primarily local, though users can configure embedding providers like Doubao or OpenAI for semantic search capabilities.
What you can do with it
- 1Analyze document cross-referencesAn agent can inspect how different documents within a repository are linked to one another.
- 2Evaluate documentation impactA developer can use the tool to compute how changes or deletions might affect document references.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
CAIRN_EMBED_API_KEYCAIRN_EMBED_MODELCAIRN_EMBED_PROVIDERCAIRN_LLM_API_KEYCAIRN_LLM_BASE_URLCAIRN_LLM_MODEL
| Name | Description | |
|---|---|---|
| CAIRN_EMBED_API_KEY | — | |
| CAIRN_EMBED_MODEL | — | |
| CAIRN_EMBED_PROVIDER | — | |
| CAIRN_LLM_API_KEY | — | |
| CAIRN_LLM_BASE_URL | — | |
| CAIRN_LLM_MODEL | — |
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablejokeuncle/cairn is public and reachablegithub.com/jokeuncle/cairn ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-28github.com/jokeuncle/cairn ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCairn
The DocsGraph for AI agents. CodeGraph helps agents navigate code; Cairn helps them navigate docs. Install it as
docsgraph; keep thecairnname for the product and compatibility alias.
Cairn is a local-first, MCP-native DocsGraph for software repositories and large structured documents. It turns README files, specs, ADRs, docs folders, PDFs, and optional MarkItDown-converted Office/data/web files into a navigable map: document catalog, hierarchical sections, multi-granularity summaries, entity mentions, cross-reference edges, and a semantic vector overlay.
Instead of dumping whole docs into context or relying on anonymous chunks, an
agent can ask Cairn to list_documents, search_documents, inspect an
outline, and drill into exact sections with stable cairn:// anchors. The
same engine also works for standalone handbooks, papers, and PDFs.
Cairn provides cited, bounded access to documentation through MCP and a local CLI. It is an experimental infrastructure tool: a general Agent cost advantage or commercial superiority has not been established. See the experiment ledger for retained successes, failures, controls and scope limits.
The latest public-document studies use real Codex Agents and independent answer and citation checks. All arms complete the selected tasks; task acceptance is separate from the predeclared cost gate:
| Study | Completed sessions | Cairn vs fresh raw: input / uncached input / output | Cost gate |
|---|---|---|---|
| Explicit document graph | 6 | −18.5% / −24.1% / +5.1% | Failed |
| Local reference analysis | 8 | +25.5% / −3.2% / +13.8% | Failed |
These rows use different target-document tasks and are not a before/after causal comparison. Input is cumulative, uncached input excludes cache hits, and output includes reasoning. Four target instances share one graph-analysis task family on two pinned public projects; they do not establish broad generalization. The analysis study includes a lightweight independent helper with the same mathematics. Build/storage costs and autonomous skill/verification overhead are disclosed in the reports. Earlier retrieval repairs, Agent cost diagnosis, paper-informed work, parity screens, strong controls, and the CLI screen remain available. Documentation with local code includes can be prepared explicitly before indexing.
🚀 Alpha —
0.1.0a13. Markdown + PDF ingest, the core MCP tool set, the full structure-aware index (tree + summaries + entities + xrefs + vectors), repo-levelinit/sync/status, repo-scoped MCP tools withlist_documents,search_documents,repo_context,repo_graph, andrepo_impact, failure-isolated sync, static graph inspector, Doubao multimodal embeddings, and an evaluation harness. SeeCHANGELOG.mdfor what's in this release andROADMAP.mdfor what's next.
Experimental capabilities (0.1.0a13)
The additions below are included in the 0.1.0a13 alpha and remain
experimental. Install with pip install --upgrade docsgraph==0.1.0a13, or use
pip install -e . for this checkout. Defaults
remain hybrid search, synopsis context, the section/entity graph and
artifact/entity impact. Original full text and the new reference views are
explicit choices.
| Need | Tool / option | Model call at query time |
|---|---|---|
| Find matching documents or context | search_documents, repo_context (hybrid default) |
Yes |
| Search literal terms without an endpoint | retrieval="lexical" on those tools |
No |
| Navigate or read cached sections | outline, get_section |
No |
| Inspect explicit cross-document links | repo_graph(view="documents") |
No |
| Compute reverse paths, cycles and deletion reachability | repo_impact(view="references") |
No |
Explore the current architecture · Architecture source and verification · Full architecture contract
After indexing a repository, the read-only CLI and MCP expose the same handlers:
docsgraph query tool repo_graph '{"view":"documents"}' --repo /path/to/project
docsgraph query tool repo_impact \
'{"view":"references","doc":"docs/guide.md","entry":"README.md","max_hops":3}' \
--repo /path/to/project
Replace the example paths with indexed sources (list_documents lists them).
The reference view follows explicit Markdown body links and returns canonical
shortest paths, cycle membership, deletion reachability and cited witnesses.
It reports completeness, caps and stale/skipped documents. Heading/code/HTML
links and external/unindexed targets are excluded; fragments are not validated.
References do not establish semantic or source-code impact.
An existing index is still required; query-time availability does not eliminate embedding, summary-generation, startup or storage costs. The current regression suite passes 620 tests (release validation); independent full-source checks cover all 42 target documents in the two graph corpora. CLI and MCP stdio graph/impact calls were verified with the model endpoint stopped. These checks qualify functionality, not general Agent cost savings. See CLI usage, embedding role configuration, ADR-0016 and ADR-0017.
Retrieval reliability update
Markdown prose before the first heading and documents without headings are
indexed as independent introduction sections. Existing heading anchors keep
their IDs. Run docsgraph sync after upgrading: old tree producers rebuild
automatically; a subsequent unchanged sync is a no-op.
repo_context returns cited summaries and bounded original evidence once per
section by default. Use get_section(doc, id, level="full") for complete examples
and precise conditions. Clients needing the earlier ranking and relationship
payload can pass include_details=true. MCP search explanations are also
available with search_documents(include_details=true); the Python library
search response remains detailed. repo_graph provides explicit graph inspection.
Section tools accept returned cairn://doc/section citations directly and reject
conflicting document namespaces. See ADR-0004
and the verified repair results.
Full section text excludes descendant bodies. Section reads now show bounded,
cited navigation links; get_related also finds siblings at the document root.
Compact context selects complementary original evidence rather than repeating
topic overviews. Small fenced code examples stay intact within excerpt budgets;
partial oversized code is marked truncated_code.
For a short-context embedding endpoint, explicitly opt into
CAIRN_EMBED_PROVIDER=windowed-openai-compatible before indexing and serving.
It embeds all 1,500-byte UTF-8 windows and pools one vector per original section;
it adds embedding work and can dilute localized facts. It does not discard text
or replace the document tree. Run sync after changing providers. Normal rebuilds
reuse stored summaries with matching model/content fingerprints; sync --force
bypasses that stored reuse. See ADR-0007
and ADR-0008.
Why Cairn?
| Today | With Cairn |
|---|---|
| AI coding agents guess from README snippets or grep. | Agent gets a repo-level documentation map with stable section anchors. |
| Dump the whole document into context. Burns tokens, dilutes attention. | Agent fetches only what it needs, at the granularity it needs. |
| Naive RAG splits structure into context-free chunks. | The document's own structure is the index. |
| Cross-references and entities are lost in chunking. | They are first-class objects. |
| Locked into one vendor's embeddings / vector DB. | Pluggable everything. Local-first defaults. |
| Different tool stacks for Claude / Cursor / Cline / Goose. | One MCP server. Any compliant agent works. |
For the in-depth motivation, see PRODUCT.md.
For the technical design, see ARCHITECTURE.md.
For the public documentation quality contract Cairn optimizes for, see
docs/golden-docs-standard.md.
The product website is published at https://jokeuncle.github.io/cairn/.
How It Works (90 seconds)
- Discover.
docsgraph init -ywrites.cairn/config.toml;docsgraph syncdiscovers README, Markdown docs, ADRs, specs, and PDFs from conservative repo globs. - Index. Each document becomes a normal Cairn index: structural tree (T),
multi-level summaries (S), entity index (E), cross-reference graph (X), and
vector overlay (V). A bad source file is isolated instead of breaking the
whole repo sync. Sync is incremental by default: unchanged source hashes and
producer fingerprints are skipped unless
--forceis passed. Concurrent syncs for the same repo are serialized by.cairn/sync.lock, so parallel agent sessions wait instead of rebuilding the same documents. - Serve.
docsgraph serveexposes repo-scoped MCP tools:list_documents,search_documents, plusoutline,get_section,expand,search_semantic,search_keyword,find_mentions,get_related, andread_rangerouted by optionaldoc. - Navigate. Your agent searches across the repo, picks a document, drills into promising sections, and only fetches full text when justified. Every result carries stable anchors for verification.
A visual explainer comparing Cairn's approach to RAPTOR, BookRAG, and A-RAG
lives at
docs/retrieval-architecture-canvas.html.
The repository workflow map lives at
docs/repo-docs-workflow-canvas.html.
Open either file in any browser.
Quickstart
The fastest way to see Cairn work is to index this repo's own documentation.
Zero API keys, zero model downloads — the --fake flag uses deterministic
in-process plugins so the whole thing runs offline.
The PyPI distribution is docsgraph; the primary CLI command is docsgraph.
The older cairn command is installed as a compatibility alias:
pip install docsgraph
Or run it without installing:
uvx docsgraph --help
AI agents that can run shell commands can install and wire Cairn into their own MCP config. Start with a dry run, then write the config once the target path looks right:
uvx docsgraph init -y
uvx docsgraph sync --fake
uvx docsgraph install --client codex --dry-run --fake
uvx docsgraph install --client codex --yes --fake
Use --client claude, --client cursor, or --client goose for other MCP
clients. docsgraph install writes the same server config that
docsgraph mcp config prints, with command = "docsgraph" and
args = ["serve"]. The server resolves the current MCP workspace at call time,
so a global agent config does not stay pinned to the repo where it was installed.
Pass --repo /path/to/repo to docsgraph install or docsgraph mcp config
only when you intentionally want a fixed-repo MCP server.
Repository Workflow
Inside any repository:
docsgraph init -y
docsgraph discover
docsgraph sync --dry-run
docsgraph sync --fake
docsgraph status
docsgraph query repo "where are docs indexed?" --fake
docsgraph doctor --fake
docsgraph mcp config --client claude --fake
docsgraph serve --fake
docsgraph client --fake
docsgraph discover and docsgraph sync --dry-run explain what will be
indexed before Cairn writes any document indexes: included docs, candidates
that did not match include rules, unsupported extensions, and excluded files
with their matching rule. docsgraph doctor checks repo config, index
freshness, primary-doc routing, model settings, and whether the query embedder
matches the indexed embedder mode and dimension. If an index was built with
--fake but the MCP server is running a real embedder (or the reverse), doctor
and fixed-repo serve print direct recovery commands. docsgraph mcp config
prints copy-pasteable stdio snippets for Claude, Cursor, Codex, and Goose. For
hosted providers, pass explicit MCP environment variables with repeated
--env KEY=VALUE, or use --env-from-current to copy the current CAIRN_*
environment into the generated config. docsgraph client opens a local browser
UI for init, sync, status, repo_context previews, and MCP config install
flows:
docsgraph mcp config --client claude
docsgraph mcp config --client cursor
docsgraph mcp config --client codex
docsgraph mcp config --client goose
docsgraph mcp config --client codex --repo . --env-from-current
For local development from source:
git clone https://github.com/jokeuncle/cairn.git
cd cairn
python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev]"
# 1. Create .cairn/config.toml with conservative documentation globs.
.venv/bin/docsgraph init -y
# 2. Index README, Markdown docs, and PDFs.
.venv/bin/docsgraph sync --fake
# 3. Inspect freshness and indexed document ids.
.venv/bin/docsgraph status
# 4. Search across all indexed repository docs.
.venv/bin/docsgraph query repo "where are docs indexed?" --fake
# 5. Start the repo-scoped MCP stdio server for Claude Code / Cursor / Cline / Goose.
.venv/bin/docsgraph serve --fake
Repo mode writes a shareable config plus ignored runtime data:
.cairn/
config.toml # commit this if you want a stable repo docs policy
manifest.json # generated
documents/ # generated per-document Cairn indexes
readme/
architecture/
docs-specs-mcp-tools/
Repo-scoped MCP adds:
| Tool | Use it for |
|---|---|
list_documents |
See every indexed doc, its source path, freshness, section count, and structured agent usage guidance. |
search_documents |
Find ranked, cited source hits across indexed docs. MCP ranking diagnostics are opt-in with include_details=true; recovery warnings are preserved. |
repo_context |
Get cited summaries and bounded original evidence once per section. Request include_details=true for ranking diagnostics and expanded relationships. |
repo_graph |
Inspect the repo documentation graph: document, section, entity, contains, xref, and mention edges. Cross-document links are exposed through shared entity nodes. |
repo_impact |
Estimate documentation surfaces affected by a document or section change. |
search_keyword |
Search all indexed docs when doc is omitted, or one selected doc when doc is provided. |
normal Cairn tools + doc |
Drill into a chosen document with outline, get_section, search_semantic, get_related, etc. |
Cairn is intentionally a docs graph, not a universal first step. Prefer
repo_context / search_documents for documentation, product, architecture,
setup, naming, protocols, business workflows, and durable decision records.
Prefer CodeGraph or native project tools for source-code symbol tracing, small
known-file edits, test output, build logs, and exact literal search.
list_documents returns the same usage boundary as structured
usage_guidance so MCP clients can route tasks without parsing README prose.
Repo behavior is intentionally configurable in .cairn/config.toml:
| Setting | Default | Impact |
|---|---|---|
include |
README, top-level Markdown/PDF, docs/**, guides/**, specs/**, ADR/decision/design/product/requirements/RFC/proposal dirs, one-level nested README |
Expands or narrows what Cairn treats as repository documentation. Broader globs improve coverage but can index noisy generated files. |
exclude |
.git, .cairn, .codegraph, caches, virtualenvs, package stores, build/site/coverage output, node_modules |
Keeps generated or tool-owned docs out of search. Simple name/** directory excludes match at any depth, so frontend/node_modules/... and apps/web/dist/... are skipped. Add project-specific generated doc folders here. |
enable_markitdown |
false |
Enables non-Markdown/PDF conversion when the markitdown extra is installed. Useful for DOCX/PPTX/XLSX/HTML-heavy repos, slower and less deterministic than native Markdown/PDF parsing. |
primary_doc |
readme |
Chooses the default document for normal tools when doc is omitted in repo mode. |
search_sections_per_doc |
1 |
Default diversity for search_documents. 1 helps agents find the right doc first; raise it when a repo has a few long docs and you want deeper hits from each doc by default. |
preferred_locales |
[] |
Optional locale preference for repo search, for example ["en"] or ["zh"]. When omitted, English queries prefer English or locale-neutral docs without hiding other languages. |
Markdown frontmatter is treated as generic document metadata. Cairn indexes
common fields such as title, description, tags, date, and draft, uses
them in keyword and semantic evidence, and marks metadata matches in search
explanations. Empty parent headings remain useful navigation nodes, but they
are down-ranked as primary evidence when a non-empty child section better
answers the query.
MarkItDown integration is local-file only and optional. Cairn uses it as a conversion layer, then feeds the generated Markdown into the same canonical Markdown parser. This expands coverage to formats such as DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, and EPUB without making the base install heavy:
pip install "docsgraph[markitdown]"
.venv/bin/docsgraph init -y --force --markitdown
.venv/bin/docsgraph sync --fake
Generate a standalone graph inspector for the primary repo doc:
docsgraph inspect --out /tmp/cairn-repo-inspector.html
Single Document Workflow
Cairn still works as a focused index for one large document:
# Index Cairn's own architecture document.
.venv/bin/docsgraph index ARCHITECTURE.md --out /tmp/cairn-arch --fake
# Get the map — gists only, never full text.
.venv/bin/docsgraph outline /tmp/cairn-arch --depth 2
# Keyword search: every section that mentions "LanceDB".
.venv/bin/docsgraph query keyword /tmp/cairn-arch LanceDB
# Multi-term keyword search with mode=all.
.venv/bin/docsgraph query keyword /tmp/cairn-arch progressive disclosure --mode all
# Generate a standalone graph inspector for the built index.
.venv/bin/docsgraph inspect /tmp/cairn-arch --out /tmp/cairn-arch/inspector.html
# Start a single-document MCP stdio server.
.venv/bin/docsgraph serve /tmp/cairn-arch --fake
A walkthrough with full output and an MCP-client config snippet is in
examples/hero-demo.md.
Cairn MCP questions
What files can Cairn index?
Cairn can index README files, specs, ADRs, documentation folders, PDFs, and Office or web files converted via MarkItDown.
How does Cairn differ from naive RAG?
Unlike naive RAG that splits structure into context-free chunks, Cairn uses the document's own structure as the index and treats cross-references and entities as first-class objects.
Can I run Cairn without API keys or model downloads?
Yes, you can use the --fake flag which uses deterministic in-process plugins to run the entire system offline.
What MCP tools are provided by Cairn?
Cairn provides repo-scoped tools including list_documents, search_documents, repo_context, repo_graph, and repo_impact.