<p align="center"> <img src="assets/banner.png" alt="DocOrbit Banner" width="100%" style="border-radius: 8px;" /> </p> <p align="center"> <img src="assets/logo.png" alt="DocOrbit Logo" width="80" height="80" style="border-radius: 16px;" /> </p>

DocOrbit

<p align="center"> <strong>Version-aware documentation intelligence for coding agents.</strong> </p> <p align="center"> DocOrbit discovers authoritative documentation, resolves it against your project's dependency versions, retrieves task-specific context, and verifies generated code against documentation contracts. </p> <p align="center"> <a href="https://www.npmjs.com/package/docorbit"><img src="https://img.shields.io/npm/v/docorbit?color=339933&style=flat-square" alt="npm version" /></a> <a href="https://www.npmjs.com/package/docorbit"><img src="https://img.shields.io/npm/dm/docorbit?color=blue&style=flat-square" alt="npm downloads" /></a> <a href="https://glama.ai/mcp/servers/HakashiKatake/docorbit"><img src="https://glama.ai/mcp/servers/HakashiKatake/docorbit/badges/score.svg" alt="docorbit MCP server score" /></a> <a href="https://github.com/HakashiKatake/docorbit/actions"><img src="https://img.shields.io/badge/tests-143%20passing-brightgreen.svg?style=flat-square" alt="tests passing" /></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D22.5.0-black.svg?style=flat-square" alt="Node.js version" /></a> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-15%20tools-blueviolet.svg?style=flat-square" alt="Model Context Protocol" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license MIT" /></a> </p> <p align="center"> <a href="https://glama.ai/mcp/servers/HakashiKatake/docorbit"> <img src="https://glama.ai/mcp/servers/HakashiKatake/docorbit/badges/card.svg" alt="docorbit MCP server card" /> </a> </p> <p align="center"> <a href="#quick-start">Quick Start</a> • <a href="#project-scoped-storage">Project vs Global Storage</a> • <a href="#why-docorbit">Why DocOrbit?</a> • <a href="#see-it-in-action">See It in Action</a> • <a href="#mcp-integration">MCP Integration</a> • <a href="#mcp-tools">15 MCP Tools</a> • <a href="#benchmarks">Benchmarks</a> • <a href="#code-verification">Code Verification</a> • <a href="#security-model">Security</a> • <a href="docs/architecture.md">Architecture</a> </p>

---

  Authoritative Sources (llms.txt / OpenAPI / Markdown / HTML)
                            │
                            ▼
              ┌───────────────────────────┐
              │  Discovery & Ingestion    │ ◄── SSRF Guard & Security Annotations
              └─────────────┬─────────────┘
                            │
                            ▼
              ┌───────────────────────────┐
              │    Version Intelligence   │ ◄── Scans package.json / cargo.lock / go.mod
              └─────────────┬─────────────┘
                            │
                            ▼
              ┌───────────────────────────┐
              │  Structured Knowledge DB  │ ◄── Project-local SQLite: <projectRoot>/.docorbit/
              └─────────────┬─────────────┘
                            │
              ┌─────────────┴─────────────┐
              ▼                           ▼
    ┌───────────────────┐       ┌───────────────────┐
    │  MCP Server Loop  │       │   CLI Developer   │
    │  (15 Tools / Stdio)│       │   Commands        │
    └─────────┬─────────┘       └─────────┬─────────┘
              │                           │
              ▼                           ▼
    ┌───────────────────┐       ┌───────────────────┐
    │  Coding Agents    │       │ AST Verification  │
    │  Claude / Cursor  │ ────► │ & Contract Check  │
    └───────────────────┘       └───────────────────┘

---

Quick Start

DocOrbit requires Node.js ≥ 22.5.0 and has zero external runtime dependencies.

[!IMPORTANT] Project-Based by Default: If you do not specify any flags, DocOrbit always defaults to project-based storage (<projectRoot>/.docorbit/docorbit.db). When you delete or branch a project, its documentation cache is isolated and cleans up automatically — zero orphaned files, zero global disk bloat, and zero cross-project version collisions.

1. Run via npx (Zero Installation)

# View all developer commands
npx docorbit --help

# Ingest and index documentation into project-local SQLite (default)
npx docorbit add https://nextjs.org/docs/14/app/api-reference/file-conventions/route

# Or explicitly pass -p to skip prompts and ensure project-local storage
npx docorbit add https://nextjs.org/docs/14/app/api-reference/file-conventions/route -p

# Query version-aware context within a strict token budget
npx docorbit context "How do I implement dynamic route params in Next.js 14?" --tokens 2000

2. Connect to Your Coding Agent (MCP)

When started by an agent (Cursor, Claude Desktop, Windsurf, Zed), DocOrbit automatically resolves to the active project workspace's SQLite database (.docorbit/docorbit.db):

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "docorbit": {
      "command": "npx",
      "args": ["-y", "docorbit", "mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "docorbit": {
      "command": "npx",
      "args": ["-y", "docorbit", "mcp"]
    }
  }
}

Claude Code (Terminal CLI)

claude mcp add docorbit -- npx -y docorbit mcp

DocOrbit detects when standard input is a machine pipe and starts the MCP stdio transport automatically in project-local mode. If you prefer a shared user-wide store across all projects, pass -g: ["-y", "docorbit", "mcp", "-g"].

3. How to Work with DocOrbit in Your Prompts

Once mounted, you never need to manually copy-paste documentation pages into your agent chat. Simply give your agent the official documentation link and tell it to use DocOrbit:

I want to setup stripe in my app, the link of stripe docs: https://docs.stripe.com/payments/checkout
use docorbit to set it up.

What DocOrbit does behind the scenes:

