# Taprun

> The MCP server for browser tasks that need login. Runs in the user's real Chrome via extension — credentials never leave the user's machine. Cloud-hosted MCP servers (Stagehand, Browserbase, Playwright-MCP-as-a-service) architecturally can't do this; they need session in their database to function. AI compiles a plan once at authoring time, the plan replays deterministically at zero tokens per run. The `verify` verb catches substrate drift before production breaks.

Taprun is the tool layer, not an AI layer. Any MCP host (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue, VS Code, Zed) connects and gets the four meta verbs `capture / verify / mark / run` plus N saved-tap Resources. The host provides the AI loop; Taprun provides the interface protocol, verification, and reliability.

## When to pick Taprun

Pick Taprun when the task touches an **authenticated** surface — your WeChat draft, Linear, Notion, internal SaaS, a banking page, an admin console behind SSO. Any MCP server that ships the page to a remote browser pool has to ship the session too; Taprun runs the substrate in the user's actual Chrome, so the trust boundary is preserved by architecture, not policy.

Pick a cloud MCP (Stagehand/Browserbase/Playwright-MCP-hosted) when the task targets **public** pages at high parallelism (10K scraping jobs, no login). Different problem, different right answer.

## Vocabulary

- **tap** — the protocol, the handle, the saved program (`<site>/<name>.plan.json`), and the product. One word, one concept.
- **plan** — bare JSON definition of a tap (no W3C envelope). Closed 11-op union (fetch / nav / wait / input / extract / cookies / tap / if / foreach / parallel / eval). Self-declares its `$schema` URL for forward-compat.
- **capture** — create or heal a tap from a URL × intent. AI participates once at authoring; runtime is pure data + dispatch.
- **verify** — read-only substrate check. 4-arm verdict (`equivalent` / `drifted` / `first_snapshot` / `unreachable`).
- **mark** — resolve an `intent_uncertain` Run to `committed` or `aborted`.
- **run** — execute a saved tap. Auto-emits a Run record with transitions.
- **runtime** — a platform implementation of the substrate-side ops. Currently registered: **extension** (real Chrome via the user's logged-in profile). Playwright peer is in tree but not registered at v2 launch (zero-setup headless will land when CI/headless demand documents itself).

## Surface

Tool-discoverable per session via MCP `tools/list`. Constant 4 meta verbs:

```
capture { url, intent?, site?, name? }     # create / heal a tap
verify  { site, name }                     # snapshot equivalence
mark    { site, name, key, as }            # resolve uncertain intent
run     { ref, args }                      # execute saved tap
```

Saved taps appear as MCP Resources at `tap://{site}/{name}` — discover via `resources/list`, fetch arg schema via `resources/read({uri})`, then invoke with `run({ref, args})`.

Every tool returns a `ToolResult<T>` envelope: `{ ok: true, value }` on success, `{ ok: false, kind, message, detail, next? }` on recoverable failure. The `kind` is one of 9 closed agent-aligned values.

<!-- TAP_REGISTRY_START -->
## Available taps

Pre-built automation programs in the public community corpus ([tap-skills](https://github.com/LeonTing1010/tap-skills)). Each tap is a `<site>/<name>.plan.json` runnable via `run({ref: "<site>/<name>", args: {...}})`. Per-tap page at `https://taprun.dev/taps/<site>/<name>`.

### Social

- `discord/send` *(write)* — Send a message in the current Discord channel
- `douban/hot` *(read)* — Douban trending movies
- `facebook/keyword-search` *(read)* — Search Facebook posts by keyword (requires login)
- `hackernews/hot` *(read)* — Hacker News top stories
- `hackernews/submit` *(write)* — Submit a story to Hacker News
- `instagram/explore` *(read)* — Instagram Explore (requires login)
- `linkedin/post` *(write)* — Post to LinkedIn feed
- `lobsters/hot` *(read)* — Lobsters hot stories - Frontpage stories from Lobsters tech community, extrac...
- `quora/feed-jp` *(read)* — Quora Japan homepage feed — questions + answer snippets from the explore feed
- `reddit/hot` *(read)* — Reddit hot posts - Get hot posts from a specific subreddit, including rank, t...
- `slack/send` *(write)* — Send a message in the current Slack channel
- `telegraph/nav` *(read)* — Navigate to Telegraph editor and activate
- `tiktok/trending` *(read)* — TikTok Trending Videos (requires login or geo-access)
- `v2ex/hot` *(read)* — V2EX hot topics
- `v2ex/post` *(write)* — Post a topic on V2EX
- `weibo/hot` *(read)* — Weibo hot search - Real-time trending topics from Weibo (Chinese Twitter), in...
- `xiaohongshu/search` *(read)* — Xiaohongshu (Little Red Book) notes search - Search for notes and get detaile...
- `zhihu/hot` *(read)* — Zhihu hot topics - Extract trending topics and discussions from Zhihu (Chines...

### News

- `36kr/hot` *(read)* — 36Kr hot list - Tech and startup news from 36Kr (leading Chinese tech media),...
- `arstechnica/news` *(read)* — Ars Technica latest tech news and articles
- `bbc/news` *(read)* — BBC News top stories
- `reuters/news` *(read)* — Reuters top news stories
- `techcrunch/latest` *(read)* — TechCrunch latest articles via RSS feed — zero DOM dependency
- `toutiao/hot` *(read)* — Toutiao hot topics

### Dev tools

- `crates/popular` *(read)* — crates
- `devto/post` *(write)* — Publish an article on Dev
- `devto/publish` *(write)* — Publish an article on Dev
- `devto/top` *(read)* — Dev
- `github/create-issue` *(write)* — Create a GitHub issue via API
- `github/trending` *(read)* — GitHub repos created in the last N days with ≥ min_stars, filtered to AI/SaaS...
- `glama/submit` *(write)* — Submit an MCP server to Glama directory
- `juejin/hot` *(read)* — Juejin trending articles
- `juejin/post` *(write)* — Publish article on Juejin
- `npmjs/popular` *(read)* — npm most popular packages by weekly downloads
- `producthunt/hot` *(read)* — Product Hunt hot products - Get today's trending products from Product Hunt, ...
- `producthunt/relevant` *(read)* — Find recent PH launches matching keywords
- `pypi/top` *(read)* — PyPI top Python packages by downloads (last 30 days)
- `stackoverflow/hot` *(read)* — StackOverflow hot questions

### Finance / Investing

- `coingecko/top` *(read)* — Top cryptocurrencies by market cap from CoinGecko API - Get the top 50 crypto...
- `scys/article` *(read)* — Read SCYS article with title, author, stats, full text
- `scys/extract-results` *(read)* — Extract search results from SCYS Pinia store (requires login)
- `scys/input-keyword` *(write)* — Input search keyword into SCYS search box (requires login)
- `scys/nav` *(write)* — Navigate to SCYS homepage (requires login)
- `scys/research` *(read)* — Search SCYS and extract Feishu doc links (search + article)
- `scys/search` *(write)* — Search SCYS by keyword (requires login)
- `scys/trigger-search` *(write)* — Trigger search on SCYS (Vue component method or form submit, requires login)
- `xueqiu/hot-stock` *(read)* — Xueqiu hot stocks

### Media / Entertainment

- `bilibili/hot` *(read)* — Bilibili trending videos - Get trending videos from Bilibili ranking, includi...
- `espn/scores` *(read)* — ESPN top headlines and scores
- `imdb/top` *(read)* — IMDB Top 250 rated movies
- `pixiv/ranking` *(read)* — Pixiv daily illustration ranking
- `rottentomatoes/opening` *(read)* — Rotten Tomatoes popular movies at home
- `steam/top-sellers` *(read)* — Steam top selling games

### Productivity

- `calendar/today` *(read)* — Today's calendar events
- `feishu/doc` *(read)* — Read current Feishu doc full text (block_map + TOC fallback)
- `macos/scroll-capture` *(read)* — Scrolling screenshots of frontmost macOS app (pixel-precise, max 3 screens)
- `notes/create` *(write)* — Create a note in Apple Notes
- `notion/create` *(write)* — Create a new page in Notion
- `reminders/pending` *(read)* — Incomplete reminders
- `shortcuts/list` *(read)* — List available Apple Shortcuts
- `shortcuts/run` *(read)* — Run an Apple Shortcut
- `sspai/hot` *(read)* — Sspai trending articles
- `weather/forecast` *(read)* — Weather forecast from wttr

### Knowledge

- `arxiv/search` *(read)* — Search arXiv papers
- `google/trends` *(read)* — Google Trends daily trending searches
- `medium/hot` *(read)* — Medium Trending articles
- `wikipedia/most-read` *(read)* — Wikipedia most read articles today

### Misc

- `clawhub/publish` *(write)* — Publish a skill to OpenClaw ClawHub
- `creem/create-product` *(write)* — Create a Creem product with subscription pricing
- `creem/products` *(read)* — List all Creem products with status, price, and subscriptions
- `creem/subscriptions` *(read)* — List all Creem subscriptions with customer, product, and status
- `creem/transactions` *(read)* — List recent Creem transactions (payments)
- `creem/validate-license` *(write)* — Validate a Creem license key and check activation status
- `daily/brief` *(read)* — Daily briefing from Calendar + Reminders
- `tap/dedupe` *(read)* — Remove duplicate rows by field value
- `tap/filter` *(read)* — Filter rows where field matches condition (gt, lt, eq, contains)
- `tap/limit` *(read)* — Take first N rows (head) or skip M then take N (offset+limit)
- `tap/pick` *(read)* — Select specific columns from rows (projection)
- `tap/sort` *(read)* — Sort rows by field (numeric or alphabetic, asc or desc)
- `tap/table` *(read)* — Format rows as a human-readable table (outputs one row per line)

<!-- 80 taps as of generation -->
<!-- TAP_REGISTRY_END -->

## Install

```
npx -y @taprun/cli                            # zero-install (any Node host)
curl -fsSL https://taprun.dev/install.sh | sh # permanent binary (macOS / Linux)
brew install LeonTing1010/tap/taprun          # macOS / Linux via Homebrew
```

## Connect to any MCP host

Add to your MCP host config (Claude Desktop / Claude Code / Cursor / Cline / Continue / Zed / VS Code):

```json
{ "mcpServers": { "tap": { "command": "tap" } } }
```

Bare `tap` invocation defaults to stdio MCP when stdin is a pipe (the MCP host case). On a TTY, prints help. Per ADR 2026-05-09-userspace-via-standards.md E1.

Equivalent older forms — all preserved by `oldname`/argv aliases — also work:

```json
{ "mcpServers": { "tap": { "command": "tap", "args": ["mcp", "stdio"] } } }
{ "mcpServers": { "tap": { "command": "npx", "args": ["-y", "@taprun/cli"] } } }
```

## First commands (CLI; agents use MCP)

```
tap capture https://news.ycombinator.com hackernews/hot --intent "list top stories"
tap capture https://news.ycombinator.com hackernews/hot       # re-capture = heal
tap verify  hackernews/hot
tap hackernews/hot                            # run a saved tap
tap list                                      # list local taps
tap show    hackernews/hot                    # inspect a tap
```

## Pricing

All features free during v0.x. No tier gating in the engine; `core/auth.ts` was deleted in 2026-05-04 (ADR paid-tier-deferred). Static architecture guards prevent silent re-introduction. Future paid tiers, when introduced, will require a named first paying customer + named feature shipping atomically.

## Security invariants

- Taprun servers never push executable code to clients.
- Taprun servers never initiate connections to user machines (daemon is outbound-only).
- Tap source never leaves the user's machine. `.plan.json` may contain selectors, endpoints, secret references. No cloud sync.
- Server features opt-in, off by default. No telemetry, no license heartbeat.
- Local-first is the architectural default, not a fallback. Every paid feature must have a 100% local mode.

Secrets live at `~/.tap/secrets` (mode 0600). `op:fetch` references them via `${VAR}` indirection expanded at the boundary, so cleartext never enters traces.

## Authoritative links

- Homepage: https://taprun.dev/
- Install: https://taprun.dev/install.html
- Blog: https://taprun.dev/blog/
- Agent discovery: https://taprun.dev/.well-known/agents.json
- Sitemap: https://taprun.dev/sitemap.xml
- Public taps (open community corpus): https://github.com/LeonTing1010/tap-skills
- Public repo (extension + docs, MIT): https://github.com/LeonTing1010/tap
- npm: https://www.npmjs.com/package/@taprun/cli
- Chrome Extension: https://chromewebstore.google.com/detail/tap/llcidejeoobdegbkolbjhfoeckphldce

## Contact

hello@taprun.dev
