UI2API

Turn any site you use into AI tools — analyze a website once, then generate a per-site MCP or ACP server so your AI agent can drive it by calling tools.

UI2API analyzes a website once (instrumenting its in-page JS calls, network calls, and DOM interactions), captures the site's real action recipes, and generates a per-site MCP / ACP server so an AI agent can drive the site by calling tools like send_prompt(text) instead of screen-reading and clicking buttons.

Why

Today AI agents interact with websites the way humans do — navigate, locate a control, click, read the screen. That is high-friction and brittle. A site's real capabilities are a finite, structured set of actions. UI2API makes those actions first-class tools. When a site changes, re-run the analyzer and the tool surface regenerates.

It is built for the sites you are authorized to automate: your own apps, APIs you hold keys for, accessibility workflows, and personal productivity. The output is a reviewable, generated tool-server you control.

Demo

# 1. Analyze a site once — capture its real action recipes
npx ui2api analyse https://app.example.com --llm

# 2. Generate a per-site MCP server from the captured map
npx ui2api generate app.example.com

# 3. Serve it — your AI agent now calls the site as tools
npx ui2api serve app.example.com

An agent calling a generated tool:

{
  "tool": "send_prompt",
  "arguments": { "text": "Summarize this thread" }
}

UI2API executes the captured recipe against the live, origin-pinned session and returns the result — no brittle screen-scraping.

Features

• Real action recipes — the analyzer captures the exact in-page JS functions, network calls, and DOM interactions a site actually uses, so generated tools mirror the site's true behavior.
• MCP + ACP targets — emit either a Model Context Protocol server or an ACP server from the same action map.
• Agent-skill wrapper — generated servers drop in as a callable tool source for your AI agents and orchestrators.
• Cookie-session capture for auth'd sites — --login records the authenticated session cookies so tools can act on sites that require sign-in.
• LLM-assisted naming with offline fallback — --llm uses a model to produce semantic tool names and task mappings; a deterministic heuristic fallback keeps the pipeline fully offline when no model is configured.
• Trust gate — generated maps are marked trusted:false and serve refuses to run an untrusted map without an explicit --trust, so generated tools are reviewed before they can act.

Quick start

ui2api is not published to npm yet — install from source:

git clone https://github.com/MeRezaRezaei/ui2api.git
cd ui2api
npm install
npx playwright install chromium   # one-time browser download

The CLI runs via tsx (no global install needed):

# 1. Analyze a site once  (drop --llm to run fully offline)
npx tsx src/cli.ts analyse https://app.example.com --llm

# 2. Generate a per-site MCP server
npx tsx src/cli.ts generate app.example.com

# 3. Serve it — your AI agent now calls the site as tools
npx tsx src/cli.ts serve app.example.com

Then connect any MCP/ACP client to the generated server and call tools like send_prompt. Re-run analyse/generate when the site changes.

Validate your install without owning a site — these run against a local fixture and print INTEGRATION OK / X tests … pass:

npm run test:unit   # 22 unit tests
npm test            # full integration test (needs the chromium browser above)

How it works

URL ──▶ analyze (headless browser + call interception + optional LLM mapper)
        ──▶ raw captures ──▶ build action map (normalize into typed action entries)
        ──▶ action-map.json ──▶ generate ──▶ MCP/ACP server
        ──▶ serve / execute (live, origin-pinned session) ──▶ agent calls tools

• analyze loads the site in Chromium, hooks fetch/XHR/WebSocket and in-page function calls, and records the real calls while representative tasks run. --llm names and describes actions semantically; otherwise deterministic heuristics are used.
• build action map normalizes repeated captures into typed action entries with inferred parameters.
• generate compiles the action map into one MCP/ACP tool per action.
• serve / execute keeps a live, authenticated browser session and runs each tool's recipe (live-JS delegation when state is needed, request replay when a pure call suffices).

Security & trust

Generated artifacts are designed to be reviewed, not blindly trusted:

