DocOrbit

  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.

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.

Related MCP server: Evergreen

Project-Scoped Storage & Flags

DocOrbit gives developers full control over where documentation is persisted:

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

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. Documentation Intelligence

• Autonomous Discovery: Probes target domains and ranks available formats: llms-full.txt > openapi.json > llms.txt > skill.md > Markdown > HTML sitemaps.

• Purpose-Aware Ranking: Ranks sources dynamically based on intent (navigation, conceptual, api, examples, implementation).

• Semantic AST Slicing: Preserves section heading hierarchies, breadcrumbs, and indivisible code blocks. Admonitions and warnings remain bound to their host sections.

2. Version Intelligence

• Workspace Manifest Scanner: Scans project files across 8 ecosystems (npm, cargo, go, pypi, composer, rubygems, pub, maven).

• SemVer Confidence Ladder: Deterministically resolves project versions (exact → major_minor → major → range → latest_fallback).

• Deterministic docs.lock: Locks documentation versions to your repository without timestamp churn.

3. Implementation Knowledge

• OpenAPI 3.x & Swagger 2.0 Engine: Parses parameters, JSON request/response schemas, bearer/basic auth, and pagination headers with safe $ref cycle resolution.

• Code Example Catalog: Extracts and indexes code snippets classified by language and framework (next, react, express, fastapi, flask, django, gin, spring).

• Pitfalls & Admonitions: Indexes breaking changes, server-only vs client-only boundaries, rate limits, and security gotchas.

• Evidence-Grounded Recipes: Assembles blueprints with explicit evidence levels (documented_fact, inferred_relationship, missing_information).

4. Closed-Loop Verification

• Static AST Code Verifier: Evaluates generated JavaScript, TypeScript, Python, and cURL against indexed schemas without calling an LLM.

• Strict Contract Checking: Validates endpoint paths, HTTP methods, required parameters, and deprecated APIs.

• Ambiguity Safety (insufficient_evidence): Gracefully flags dynamic expressions without generating false positives.

5. Change Intelligence

• Documentation Diffing (diff_docs): Compares documentation snapshots to detect added, modified, removed, and deprecated endpoints.

• Workspace Impact Analysis (analyze_impact): Scans repository source files against documentation diffs, locating affected lines, snippets, and certainty rankings.

6. Agent Integration

• 15 MCP Tools: Complete Model Context Protocol suite over stdio and Streamable HTTP.

• Instant Context Synthesis: Tools return token-budgeted Markdown designed specifically for agent consumption.

• Deterministic Exporters: Generates AGENTS.md, CLAUDE.md, skill.md, llms.txt, and docs-map.md.

MCP Tools

DocOrbit exposes 15 agent-native tools organized by workflow stage:

                  DocOrbit 15-Tool Agent Suite
                               │
       ┌───────────────────────┼───────────────────────┐
       ▼                       ▼                       ▼
  Loop Starter         Task Context & Recipe       Verification
  ingest_doc           get_implementation_context  check_api
                               │
       ┌───────────────────────┼───────────────────────┐
       ▼                       ▼                       ▼
 API Intelligence       Deep Retrieval          Change & Exports
 find_api               search_docs             diff_docs
 find_example           get_doc                 analyze_impact
 find_pitfall           get_version             get_documentation_map
 find_recipe            list_sources            export_agent_context

Ingestion & Loop Starter

Context & Implementation Blueprints

API & Knowledge Intelligence

Verification & Change Intelligence

Retrieval & Search

Agent Exports & Structure

Performance

DocOrbit is built natively in Node.js 24 with node:sqlite and zero external dependencies. Cold boot takes < 40ms.

Scaling Performance (From Repository Test Suite)

Measured on SQLite in WAL mode via automated benchmarks (tests/integration/retrieval-benchmark.test.ts and tests/integration/benchmark.test.ts):

Empirical Benchmark (17-Task Suite)

DocOrbit includes a reproducible, auditable benchmark suite across 17 tasks covering 5 ecosystems (npm, pypi, cargo, go, composer):

