Provides deterministic documentation handoffs and ownership mapping to help coding agents navigate repositories and edit code with evidence-linked context.
Also known as AgentsKit-io/doc-bridge, doc-bridge, @agentskit/doc-bridge
- Stars
- 10
- Tools
- —
- Downloads, 30 days
- 28,951
- Latest version
- 2.4.0
- Last commit
- Nov 14, 2026
- License
- MIT
What is Doc Bridge MCP?
Doc Bridge provides deterministic documentation handoffs and ownership mapping to help coding agents navigate repositories and edit code with evidence-linked context.
Summary generated from the project's README
About Doc Bridge MCP server
Doc Bridge provides a deterministic way to hand off documentation and ownership mapping to coding agents. It transforms human-readable documentation from sources like Docusaurus, Fumadocs, or Markdown into structured AgentHandoff objects. This allows AI agents to understand exactly where to start reading, which files they are permitted to edit, and which specific tests must pass to verify their changes.
The system operates locally via a CLI tool called ak-docs and can be integrated into development workflows through an MCP server. This server enables clients like Cursor or Claude Code to resolve handoffs before attempting code edits. Notably, the core functionality works without requiring an LLM or any API keys, relying instead on a deterministic layer to map repository structures. It also includes tools to audit documentation quality by comparing declared ownership against the actual project graph to find contradictions or stale relations.
What you can do with it
- 1Automate agent handoffsConvert existing human documentation and ownership files into structured context for AI agents.
- 2Audit documentation accuracyIdentify contradictions between your written documentation and the actual structure of your code repository.
- 3Detect documentation driftCompare different versions of your repository to see how documentation references have broken or changed.
Written from the project's README. Every use case is checked against a quote from it.
How to install Doc Bridge MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Doc Bridge MCP in Claude Code
$ claude mcp add doc-bridge -- npx -y @agentskit/doc-bridgeInstall Doc Bridge MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"doc-bridge": {
"command": "npx",
"args": [
"-y",
"@agentskit/doc-bridge"
]
}
}
}Install Doc Bridge MCP in VS Code
.vscode/mcp.json
{
"servers": {
"doc-bridge": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@agentskit/doc-bridge"
]
}
}
}Install Doc Bridge MCP in VS Code CLI
$ code --add-mcp '{"name":"doc-bridge","type":"stdio","command":"npx","args":["-y","@agentskit/doc-bridge"]}'Install Doc Bridge MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"doc-bridge": {
"command": "npx",
"args": [
"-y",
"@agentskit/doc-bridge"
]
}
}
}Install Doc Bridge MCP in Codex
$ codex mcp add doc-bridge -- npx -y @agentskit/doc-bridgeInstall Doc Bridge MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.doc-bridge] command = "npx" args = ["-y", "@agentskit/doc-bridge"]
Install Doc Bridge MCP in Gemini CLI
$ gemini mcp add -s user doc-bridge npx -- -y @agentskit/doc-bridgeInstall Doc Bridge MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"doc-bridge": {
"command": "npx",
"args": [
"-y",
"@agentskit/doc-bridge"
]
}
}
}Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubdoc-bridge
npm: @agentskit/doc-bridge · CLI: ak-docs · Landing: agentskit-io.github.io/doc-bridge
Topics: ai-agents · documentation · developer-experience · mcp · llms-txt · typescript
Compatibility: node >=22 · TypeScript 5.8+ · pnpm, npm, or yarn consumers
Deterministic proof of documentation drift, with evidence-linked handoffs for coding agents.
Turn your docs into executable handoffs: doc-bridge reads your repo docs, ownership map, and human documentation site, then gives humans and agents the same evidence-linked starting point:
- where to start reading
- which files/packages it may edit
- which checks prove the change
- which human docs explain the feature
The core works without any LLM or API key; the documentation portal dogfoods AgentsKit Chat as an optional surface over that deterministic layer.