1. Tree Crawling & SQLite FTS5 Indexing: The agent automatically invokes docorbit.ingest_doc({ url: "https://docs.stripe.com/payments/checkout" }). DocOrbit crawls the documentation with SSRF protection and indexes endpoints and types in ~24ms.
2. Context Assembly (Zero JSON Bloat): The agent calls docorbit.get_implementation_context(...) and receives 412 tokens of clean, pure GitHub Markdown grounded in active API contracts.
3. AST Contract Verification: The agent calls docorbit.check_api(...) to verify code against AST contracts before writing to disk, preventing deprecated methods (such as legacy stripe.charges.create) and runtime parameter crashes.

---

Project-Scoped Storage & Flags

DocOrbit gives developers full control over where documentation is persisted:

| Storage Mode | Location | Flag | Best Used For | | :--- | :--- | :---: | :--- | | Project-Local (Default) | <projectRoot>/.docorbit/docorbit.db | -p, --project | Default for all workflows. Zero disk leaks. Clean git isolation (.gitignore). Deletes when project is deleted. No version collisions between projects. | | Global Store | ~/.docorbit/docorbit.db | -g, --global | Shared documentation across multiple ad-hoc scripts or global toolchains without repository workspaces. |

Interactive Selection Prompt

When running docorbit init or docorbit add <url> in an interactive terminal without flags on a new project, DocOrbit will ask:

? Where would you like to store DocOrbit documentation?
  1) Project-local (.docorbit/ in project root) [Recommended - zero disk leak]
  2) Global (~/.docorbit/ in user home directory)
  Tip: Pass -p / --project or -g / --global to skip this question in future.

Select storage location [1/2] (default: 1): 

• Pressing Enter directly accepts the default ([1] Project-local).
• Non-interactive environments (CI, agents, pipes, scripts, --json) automatically default to Project-local without hanging.
• Passing -p or -g immediately selects that target and skips the prompt.

---

Why DocOrbit?

AI coding agents (Claude Code, Cursor, Windsurf, Devin) frequently produce broken code not because models lack reasoning, but because the documentation context they receive is flawed:

• Wrong Version Collisions: An agent in a Next.js 14 codebase gets fed Next.js 15 documentation and uses await params, breaking production builds.
• Bloated HTML: Generic scrapers dump navigation headers, footers, cookie banners, and script tags, wasting 70%+ of the agent's context window.
• Missing API Contracts: Models guess query parameters and request bodies because documentation lack structured OpenAPI/Swagger schemas.
• Stale Examples & Deprecations: Agents call deprecated endpoints (e.g. Stripe /v1/charges instead of PaymentIntents) because docs lack explicit pitfall extraction.
• Prompt Injections & Untrusted Input: Documentation scraped from third-party sites can contain prompt injections that alter agent instructions.

Documentation Retrieval Approaches

| Capability | Official Docs Fetch | Web Scraper (e.g. Firecrawl) | Generic Retrieval (e.g. Context7) | DocOrbit | | :--- | :---: | :---: | :---: | :---: | | Machine-readable Discovery (llms.txt, OpenAPI) | ❌ | ❌ | ⚠️ Manual / Centralized | ✅ Automatic multi-source | | Project Lockfile & SemVer Resolution | ❌ | ❌ | ❌ | ✅ 8 Ecosystems (docs.lock) | | Structured OpenAPI Endpoints | ❌ | ❌ | ❌ | ✅ Full parameters & schemas | | Indivisible Code Fence Chunking | ❌ | ❌ | ⚠️ Naive character split | ✅ Semantic AST chunking | | Pitfall & Deprecation Extraction | ❌ | ❌ | ❌ | ✅ Explicit gotcha indexing | | Closed-Loop Code Verification | ❌ | ❌ | ❌ | ✅ AST check_api verifier | | Untrusted Content Tagging & SSRF Defense | ❌ | ❌ | ❌ | ✅ Strict isolation boundary | | Local Offline-First SQLite FTS5 Cache | ❌ | ❌ | ❌ | ✅ Fast local database |

---

See It in Action

A developer in a Next.js 14 project asks their coding agent:

"How should I access dynamic route params in a Next.js 14 route handler?"

sequenceDiagram
    autonumber
    actor User
    participant Agent as Coding Agent (Claude/Cursor)
    participant DocOrbit as DocOrbit MCP
    participant Code as Project Workspace

    User->>Agent: "Implement GET handler with route params"
    Agent->>DocOrbit: get_implementation_context({ task: "Next.js dynamic route params", project: "." })
    DocOrbit->>Code: Scans package.json → detects next@14.2.0
    DocOrbit->>DocOrbit: Resolves v14 doc branch & penalizes v15 breaking changes
    DocOrbit-->>Agent: Returns v14 verified snippet + explicit warning: "Do NOT await params in v14"
    Agent->>Agent: Generates route.ts (const id = params.id)
    Agent->>DocOrbit: check_api({ code: "const id = params.id", framework: "next" })
    DocOrbit-->>Agent: { status: "verified" }
    Agent-->>User: Correct Next.js 14 implementation with zero deprecation errors

If the agent had erroneously generated Next.js 15 syntax:

export async function GET(request: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params; // ❌ Invalid in Next.js 14
  return Response.json({ id });
}

DocOrbit's check_api tool immediately flags the mismatch:

{
  "status": "mismatch",
  "severity": "error",
  "message": "Next.js 15 asynchronous route params used in a Next.js 14 workspace.",
  "rule": "version_syntax_conflict",
  "provenance": {
    "sourceUrl": "https://nextjs.org/docs/14/app/api-reference/file-conventions/route",
    "authority": "official",
    "docVersion": "v14"
  }
}

---

Core Capabilities

1