• 4 Training Tasks: Used for algorithm calibration.

• 6 Held-Out Evaluation Tasks: Real-world library tasks (Next.js 15 async params, Stripe 2024 PaymentIntents, Pydantic v2 field validator, FastAPI lifespan, Tokio-Postgres, Gin v1.9).

• 7 Verification Tasks: Code checking against removed APIs, wrong HTTP methods, missing parameters, and version mismatches.

Measured System Metrics

All runs save raw JSON execution artifacts to eval-results/raw/ for independent verification:

¹ Official Docs Fetch is direct HTTPS retrieval from known official documentation URLs (not an open-ended search engine). Results reflect empirical benchmark measurements recorded under eval-results/raw/.

Code Verification

DocOrbit provides closed-loop AST verification via check_api without calling an LLM:

  Agent-Generated Code
           │
           ▼
    ┌───────────────┐
    │  AST Parser   │ ◄── JS/TS, Python, cURL extractor
    └──────┬────────┘
           │
           ▼
    ┌───────────────┐
    │ Schema Verifier│ ◄── Evaluates against SQLite OpenAPI schemas & version rules
    └──────┬────────┘
           │
           ├──► [VERIFIED]              (Parameters, method, endpoint, and version match)
           ├──► [WARNING]               (Deprecated endpoint; alternative suggested)
           ├──► [MISMATCH]              (Removed API, missing required fields, version conflict)
           └──► [INSUFFICIENT_EVIDENCE] (Dynamic/computed expression; safe non-blocking fallback)

Example 1: Removed API Endpoint

// Agent calls removed Stripe Charges endpoint
const res = await fetch('https://api.stripe.com/v1/charges', { method: 'POST' });

Result:

{
  "status": "mismatch",
  "severity": "error",
  "message": "Endpoint \"POST /v1/charges\" was removed in the active API version.",
  "rule": "endpoint_removed",
  "provenance": { "sourceUrl": "https://docs.stripe.com/api", "docVersion": "2024-10-28" }
}

Example 2: Ambiguous Dynamic Expressions

When code relies on runtime variables:

const url = getApiUrl();
fetch(url, { method: 'POST' });

DocOrbit returns status: "insufficient_evidence", avoiding false positives on dynamic or unresolvable AST nodes.

Security Model

Documentation ingested from external websites must be treated as untrusted input. DocOrbit isolates external content through multiple defense layers:

1. Untrusted Provenance Tagging: All retrieved documentation carries explicit untrusted: true flags in metadata. Security boundaries are never stripped.

2. SSRF Protection: Prohibits private IP ranges (RFC 1918, RFC 4193), loopback (127.0.0.1), link-local, and cloud metadata endpoints (169.254.169.254) on all requests and redirect hops.

3. Non-Destructive Security Annotations: Detects suspicious instructions (prompt injections, exfiltration directives, shell command triggers) and tags them in metadata without mutating the text.

4. Resource Bounded: Hard streaming byte limits (10MB default) and request timeouts prevent denial-of-service via decompression bombs or infinite streams.

Local Web Dashboard

DocOrbit includes an embedded local web dashboard powered by native node:http (port 3737) with zero browser build steps:

# Launch dashboard on http://127.0.0.1:3737/
npx docorbit dashboard

• Visual Health: Status of indexed sources, snapshots, chunks, and token footprints.

• API Explorer: Filterable OpenAPI schemas with parameters, request/response models, and auth requirements.

• Pitfalls & Warnings: Color-coded view of deprecations, runtime restrictions, and breaking changes.

• Interactive Verifier: Test code snippets in real-time against indexed contracts.

• Documentation Map: Interactive token hierarchy tree.

• Export Center: One-click preview and export of AGENTS.md, CLAUDE.md, and skill.md.

CLI Reference

# Workspace & Versioning
docorbit init [dir] [-p|-g]  # Scan project dependencies and generate docs.lock
docorbit update [pkg] [-p|-g]# Selectively or globally refresh documentation versions