Built for agent-scale repositories
Doc Bridge turns large repository structure and documentation into compact, evidence-linked context that humans and coding agents can query instead of repeatedly traversing the full repository.
Historical context-payload estimate
An earlier anonymized dogfooding cycle estimated up to 99% less serialized context payload. This is a historical payload estimate—not a guarantee of provider-token savings, answer quality, or semantic correctness. It is not the same measure as provider-token usage.
Historical controlled A/B signal
The published controlled study with 96 anonymized executions reported a directional operational signal of:
- 18.46% fewer paired provider token-equivalent units across 46 token-complete pairs;
- 39.75 seconds lower P95 latency;
- 87.5% operationally completed executions vs. 75.0% with repository-only context.
These are historical, separately defined measures: the 99% figure is an estimated context-payload reduction, while the 18.46% figure uses provider-token-equivalent data from 46 paired observations. The bounded adjudicator recorded zero adjudicator-success outcomes in both arms; because that adjudicator is mechanical and does not independently judge semantic correctness, this result is directional and inconclusive. A newer local pilot is intentionally not promoted here while its semantic evaluation and publication review remain incomplete. See the full methodology and anonymized data. The separate Layer-1 benchmark results measure deterministic documentation findings with native and fixture scores reported separately.
Why teams use it
Agents are powerful, but most repo docs are written for humans. The result is familiar: the agent guesses ownership, edits the sibling package, runs the wrong test, or ignores the human guide that already explained the rule.
doc-bridge works in both directions:

