npx agentoverflow-mcp          # drop into Claude Code or Cursor in 60 seconds

Without AgentOverflow                   With AgentOverflow
─────────────────────────────────────   ───────────────────────────────────
agent → load MDN fetch page             agent → GET /api/docs/fetch/fetch
        ↓                                       ↓
   ~12,000 tokens of HTML,              DOC|n~fetch;sig~fetch(input,init?)
   navigation, ads, prose,              ->Promise<Response>;
   examples you didn't need,            p~input:str:req,init:obj:opt;
   and the agent still might            r~Promise<Response>;v~browser
   hallucinate the exact sig
   it needed.                           85 tokens. Exact signature. Done.
                                        X-AO-Tokens: 85  (141× savings)

curl -X POST https://ao-registry.fly.dev/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name":"my-workspace","email":"you@example.com"}'
# → { "key": "ao_...", "plan": "free" }

// ~/.claude/mcp.json  or Cursor MCP settings
{
  "mcpServers": {
    "agentoverflow": {
      "command": "npx",
      "args": ["agentoverflow-mcp"],
      "env": { "AO_KEY": "ao_your_key_here" }
    }
  }
}

> auto_ingest          ← indexes every dep in package.json + requirements.txt
> search "retry fetch with backoff"
> get_doc express app.get

curl "https://ao-registry.fly.dev/api/docs/express/app.get?format=dense" \
  -H "X-API-Key: ao_..."
# → DOC|n~app.get;sig~app.get(path,...handlers)->app;...  (85 tokens)

# TypeScript SDK → every exported symbol from the .d.ts
curl -X POST https://ao-registry.fly.dev/api/ingest \
  -H "X-API-Key: ao_..." -H "Content-Type: application/json" \
  -d '{"targets":["ts:@acme/internal-sdk"],"private":true}'

# OpenAPI spec → every endpoint as a queryable record
curl -X POST https://ao-registry.fly.dev/api/ingest \
  -H "X-API-Key: ao_..." \
  -d '{"targets":["openapi:https://api.acme.com/openapi.json"],"private":true}'

# Python stubs
curl -X POST https://ao-registry.fly.dev/api/ingest \
  -H "X-API-Key: ao_..." \
  -d '{"targets":["pypi:httpx","pypi:pydantic"]}'

# Auto-detect and index everything from package.json + requirements.txt (MCP)
> auto_ingest { "private": true }

# Register your repo
curl -X POST https://ao-registry.fly.dev/api/webhooks/register \
  -H "X-API-Key: ao_..." -H "Content-Type: application/json" \
  -d '{"repo":"acme/internal-sdk","targets":["ts:@acme/internal-sdk"]}'
# → { "webhookUrl": "https://ao-registry.fly.dev/api/webhooks/github" }

# Add that URL as a GitHub webhook on your repo (push events, JSON content-type)
# Every push → AgentOverflow re-crawls the .d.ts and updates all symbols.

  Your agent (Claude Code · Cursor · LangChain · any MCP client)
       │
       │  MCP tools  /  HTTP  GET /api/docs/:lib/:symbol?format=dense
       ▼
  ┌─────────────────────────────────────────────────────────┐
  │  AgentOverflow                                          │
  │  ──────────────────────────────────────────────────     │
  │  BM25Index → symbol store → serialize()                 │
  │  (ranking)    SQLite/PG     dense/json/xml/prose        │
  │                                                         │
  │  Crawlers: ts(.d.ts) · openapi · pypi(typeshed)         │
  │            npm · mdn · pyi(stdlib)                      │
  │                                                         │
  │  Auth: API keys · per-plan rate limits · Stripe         │
  │  Private docs: owner-namespaced, tenant-isolated        │
  │  GitHub webhooks: auto re-crawl on every push           │
  └─────────────────────────────────────────────────────────┘
       │
       │  85 tokens · exact signature · no hallucination
       ▼
  LLM (Anthropic · OpenAI · any provider)

# Minimal — SQLite, no auth
npm install agentoverflow && npm start

# With auth + Postgres
AO_REQUIRE_KEY=1 AO_ADMIN_TOKEN=changeme \
DATABASE_URL=postgres://user:pass@host/db npm start

# Docker
docker run -p 4317:4317 \
  -e AO_REQUIRE_KEY=1 -e AO_ADMIN_TOKEN=secret \
  -v ao_data:/data \
  ghcr.io/tatsunori-ono/agentoverflow:latest

# Then seed with public libraries
npm run crawl -- ts:express ts:zod pypi:requests openapi:https://petstore.swagger.io/v2/swagger.json

git clone https://github.com/tatsunori-ono/agentoverflow
cd agentoverflow && npm install
npm test        # ~30 tests
npm run dev     # hot-reload on :4317