# Ingestion & Discovery
docorbit inspect <url>       # Probe domain for machine-readable specifications
docorbit add <url> [-p|-g]   # Ingest, chunk, and index documentation into SQLite

# Search & Retrieval
docorbit search "<q>" [-p|-g]# Hybrid FTS5 search across documentation chunks
docorbit context "<t>" [-p|-g] Pack token-budgeted context for coding agents

# API & Implementation Knowledge
docorbit api "<query>" [-p|-g] Inspect structured OpenAPI endpoints
docorbit examples "<t>" [-p] # Filter code examples by framework and language
docorbit pitfalls "<t>" [-p] # Inspect deprecations and runtime traps
docorbit recipes "<g>" [-p]  # Assemble evidence-grounded blueprints

# Verification & Change Intelligence
docorbit verify <code> [-p]  # Verify code against indexed schemas
docorbit diff [source] [-p]  # Compare documentation versions and snapshots
docorbit impact [source] [-p]# Scan workspace for breaking changes

# Dashboard & Exports
docorbit dashboard [-p|-g]   # Launch local inspection UI (alias: ui)
docorbit export [fmt] [-p|-g]# Export AGENTS.md, CLAUDE.md, skill.md, llms.txt, docs-map.md
docorbit mcp [-p|-g]         # Start Model Context Protocol server (stdio / HTTP)

CLI Storage Flags

Repository Structure

docorbit/
├── bin/
│   └── docorbit.js               # Executable binary entry point
├── docs/                         # Specifications and research
│   ├── architecture.md           # Deep architectural specification
│   ├── competitive-analysis.md   # Ecosystem analysis vs Context7, Firecrawl, etc.
│   └── product-spec.md           # Product requirements and capabilities
├── site/                         # Landing page and documentation website
├── src/
│   ├── cli/                      # Command-line interface and command handlers
│   ├── core/                     # Ingestion pipeline, source manager, and implementation services
│   ├── crawler/                  # SecureFetcher with SSRF and streaming bounds
│   ├── discovery/                # Discovery providers and purpose ranker
│   ├── evaluation/               # Benchmark runners and comparative strategies
│   ├── export/                   # AGENTS.md, CLAUDE.md, and skill.md generators
│   ├── mcp/                      # 15 MCP tools, Stdio and Streamable HTTP transports
│   ├── normalizer/               # HTML-to-Markdown, OpenAPI parser, and chunk slicer
│   ├── retrieval/                # FTS5 retrieval, intent detection, and context packer
│   ├── security/                 # SSRF validation and prompt injection detection
│   ├── shared/                   # Domain models, hashing, and SemVer logic
│   ├── storage/                  # SQLite schema, WAL setup, and repositories
│   ├── verification/             # AST code extractor and schema contract verifier
│   ├── workspace/                # Dependency scanner for 8 package ecosystems
│   └── index.ts                  # Public programmatic SDK exports
└── tests/
    ├── fixtures/                 # In-memory test servers (Fixtures A–J)
    ├── integration/              # Real-world benchmark and transport suites
    └── unit/                     # Unit test suites across all components

Current Status

• Documentation Ingestion: Autonomous discovery (llms.txt, OpenAPI, Sitemap, Markdown, Skill)

• Semantic Retrieval: SQLite FTS5 with section breadcrumbs and indivisible code fences

• Version Intelligence: Project awareness across 8 ecosystems and deterministic docs.lock

• API & Implementation Knowledge: OpenAPI 3.x parser, code examples, pitfalls, and recipes

• Agent MCP Integration: 15 MCP tools over stdio and Streamable HTTP

• AST Code Verification: Schema and parameter contract checking (check_api)

• Documentation Diffing & Impact: Breaking change detection and workspace scanning

• Local Web Dashboard: Zero-dependency UI for interactive verification and exploration

• Empirical Benchmark: Auditable 17-task comparative evaluation suite

License

MIT License. See LICENSE for details.