unapi-mcp

Unwrap any website's hidden Shadow APIs into a typed Python/TypeScript SDK, OpenAPI 3.1 spec, Auth Dependency Graph, Security Audit, and Local Mock + MCP Server in one command.

Why unapi-mcp?

Every modern website talks to itself using undocumented internal JSON and GraphQL endpoints (Shadow APIs). Yet when developers want an AI agent (Claude Code, Cursor, OpenCode) to interact with a web portal, they usually reach for headless browsers (Playwright MCP, browser-use) that take 45+ seconds and burn thousands of tokens parsing DOM trees.

Even worse, basic network recorders just dump raw endpoints without telling you where the auth tokens came from, whether the API leaks PII, or letting you test offline.

unapi-mcp goes far beyond simple network capture:

1. Automatic Auth & Token Dependency Chain Tracer: Automatically traces how a sessionToken or csrfToken returned in the JSON body of Request A ($.sessionToken) is injected into the Authorization or x-csrf-token header of Request B and C.

2. Shadow API Security & PII Auditor (unapi-mcp audit): Scans every captured endpoint for unauthenticated state-mutations (POST/DELETE), plaintext email/PII leaks, credentials leaked in URL query strings, and wildcard CORS misconfigurations.

3. Instant Zero-Config Local Mock Server (unapi-mcp mock): Spins up a local HTTP server (http://127.0.0.1:4010) that replays the exact synthesized routes and captured JSON payloads so you and your AI agent can build and test against any website's API offline without hitting production rate limits.

4. Full Code & Spec Compiler (unapi-mcp export): Generates standalone, zero-dependency Python SDKs, TypeScript SDKs, OpenAPI 3.1 specs, and native Model Context Protocol (MCP) tools.

Related MCP server: mcp-network-analyzer

Quick Comparison

How it works

• Capture. Connects to Chrome over the DevTools Protocol WebSocket (Network.requestWillBeSent and Network.getResponseBody) or parses a local .har file. Requests to ad networks, analytics trackers, fonts, stylesheets, and images are dropped immediately; only XHR, Fetch, JSON, and GraphQL exchanges are kept.

• Synthesize. Concrete URLs like /api/v1/flights/98412/seats are collapsed into parameterized route patterns (/api/v1/flights/{flightId}/seats). GraphQL POST bodies are split by operationName, and request/response payloads are recursively inspected to build JSON Schemas.

• Trace. The synthesizer walks captured exchanges in chronological order. When a high-entropy token returned in an earlier JSON response body (for example, $.sessionToken or $.csrfToken) reappears inside a later request's Authorization or x-csrf-token header, unapi-mcp records the dependency link so you and your agent know which bootstrap endpoint feeds downstream calls.

• Call or replay. In MCP mode (unapi-mcp mcp), each endpoint becomes a native tool executed with Node's fetch, injecting headers or environment credentials (<SITE>_AUTH_TOKEN, <SITE>_COOKIE) automatically. In mock mode (unapi-mcp mock), a local server emulates the remote API so you can test integrations offline without hitting production rate limits.

What's included

Pre-built catalogs and synthesis modules ready out of the box:

• acme-flights (via unapi-mcp demo): multi-step session login, flight search, seat map lookup, and GraphQL price alert mutation

• hackernews (sites/hackernews.json): top stories feed and item detail lookups

• github (sites/github-public.json): repository metadata lookup by owner and repo

• export compilers: zero-dependency TypeScript client (ts), Python urllib client (python), and OpenAPI 3.1 JSON (openapi)

• audit scanner: checks captured traffic for unauthenticated state mutations, tokens leaked in URL query strings, plaintext email/PII exposure, sensitive response keys, and wildcard CORS headers

• mock server: local HTTP server that matches parameterized routes ({itemId}, {flightId}) and replays captured status codes and JSON bodies offline

Catalogs are stored as plain JSON in ~/.unapi-mcp/catalogs/. Run unapi-mcp list to see all saved sites and their MCP tool names.

Quickstart in 30 seconds

# 1. Clone and build
git clone https://github.com/mohdxaid/unapi-mcp.git
cd unapi-mcp
npm install
npm run build

# 2. Run the self-contained demo (synthesizes endpoints + traces auth chain + runs security audit)
npx unapi-mcp demo

# 3. Inspect the Auth Dependency Graph & Shadow API Security Report
npx unapi-mcp audit acme-flights

# 4. Spin up a local offline Mock Server of the captured website API on port 4010
npx unapi-mcp mock acme-flights --port 4010

# 5. Export a standalone Python or TypeScript SDK, or OpenAPI 3.1 spec
npx unapi-mcp export acme-flights --format python
npx unapi-mcp export acme-flights --format ts
npx unapi-mcp export acme-flights --format openapi

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                    1. Traffic Ingestion Layer                           │
│  • Live Chrome DevTools WebSocket (127.0.0.1:9222)  [`src/recorder.ts`] │
│  • Offline Browser HAR File Importer (`import-har`)                     │
│  • Telemetry, Ad-Domain & Static Asset Noise Filter (95% reduction)     │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                  2. Synthesis & Intelligence Engine                     │
│  • Dynamic Path Parameterizer (`/orders/8492` ➔ `/orders/{orderId}`)    │
│  • Recursive JSON Schema Inferrer & GraphQL Operation Unwrapper         │
│  • Multi-Step Auth Token Dependency Tracer (`traceTokenDependencies`)│
│  • Shadow API Security & PII Auditor (`auditEndpointSecurity`)       │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    ▼
┌───────────────────┬─────────────────────────────────┬───────────────────┐
│ 3A. Native MCP    │ 3B. Offline Local Mock Server   │ 3C. SDK Compilers │
│ Stdio Server for  │ Replays routes & payloads on    │ • OpenAPI 3.1     │
│ Claude / Cursor   │ `http://127.0.0.1:4010`         │ • TypeScript SDK  │
│ (`mcp-server.ts`) │ (`src/mock-server.ts`)          │ • Python Client   │
└───────────────────┴─────────────────────────────────┴───────────────────┘

Repository layout

• .claude-plugin/ & skills/unapi-mcp/ — Native Claude Code plugin manifest & agent skill definition.

• .github/workflows/ — Automated CI matrix testing Node 20, 22, and 24 across Ubuntu and macOS.

• bench/ — Latency & throughput benchmarks (npm run bench).

• docs/ — Deep-dive architecture and Shadow API Security Auditor documentation.

• examples/ - Sample generated TypeScript & Python SDK clients.

• sites/ — Pre-built API catalogs (hackernews.json, github-public.json).

• src/ — TypeScript source (recorder.ts, synthesizer.ts, mock-server.ts, mcp-server.ts, cli.ts).

• test/ — Automated test suite (npm test).

CLI reference

unapi-mcp capture [url] [--launch] [--port 9222] [--duration 30] [--name <site>]
unapi-mcp import-har <file.har> [--name <site>]
unapi-mcp demo
unapi-mcp list
unapi-mcp audit <site>
unapi-mcp mock <site> [--port 4010]
unapi-mcp export <site> [--format openapi|ts|python] [--out <file>]
unapi-mcp setup [--client claude|cursor]
unapi-mcp doctor [--port 9222]
unapi-mcp mcp [--catalog <file.json>]

Capture Any Live Website or .har Recording

# Auto-launch Chrome with remote debugging and capture 30 seconds of clicks
npx unapi-mcp capture https://news.ycombinator.com --launch --duration 30 --name hn

# Or import any network recording saved from Chrome DevTools ("Save all as HAR with content")
npx unapi-mcp import-har ./portal-recording.har --name my-portal

Connect to Claude Code, Cursor, or OpenCode

npx unapi-mcp setup --client claude
npx unapi-mcp setup --client cursor

License

MIT Licenced.

unapi-mcp