• Generated maps are written trusted:false. serve refuses to run an untrusted map unless you pass an explicit --trust.
• Replay is origin-pinned to the analyzed site and SSRF-guarded, so a generated tool can only act on the origin it was built for.
• Cookie sessions are gitignored — captured authentication is never committed.

Only use UI2API on sites you are authorized to automate. You are responsible for complying with the terms of any site or API you point it at.

What it is / what it is not

• What it is: a tool for turning sites you are authorized to use — your own properties, APIs you hold keys for, accessibility aids, personal productivity — into reviewable, generated tool-servers for your own AI agents.
• What it is not: it is not a substitute for a site's official API, and it does not grant access you do not already have. Use it only where you are permitted to automate.

LLM mapping (tool naming)

analyse --llm uses a model to turn a site's captured actions into clean snake_case tool names + descriptions. It is OpenAI-compatible, so any OpenAI-style endpoint works — including Google Gemini via its OpenAI-compatible API:

# Gemini (recommended): just set the key
export UI2API_LLM_PROVIDER=gemini
export UI2API_LLM_KEY=AIza...your-gemini-key
npx tsx src/cli.ts analyse https://app.example.com --llm

# Or any OpenAI-compatible endpoint explicitly:
export UI2API_LLM_BASE_URL=https://api.openai.com
export UI2API_LLM_KEY=sk-...
export UI2API_LLM_MODEL=gpt-4o-mini

Without these env vars, analyse still works fully offline using deterministic heuristics (no LLM required).

Using your real Chrome profile

By default UI2API launches Playwright's bundled Chromium. To analyze a site you are already logged into with your everyday Chrome, point it at your installed Chrome and profile so the session/cookies are reused:

export UI2API_CHROME=1                       # use the system Chrome
export UI2API_USER_DATA_DIR=/path/to/profile # reuse your logged-in profile
npx tsx src/cli.ts analyse https://app.example.com

• UI2API_CHROME=1 → launches the system Chrome (channel: "chrome").
• UI2API_CHROME_PATH=/path/to/chrome → use a specific Chrome/Chromium binary.
• UI2API_USER_DATA_DIR=/path → reuse an existing profile (cookies + sign-in).

Close your normal Chrome first, or copy the profile to another folder — two Chrome instances cannot share one profile directory at the same time.

Responsibility

UI2API is an automation tool. You are responsible for how you use it. Only automate sites you are authorized to use, respect each site's terms of service, and comply with applicable law. Use it at your own risk.

Docs & links

• Documentation: docs/
• License: MIT

Hub (hosted registry + plugin runtime)

UI2API can run as a small self-hosted registry + runtime: you publish generated site packages, and the Hub serves them to your AI agents as managed MCP/ACP plugin instances — no per-site server to babysit.

# Start the registry + operator UI on http://localhost:8787
UI2API_HUB_TOKEN=op-secret npx ui2api hub --port 8787

# In another terminal: build a site's package and publish it to your hub
UI2API_HUB_TOKEN=op-secret npx ui2api hub publish app.example.com

# ...optionally also push it to the public community mirror (ui2api-registry)
UI2API_HUB_TOKEN=op-secret npx ui2api hub publish app.example.com --mirror

# Serve a registered package as a live MCP plugin your agent can call
npx ui2api hub run app.example.com          # stdio MCP
npx ui2api hub run app.example.com --acp    # ACP JSON-RPC on :8788

• Storage is the filesystem (data/registry.json + data/pkgs/<name>/<version>.json) — backup = copy the folder. No database.
• Publish (PUT /api/packages) requires UI2API_HUB_TOKEN and runs the validator on every push; invalid packages are rejected.
• Trust — packages start unreviewed; the operator marks them reviewed from the UI or API. The Hub's resolve path proxies (read-only) the ui2api-registry mirror on a miss.
• Plugins are loaded through the allow-listed Ui2ApiContext — a plugin can only use the abilities the host grants (analyse, SSRF-guarded replay/fetch, page-scoped call, session, dom). It never receives launchBrowser, generate, or raw filesystem access.
• Management UI at GET / lists packages with trust badges, a publish form, and a review button.

Only publish and run sites you are authorized to automate. See Responsibility.