// ❌ Model hallucinates — Express 4 syntax, but you have Express 5 installed
import bodyParser from 'body-parser';
app.use(bodyParser.json());

// ❌ Wrong API — Zod v3 pattern, but Zod v4 changed the API
const schema = z.object({ name: z.string() });
schema.parse(data); // Zod v4 requires schema.parse({...}) with options

npm registry → GitHub .ts (JSDoc) → npm tarball (.d.ts) → DefinitelyTyped (@types/)

┌──────────────────┐       ┌──────────────────────────────────────────────┐
│  AI Coding Agent │ ◄──── │          ts-docs-mcp                         │
│  (Cursor, Claude │ MCP   │   (MCP Server via stdio)                     │
│   Code, etc.)    │       │                                              │
└──────────────────┘       │  get_package_docs("zod")                     │
         │                  │    ↓                                        │
         │   "Here is the  │  1. npm registry → package metadata          │
         │   full API      │  2. GitHub raw → JSDoc from .ts source       │
         │   documentation"│  3. BFS re-export resolution (parallel)      │
         ▼                  │  4. npm tarball → .d.ts parsing (no JSDoc?) │
  Writes correct code       │  5. @types/{name} fallback (JS-only)        │
                            │  6. Merge + dedup → Markdown                │
                            │  7. XDG cache (24h TTL)                     │
                            └──────────────────────────────────────────────┘

# Latest version
get_package_docs("zod")

# Specific version
get_package_docs("zod", version="3.23.8")

# Subpath export (e.g. zod/v4/classic)
get_package_docs("zod", subpath="v4/classic")

# Query a specific symbol
get_package_docs("zod", query="transform")

GitHub .ts (JSDoc + declarations)
  → BFS re-export resolution (depth=2, concurrency=5)
    → merge: GitHub .d.ts (from tarball, with re-export following)
      → if 0 symbols: DefinitelyTyped (@types/{name})
        → merge all results, dedup by name (GitHub takes priority)

## findByEmail (function)
> Find a user by their email address.
> @param email — The email to search for
> @returns The user object or null

```typescript
export function findByEmail(email: string, includeDeleted?: boolean): User | null;

Full signatures, no truncation. `@param`, `@returns`, `@deprecated`, `@example` are preserved.

### Cache

Documentation is cached in `~/.cache/ts-docs-mcp/` (XDG-compatible), keyed by `package@version`. TTL is 24 hours. Old entries are cleaned up after 7 days.

---

## Usage

### Quick start

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "ts-docs-mcp": {
      "command": "npx",
      "args": ["-y", "ts-docs-mcp"]
    }
  }
}

You → "Show me the axios API"
Agent → calls get_package_docs("axios")
     → gets 83 symbols: types, interfaces, classes, functions

You → "How do I use Zod's transform method?"
Agent → calls get_package_docs("zod", query="transform")
     → gets ZodEffects.transform with full signature + JSDoc

git clone https://git.827482.xyz/xvantz/ts-docs-mcp.git
cd ts-docs-mcp
npm install
npm run build
npm test          # 43 unit tests (5 test files)
npm run test:integration  # network tests (skipped in CI)

src/
├── registry.ts   — npm package metadata + HTTP helpers
├── github.ts     — GitHub raw source fetching (BFS, parallel)
├── tarball.ts    — .d.ts extraction from tarball + DefinitelyTyped
├── parser.ts     — Two-phase JSDoc + declaration parser
├── format.ts     — Markdown output (summary + detail)
├── throttle.ts   — Per-endpoint token-bucket rate limiter
├── cache.ts      — XDG file cache with 24h TTL
├── types.ts      — PublicSymbol, PackageInfo interfaces
└── index.ts      — MCP server (thin handler)