<p align="center">
  <img src="docs/media/banner.jpg" alt="The WMA dashboard with demo data" width="100%">
</p>

<h1 align="center">WMA · Web MCP Anything</h1>

<p align="center">
  <b>This site has no MCP? Make one.</b><br>
  Point WMA at a website. Review the MCP tools it drafts from what the site does. Your agent calls them by name.
</p>

<p align="center">
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-2f6bff"></a>
  <img alt="Node.js 20+" src="https://img.shields.io/badge/node-%3E%3D20-12a150">
  <img alt="Status: developer alpha" src="https://img.shields.io/badge/status-developer%20alpha-ff7a1a">
  <img alt="Protocol: MCP" src="https://img.shields.io/badge/protocol-MCP-e0218a">
  <a href="https://zirkomirko.com/tools/wma/"><img alt="Website" src="https://img.shields.io/badge/site-zirkomirko.com%2Ftools%2Fwma-0b0b10"></a>
</p>

<p align="center">
  <a href="https://zirkomirko.com/tools/wma/"><img src="docs/media/wma-film.gif" alt="WMA film: an agent is stuck on a site with no API or MCP server, then WMA drafts a tool it can call" width="640"></a><br>
  <sub>Watch the full 22 s film with sound on <a href="https://zirkomirko.com/tools/wma/">the website</a>.</sub>
</p>

## Why

No public API. No MCP server. So your agent is stuck. WMA lets you build the tool yourself from what the site already does: point it at a site, it explores and records the requests and page steps it sees (or browse yourself with `--interactive`), and it saves parameterized tools as a local JSON spec. Read tools may start on; inferred write tools start off. Check the spec before you connect an agent. Then WMA serves the enabled tools over MCP.

```text
1  Point       npx wma "https://hn.algolia.com/?q=rust"     # WMA explores and records
2  Review      npx wma ui                                    # rename, narrow, enable or disable
3  Call        search_stories({ q: "rust" })  ->  { hits: [...], status: 200 }
```

<p align="center"><img src="docs/media/loop.jpg" alt="The WMA dashboard with demo data: discovered tools and one tool definition" width="720"></p>

| | What it does |
|---|---|
| **Observe** | Visit a site while WMA records network requests and selected page interactions. |
| **Review** | Proposed tools land in a local JSON spec. Rename them, narrow parameters, enable what you trust. |
| **Execute** | Serve enabled tools over MCP (stdio or loopback HTTP). Saved tools replay without a model. |
| **Verify** | `wma check` confirms a response came back, not that the data is complete. Inspect results yourself. |
| **Refine** | `wma refresh` keeps reviewed tools and edits; new candidates arrive disabled. |

## Honest status

WMA is a **developer alpha** (v0.1.0). It is useful today, and it has real limits.

| Works today | Not established yet |
|---|---|
| Proposes parameterized tools from what it observed on a site | Discovery is heuristic and covers only what you observed |
| Local, reviewable JSON specs; refresh keeps your edits | No self-healing: refresh does not repair broken tools |
| MCP server over stdio and loopback HTTP | Health checks don't prove the data is complete |
| Live interactive browser tools | Access walls stop it. It is not a bypass |
| Local dashboard (`wma ui`) to support review | No scheduler, no stable SDK, not on npm; extension and WebMCP are experimental |

Not yet shown to beat a hand-written script. Use it on sites you are allowed to automate. Action controls prohibit purchases, messages and other sensitive operations, but they are controls, not guarantees.

## Install and check

```sh
git clone https://github.com/ZirkoMirkoLabs/web-mcp-anything
cd web-mcp-anything
```

Requires Node.js 20+ and npm. Open a terminal in this source checkout and run:

```sh
npm ci
npx playwright install chromium
npm run build
npx wma doctor
```

The package is not published to npm. These `npx wma` commands use this checkout's installed executable; keep running them here. Outside this checkout, bare `npx wma` may fetch a different package and is not a supported installation method. To use a local packed build in another folder, run `npm pack` in `packages/core`, then run `npm install <path-to-tgz>` in the other folder and use `npx --no-install wma` there. Keep that folder in place for the generated Claude configuration. On Linux, Chromium may also need system libraries; doctor prints the relevant recovery command. Set `WMA_HOME` to choose a different data directory.

## Add a website and connect Claude

```sh
npx wma "https://books.toscrape.com/"
npx wma "https://hn.algolia.com/?q=rust" --goal "find Rust stories"
```

Replace the URL with your website. The optional `--goal` guides discovery toward a task. WMA saves a spec in the current directory and registers it under `~/.wma/specs`. It prints observed coverage and, when usable tools exist, a ready-to-copy `claude mcp add` command and Claude Desktop JSON.

For **Claude Code**, run that printed command in the project where you want the tools. It registers them in local project scope. For **Claude Desktop**, merge the printed `mcpServers` entry into Settings > Developer > Edit Config, then fully quit and restart Desktop. Config locations:

- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: use your Desktop distribution's Edit Config location; some use `~/.config/Claude/claude_desktop_config.json`.

The generated config contains absolute paths, so keep this checkout and your saved specs in place. Once connected, ask Claude to use the website's tools for your task.

## Daily use

