OpenAct ⚡

The yt-dlp for turning any website or portal into a fast, deterministic REST API, CLI command, and AI Agent (MCP) tool.

Most websites, portals, and SaaS dashboards either don't offer a public API or lock API access behind a $50,000/year "Enterprise Plan." Meanwhile, AI browser agents ("Computer Use") take 45+ seconds, cost $0.50–$2.00 per run, and hallucinate clicks.

OpenAct takes the proven community architecture of yt-dlp and applies it to structured web data and actions:

1. Declarative .act.yaml Blueprints: A single ~40-line YAML file (with optional TypeScript hooks) defines inputs, extraction logic, output schemas, and automated verification tests.

2. 3-Tier Execution Engine with Automatic Fallback:

   • Tier 1 (http — 20–80ms): Direct JSON/REST/GraphQL replay with templated inputs and local Session Vault cookies/headers.

   • Tier 2 (extract — 50–150ms): Fast HTML parsing via Next.js/Nuxt Hydration blobs (__NEXT_DATA__), Schema.org JSON-LD (application/ld+json), OpenGraph metadata, and Cheerio CSS selectors—zero headless browser overhead.

   • Tier 3 (browser — Playwright): Full headless Chromium automation and live background XHR/Fetch JSON interception when a site requires JavaScript execution.

3. 1 Blueprint = 4 Interfaces Automatically:

   • REST API + Live OpenAPI 3.1 Spec (POST /api/v1/run/:namespace/:name)

   • Model Context Protocol (MCP) Server (openact mcp for Claude Desktop, Cursor, Windsurf, OpenHands)

   • Ergonomic CLI (openact run developer/github-trending --input language=typescript)

   • Interactive Web Studio UI (http://localhost:4100)

Built-in Community Blueprints

OpenAct ships with 12 verified blueprints across 4 categories out of the box:

Related MCP server: Kryfto

Quick Start

# 1. Install dependencies
npm install

# 2. List all installed community blueprints
npx tsx src/cli/main.ts list

# 3. Run all offline fixture tests (or add --live to test against live websites)
npx tsx src/cli/main.ts test
npx tsx src/cli/main.ts test --live

# 4. Run any blueprint from the CLI
npx tsx src/cli/main.ts run developer/github-trending --input language=typescript --input since=daily

# 5. Launch the OpenAct REST Server, OpenAPI 3.1 Spec & Web Studio UI
npm run serve
# -> Open http://localhost:4100

Reverse-Engineering New Sites in Seconds

OpenAct ships with two built-in compilers so you never have to write a blueprint from scratch:

1. Live URL Inspector (openact inspect <url>)

Automatically probes any URL for direct JSON, __NEXT_DATA__ hydration state, Schema.org JSON-LD, OpenGraph tags, and repeating DOM card/row structures, and outputs a ready-to-run .act.yaml blueprint:

npx tsx src/cli/main.ts inspect https://news.ycombinator.com --save

2. Browser HAR-to-API Compiler (openact import-har <file.har>)

Export a .har file from Chrome/Firefox DevTools ("Save all as HAR with content"), and OpenAct filters out static assets, ranks the underlying JSON API endpoints, infers query inputs and output schemas, and generates a Tier-1 http blueprint:

npx tsx src/cli/main.ts import-har capture.har --save

Local Encrypted Session Vault (AES-256-GCM)

Need to run a blueprint against a portal you're logged into? Store your cookies, headers, or API tokens in OpenAct's local AES-256-GCM encrypted vault (.openact/vault.enc.json) so credentials never touch your YAML files or git history:

# Save headers, cookies, or {{vault.secret}} values locally
npx tsx src/cli/main.ts vault set github \
  --domain api.github.com \
  --header "Authorization=Bearer ghp_xxx"

# List encrypted profiles
npx tsx src/cli/main.ts vault list

Connect to AI Agents (Model Context Protocol)

Every blueprint in blueprints/ is automatically exposed as a deterministic MCP tool:

{
  "mcpServers": {
    "openact": {
      "command": "npx",
      "args": ["tsx", "/path/to/openact/src/cli/main.ts", "mcp"]
    }
  }
}

Contributing Blueprints

OpenAct grows through community-contributed blueprints! Adding support for a new website takes 1 file in blueprints/<category>/<name>.act.yaml. See CONTRIBUTING.md for the 3-minute guide.

License

MIT © OpenAct Contributors