| Direction | What it does | Command |
|---|---|---|
| Human docs → agents | Turns Fumadocs, Docusaurus, markdown, and ownership docs into AgentHandoff |
ak-docs index · ak-docs query --agent |
| Agent memory → docs | Reads .agent-memory/** and .cursor/rules/*.mdc, classifies what should become project docs, and drafts a human-reviewed promotion |
ak-docs memory ingest · classify · promote --pr |
The handoff is a routing contract:
{
"startHere": "docs/for-agents/packages/auth.md",
"editRoots": ["packages/auth"],
"checks": ["pnpm --filter @demo/auth test"],
"humanDoc": "/docs/guides/auth"
}
Workflow runs may carry the same optional correlation envelope used by the
AgentsKit runtime and Chat protocol. operationId is the cross-repository
identity; runId, sessionId, turnId, actionId, and traceId retain local
meaning. It is bounded metadata only and must not contain prompts, secrets, or
document content.
That contract works from the terminal, MCP, CI, and optional RAG/chat.
Documentation quality and reconciliation
Discovery is only the first step. ak-docs audit documentation compares declared documentation and ownership with the observed project graph and reports evidence-backed findings for missing coverage, stale relations, structured contradictions, exact duplicates, missing examples, and incomplete maintenance metadata.
Natural-language correctness, unnecessary prose, and semantic redundancy remain explicitly not-analyzed until a configured agent or human review evaluates them. Proposed changes stay reviewable and human-approved.
Example finding (anonymized)
CONTRADICTION · high confidence
Documentation declaration differs from the observed project relation
Evidence: 4 source files + 1 documentation declaration
Action: review ownership and update the canonical document
Verify documentation divergence
Compare revision snapshots deterministically: inspect symbol, CLI, configuration
and signature changes, historical references and remaining head citations.
Broken references require removal evidence; ambiguity and unsupported extraction
stay explicit. Changed references require review. Default policy routes findings
separately from their evidence status; use --no-policy to inspect raw diagnostics.
From a built checkout, this runnable comparison snapshots a temporary copy of
the signature fixture before and after removing a cited export. Use an installed
ak-docs, or replace it with node /path/to/checkout/bin/ak-docs.js from a built
checkout. The Node step extracts the raw snapshot from the discovery response:
set -e
work=$(mktemp -d)
cp -R tests/fixtures/signature-api "$work/repo"
(cd "$work/repo" && ak-docs discover --json) > "$work/discovery.json"
node -e 'const fs = require("node:fs"); const result = JSON.parse(fs.readFileSync(process.argv[1], "utf8")); fs.writeFileSync(process.argv[2], JSON.stringify(result.snapshot))' "$work/discovery.json" "$work/base.json"
sed '/^export const describeThing/d' "$work/repo/api.ts" > "$work/api.ts"
mv "$work/api.ts" "$work/repo/api.ts"
ak-docs diff --base "$work/base.json" --root "$work/repo"
ak-docs diff --base "$work/base.json" --root "$work/repo" --no-policy
rm -rf "$work"
Capture each revision independently for a real delta. See diff and findings and Action advisory mode for bounded PR reports. Reports never approve documentation corrections.
2.0 workflows
- Vault: opt-in Obsidian discovery reads wikilinks, aliases and tags;
ak-docs vault exportgenerates ignored navigation notes andvault diffturns edited generated notes into pending proposals. Vault guide. - Rationale: enable
index.knowledgeEntities.enabled, index decisions/concepts/changes, then runak-docs why <path|symbol|concept>. MCP exposesknowledge.decision,knowledge.conceptandknowledge.whyChanged. Evidence is observed rationale, not inferred causality. Knowledge query contract. - Remediation: optional
ak-docs fix --llmuses scripted fake-provider responses in the key-free guide; real providers use explicit intelligence configuration. Proposals require deterministic rechecking and human review. - Advisory:
CHANGED_REFERENCEconcerns a claim about the changed aspect; bare mentions do not trigger it. Unknown syntax remains review-required uncertainty. Action advisory. - Upgrade: follow the 1.x → 2.0 migration guide. This package ships no Studio UI; use the deterministic StudioGraphV1 export to visualize the graph with other tools.
The latest Layer-1 benchmark and method report native findings at 100% precision (15 TP, 0 FP, 0 FN), historical changed-reference findings at 83.3% precision (10 TP, 2 FP, 0 FN), and 6.25% false-positive rate on historical negative cases (2/32). These purposive controls measure different denominators; they do not establish general semantic accuracy or release readiness.
60-second proof
This README owns the one-command proof; the Getting started guide owns the complete repository setup and first-index workflow.
npm i -D @agentskit/doc-bridge
npx ak-docs demo --text
No config, no docs to read first. Output shows before/after, a real handoff, gate red→green, and the MCP snippet:
After (handoff.resolve / query --agent)
✓ target: auth (packages/auth)
✓ start: docs/for-agents/packages/auth.md
✓ edit: packages/auth
✓ checks: pnpm --filter @demo/auth test · pnpm --filter @demo/auth lint
✓ human guide: /docs/guides/auth
Gate: red → green
Verify the real handoff path
This checked example runs the bundled demo through the public CLI. The
repository's scripts/check-readme-standard.mjs gate compares this block byte-for-byte
with the executable fixture; .github/workflows/ci.yml runs that gate and its
executable tests on every pull request.
The study figures below are not recomputed by the README gate; their protocol, privacy checks, and limitations are documented in the linked study artifacts.
import { execFileSync } from 'node:child_process'
execFileSync(process.execPath, ['bin/ak-docs.js', 'demo', '--text'], {
stdio: 'inherit',
})
node examples/verify-handoff.mjs
For the complete repository setup, follow the Getting started guide.
Using Cline? Follow the deterministic llms-install.md setup. It runs the pinned MCP server through pnpm dlx without adding Doc Bridge to your repository dependencies.
What ships
See the surface map for a visual overview of the CLI, MCP, CI, and adapter surfaces.
| Surface | Use it for | Command / artifact |
|---|---|---|
| CLI | Inspect ownership, search docs, run gates, ask local questions | ak-docs query, search, ask, doctor, gate |
| MCP server | Let Cursor, Claude Code, Codex-style agents resolve handoffs before editing | ak-docs mcp, handoff.resolve |
| GitHub Action / CI | Fail stale indexes and configured documentation gates on PRs | AgentsKit-io/doc-bridge@ee756a13c006c597445c31e2643c1e8cece715d7 |
| Documentation conformance | Check the stable ecosystem standard with auditable evidence | ak-docs conformance run documentation-standard-v1 --text |
| Documentation audit | Measure documentation quality and compare docs with the observed project graph | ak-docs audit documentation --json |
| Doc adapters | Link human docs to agent docs | fumadocs, docusaurus, vitepress, starlight, nextra, plain-markdown |
| Monorepo routing | Discover workspaces and checks | pnpm-monorepo, nx |
| Memory pipeline | Turn agent notes into reviewable documentation drafts | memory ingest, classify, promote --pr |
| Optional RAG/chat | Ground chat in the same handoff-first index | @agentskit/rag, @agentskit/ink, ak-docs chat |
See Getting started, MCP, Examples, and Why doc-bridge.
Cursor plugin
This repository also contains a Cursor plugin that pairs the Doc Bridge MCP server (read-only except for the explicit proposal tool) with a handoff skill. It resolves startHere, readBeforeEditing, editRoots, and checks before Cursor edits a routed repository. The plugin does not request credentials. Its MCP tools are read-only except docbridge.proposals, which can save a review artifact under .doc-bridge/ and record enrichment approve/reject decisions; no MCP tool edits documentation or source files or applies remediations.
GitHub Copilot plugin
The root Agent Plugins manifest exposes the same portable handoff skill and MCP server to GitHub Copilot CLI. Copilot discovers skills/ and .mcp.json from the standard plugin layout, so the integration stays source-owned instead of copying prompts into another repository.
copilot plugin install AgentsKit-io/doc-bridge
Portable Agent Skill
skills/doc-bridge-handoff packages the same fail-closed routing contract in the open Agent Skills layout for OpenClaw-compatible clients, Hermes Agent, Pi, Cursor, and other runtimes that can execute a local skill script. The skill prefers the read-only MCP tool and falls back to a pinned, zero-credential CLI resolver. It never edits files, runs returned checks, or grants authority outside editRoots.
Install the published skill from ClawHub:
clawhub install doc-bridge-handoff
Pi users can install the same source-owned skill through the npm package:
pi install npm:@agentskit/doc-bridge
Claude Desktop MCP Bundle
Doc Bridge can be packaged as a local MCP Bundle for Claude Desktop. The bundle advertises 14 MCP tools, exercises 8 of them in its smoke test, and marks every tool except docbridge.proposals read-only. It asks the user to select the repository's doc-bridge.config.json; that file defines the project boundary Doc Bridge may read.
From a clean checkout:
pnpm install --frozen-lockfile
pnpm mcpb:pack
The command builds Doc Bridge, creates a production-only staging directory, validates the MCPB manifest, packs the extension, checks its file inventory, and writes the local artifact under .mcpb-output/. Generated bundles and staging directories are intentionally excluded from Git.
The current packaged compatibility declaration is macOS-only; this project does not claim bundle support for other operating systems until the exact artifact passes an independent installation test there.
Why this exists
| Pattern | Gap |
|---|---|
| Wiki + RAG | Explains; weak on where to act and proof docs match code |
| AGENTS.md alone | Great static rules; no ownership index, gates, or human bridge |
| Context7-class tools | Library docs for the model; not your monorepo routing |
doc-bridge ships AgentHandoff JSON:
{
"type": "agent-handoff",
"startHere": "docs/for-agents/packages/auth.md",
"editRoots": ["packages/auth"],
"checks": ["pnpm --filter @demo/auth test"],
"humanDoc": "/docs/guides/auth",
"bridge": { "humanDoc": "linked" }
}
When a human guide is missing, handoffs surface it as a feature:
{
"bridge": {
"humanDoc": "missing",
"action": "ak-docs bootstrap agent-docs"
},
"notes": ["Human guide missing for billing. Run: ak-docs bootstrap agent-docs"]
}
Five loops (with real commands)
| Loop | Command | What you see |
|---|---|---|
| Act | ak-docs query package auth --agent |
editRoots, checks, startHere |
| Bridge | ak-docs bootstrap agent-docs |
Draft agent docs from human site; bridge.humanDoc in handoff |
| Learn | ak-docs memory classify → promote |
HITL draft for agent corpus |
| Verify | ak-docs diff --base base.json --head head.json |
Revision delta, review impact and bounded reference findings |
| Explain | ak-docs ask "auth is broken in staging" |
Ownership match + handoff preview + next commands |
ak-docs ask "who owns schemas"
# Best match: ownership os-core
# Handoff preview
# start: docs/for-agents/packages/os-core.md
# edit: packages/os-core
# checks: pnpm --filter os-core lint · pnpm --filter os-core test
Coverage your team checks daily
The following is illustrative output from the command, not a measurement of this repository. Run the command locally or in CI for current values.
ak-docs doctor --text
ak-docs doctor --badge # shields.io markdown for README
ak-docs index --watch # keep index fresh while editing docs
Score: 82/100 (B)
Agent docs: 8/10 (80% handoff-ready)
Human guides: 6/10 (60% bridged)
Gates: 3/3 passing
Next actions
→ ak-docs bootstrap agent-docs
→ ak-docs query package billing --agent
Agent uses it alone
- MCP auto-wire:
ak-docs mcp install --cursor - Skill/rule: paste docs/skills/doc-bridge.md into Cursor rules — agents call
handoff.resolvebefore editingpackages/* - Handoff is the next step:
startHere,checks, andbridgeare in the JSON/MCP response
CI as first-class citizen
Reuse the bundled GitHub Action on every PR:
Follow the canonical Gate and CI guide, which includes the complete workflow and pins the published Action release.
The Action installs the exact configured package (or the workspace package when dogfooding this repository), then verifies the committed index and configured gates without silently rebuilding them. It rejects non-exact package versions. See the Marketplace guide.
The guide is pinned to the published stable Action release v1.7.45; the
checked-in package version is 2.6.0.
Coverage is repository-specific. Run ak-docs doctor --badge locally to emit
current handoff and human-bridge badges, or pnpm coverage:badge in CI; this
README intentionally avoids publishing a stale static percentage.
For this repository, generate the ignored index before local checks:
node bin/ak-docs.js index
node bin/ak-docs.js gate run
Never commit this repository's .doc-bridge/index.json. CI builds it twice and
compares artifact bytes, then checks reproducibility and documentation conformance.
This verifies deterministic generation, not committed-index freshness. Consumer
repositories using the Action still verify their committed index before rebuilding.
Product surface
Core — always (no LLM)
| Surface | Purpose |
|---|---|
| Demo | ak-docs demo — bundled fixture, no setup |
| Doctor | Coverage score, missing humanDoc/agent doc, next actions |
| Index | DocBridgeIndex + contentHash + llms.txt + capabilities |
| CLI | query / search / list / ask / gate / bench / memory / bootstrap |
| MCP | handoff.resolve, doc.search, doc.get, gate.status, … |
| Gates | Freshness, human-link validation, optional OKF style |
| Adapters | pnpm-monorepo, nx, fumadocs, docusaurus, vitepress, starlight, nextra, plain-markdown |
Optional AgentsKit peers
npm i -D @agentskit/rag @agentskit/ink @agentskit/adapters @agentskit/memory react
ak-docs rag ingest && ak-docs chat
See docs/chat-and-rag.md.
AgentsKit ecosystem
Who uses it (public)
Designed for and dogfooded on open AgentsKit surfaces:
| Surface | Link |
|---|---|
| for-agents | agentskit.io/docs/for-agents |
| Registry | registry.agentskit.io |
| Playbook | playbook.agentskit.io |
| AgentsKit Chat | documentation · source |
| Code Review | site · source |
| Harness | documentation · source |
| This repo | CI green · ak-docs gate run on every PR |
Playbook pattern: docs/playbook/doc-bridge-pattern.md — export with ak-docs playbook pattern --text
Configuration examples
| Profile | Example |
|---|---|
| Solo markdown | examples/minimal-plain-markdown.config.ts |
| pnpm monorepo | examples/pnpm-monorepo.config.ts |
| Nx monorepo | examples/nx-monorepo.config.ts |
| Demo monorepo | examples/demo-monorepo/ |
| Fumadocs + chat | examples/fumadocs-with-chat.config.ts |
| VitePress | examples/vitepress-only.config.ts |
| Astro Starlight | examples/starlight-only.config.ts |
| Nextra | examples/nextra-only.config.ts |
Contract: docs/spec/config-v1.md · CLI: docs/spec/cli.md · MCP: docs/mcp.md · Skill: docs/skills/doc-bridge.md · Pattern: docs/playbook/doc-bridge-pattern.md · Recipes: docs/recipes/index-pipeline.md
Learn loop — memory → draft PR
ak-docs memory ingest
ak-docs memory classify
ak-docs memory promote --pr --dry-run # preview gh commands
ak-docs memory promote --pr # opens draft PR via gh
Status
Published npm package: v1.7.45 stable. The working-tree package version is
1.8.0 and is not published yet. The Action example below intentionally pins
the latest published stable release; the release workflow updates the package
and Action version together when a new release is published.
The published package provides portable, fail-closed handoffs through the CLI, MCP server, CI action, and packaged skill; deterministic Documentation Standard v1 conformance; verified release provenance; and documentation-quality audit tooling.
pnpm install && pnpm build && pnpm test
pnpm smoke:ollama # optional — skips if Ollama/peers unavailable
Landing: https://doc-bridge.agentskit.io/
Privacy Policy
The local MCP server reads only the project selected through doc-bridge.config.json. It does not require an API key, send project data to AgentsKit, or collect telemetry. Its MCP tools are read-only except docbridge.proposals, which can save a review artifact under .doc-bridge/ and record enrichment approve/reject decisions; no MCP tool edits documentation or source files or applies remediations. See the complete Privacy Policy for accessed paths, use, storage, sharing, retention, optional integrations, and contact information.
Doc Bridge MCP questions
How do I add Doc Bridge MCP to Claude Code?
Run claude mcp add doc-bridge -- npx -y @agentskit/doc-bridge in your terminal. Add --scope user to make it available in every project.
How do I add Doc Bridge MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does Doc Bridge require an LLM or API key to function?
No, the core functionality works without any LLM or API key.
What kind of documentation can Doc Bridge process?
It can turn Fumadocs, Docusaurus, markdown, and ownership docs into structured agent handoffs.
Can Doc Bridge help with documentation quality?
Yes, it can audit documentation by comparing declared ownership with the observed project graph to find missing coverage or stale relations.