New captures also expose ten live browser tools over MCP: open, snapshot, click, type, select, press, wait, screenshot, drag and download observation. Start with `browser_open`, then use the labelled refs in `browser_snapshot` to work with the current page. These tools keep one page/session alive; captured API tools remain additional options. Screenshots help with canvas controls, and local exports are saved under the capture directory. Existing owner-completed browser sessions are reused.

The browser tools enforce denied destinations, robots rules, a 30-top-level-navigation session limit, and at least two seconds between public page loads. They stop at real access walls. Robots rules govern top-level navigation and direct WMA HTTP/API fetches; page-initiated scripts, CDNs, frames, workers, service workers, fonts, WebSockets and XHR (including POST) load with normal browser methods and concurrency. Browser navigation is not limited to recorded API origins. Action controls still prohibit purchases, messages and other sensitive operations; page network POSTs are not proof of permission for such actions. A failed API capture does not establish site usability: a saved spec with browser actions can be served for a live attempt, which may still be blocked.

```sh
npx wma list
npx wma check books
npx wma refresh books
npx wma ui --port 18863
```

Use the site ID from `list` in place of `books`. `check` tries recorded samples of read-only tools. `refresh` preserves reviewed edits and disabled states; newly discovered tools need review. `ui` opens a local dashboard at the printed address; stop it with Ctrl+C.

To remove the saved demo site and keep a restorable spec backup:

```sh
npx wma remove books --yes
```

Removal keeps local captures and sessions. Without `--yes`, removal asks for confirmation in a terminal.

## When a site blocks capture

Use a visible browser and complete the site's check yourself. Replace this demo URL with the blocked URL:

```sh
npx wma "https://books.toscrape.com/" --interactive
```

Browse to the content you need, let it load, then close the browser or press Ctrl+C. Interactive capture checkpoints Playwright storage state and saves it under `~/.wma/secrets`, per origin. Later captures and browser tools reuse it; HTTP tools send saved cookies only to that exact origin. Interactive capture allows up to ten minutes by default. It needs a graphical display; a headless machine prints a recovery message. You can also import a successful HAR recording through the dashboard.

This is a user-completed session, not a challenge bypass. Some checks bind access to a particular browser or expire quickly, so saved state may still be rejected. WMA reports blocked sites instead of advertising working tools.

## Safety and limits

Inferred write operations are off by default; review them before opting in. Recognized credentials and browser sessions stay locally under `~/.wma/secrets`, separate from specs. Captures are under `~/.wma/captures`. Tool results redact known secrets. Review files before sharing: secret detection is heuristic.

For exact HTTPS origins npmjs.com, www.npmjs.com, pypi.org and stackoverflow.com, add and refresh use documented public APIs instead of browser capture; an explicit `--interactive` still opens the browser. npm supports search and exact package lookup, including scoped names. PyPI's JSON API provides **exact project lookup only**, not search: a `/search/?q=...` URL does not become a package name; supply one to the tool. Stack Overflow uses the Stack Exchange API, with shared quotas and rate limits. Inspect `quota_remaining`, API errors and `backoff` in results; wait the specified number of seconds before calling the same method again. WMA persists and enforces returned method backoff across processes sharing `WMA_HOME`; a blocked call returns `retryAfter` without an upstream request. It does not coordinate other installations or third-party clients. See the [npm registry API](https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md), [PyPI JSON API](https://docs.pypi.org/api/json/) and [Stack Exchange throttles](https://api.stackexchange.com/docs/throttle). API definitions are not evidence of a browser visit; review and test them. Other origins use capture. Cambridge Dictionary has no adapter; use the user-completed `--interactive` flow above, which may still be rejected or expire.

Discovery only covers observed traffic and page content, not every workflow or login scheme. Read-like POST searches may be enabled, but health checks skip all POSTs and interactive actions. Tool results are bounded and paginated; upstream bodies above 16 MiB are rejected. The extension and exported WebMCP snippet use core argument validation, but run under browser permissions and site policy; the snippet does not inject local secrets. No claim is made that every website works.

For maintainers: `api-policy.ts` enforces Stack Exchange cooldowns through HTTP execution.

Robots fetch handling follows RFC 9309: 4xx responses permit access, successful responses retain parseable disallow rules, and network/5xx errors receive one retry before exclusion. Subresource and API polling requests do not consume the navigation count. `browser_downloads` waits for export completion and returns path, size, MIME type and suggested filename.

Browser egress uses an isolated per-context forward proxy. It checks every actual socket destination (including all DNS answers and redirect hops), blocks private/link-local/metadata addresses, and strips credential headers on requests outside the exact owner origin. Saved session values in foreign URLs or bodies are rejected before transmission. An explicitly supplied local entry URL authorizes only that exact local origin for development; recorded API origins do not widen that exception. HTTPS is locally terminated using an ephemeral in-memory key trusted only by the launched Chromium process; the proxy validates upstream certificates normally. No certificate is installed in the OS trust store. The guard covers worker and WebSocket traffic too; non-proxied WebRTC UDP is disabled. Direct API origin/credential restrictions and bot-wall reporting remain enforced.

## Contributing

Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) first; report security problems as described in [SECURITY.md](SECURITY.md), not in public issues.

## License

[MIT](LICENSE) © ZirkoMirko