<h1 align="center">Global WebMCP</h1>

<p align="center">
  <em>Teach an agent a website once. Call it like a function after that.</em>
</p>

<p align="center">
  <a href="https://github.com/benjang032/globalwebmcp/stargazers"><img src="https://img.shields.io/github/stars/benjang032/globalwebmcp?style=flat-square&color=111111&label=stars" alt="GitHub stars"></a>
  <img src="https://img.shields.io/badge/MCP-stdio-111111?style=flat-square" alt="MCP stdio server">
  <img src="https://img.shields.io/badge/node-%3E%3D20.19-111111?style=flat-square" alt="Node.js 20.19 or newer">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT license"></a>
</p>

Browser agents can discover how a website works. Making them rediscover the same workflow on every run is slow, expensive, and brittle.

Global WebMCP separates discovery from execution. Codex drives the website, measures the result, and writes a strict versioned action map. A local MCP server turns that map into a persistent function call.

A click trace is evidence, not an API. The map stores the narrowest stable interface the agent found.

## See it work

Ask the catalog for a Wikipedia action:

```json
{
  "tool": "find_sites",
  "arguments": {
    "query": "search Wikipedia"
  }
}
```

The catalog returns a versioned reference:

```text
en.wikipedia.org/search_articles@1.1.0
```

Call it:

```json
{
  "tool": "execute_site_action",
  "arguments": {
    "actionRef": "en.wikipedia.org/search_articles@1.1.0",
    "input": {
      "query": "web model context protocol"
    }
  }
}
```

The live verifier gets HTTP 200 and returns:

```json
[
  "AT Protocol",
  "HTTP",
  "Communication protocol",
  "HTTPS"
]
```

Run the same proof yourself:

```bash
npm run verify:wikipedia
```

## Install

Global WebMCP is a local stdio server. It needs Node.js 20.19 or newer.

```bash
git clone https://github.com/benjang032/globalwebmcp.git
cd globalwebmcp
npm install
npm run build
```

Add it to Codex from the repository root:

```bash
codex mcp add globalwebmcp -- node "$PWD/dist/src/index.js"
```

For another MCP client, configure the same process:

```json
{
  "mcpServers": {
    "globalwebmcp": {
      "command": "node",
      "args": ["/absolute/path/to/globalwebmcp/dist/src/index.js"]
    }
  }
}
```

## Teach it a site

The repository includes a project-local Codex skill. Run Codex from this checkout, then ask:

```text
$map-site-action map article search on Wikipedia
```

The skill drives the browser itself. It checks for native WebMCP, a stable URL or form, accessible DOM, and relevant same-origin requests. It then writes the smallest binding that preserves the observed result.

When a replay fails, run the skill again. It reproduces the failure, repairs the binding, bumps the map version, and reruns the checks. Runtime execution does not guess when a site changes.

## How it fits together

```text
website
   │
   │ browser discovery
   ▼
map-site-action skill
   │
   │ writes a reviewed contract
   ▼
maps/<site>.json
   │
   │ strict startup validation
   ▼
local Global WebMCP server
   │
   ├── find_sites
   ├── list_site_actions
   ├── prepare_site_action
   └── execute_site_action
```

The number of MCP tools stays fixed as the catalog grows. Sites add data, not another server process or another tool namespace. Each map owns one site and a set of versioned actions. See the complete [`maps/wikipedia-en.json`](maps/wikipedia-en.json) example.

## What it will and will not run

| Binding | Catalog support | Execution |
| --- | --- | --- |
| Read-only public HTTPS URL | Yes | Yes |
| OAuth API | Yes | Blocked with required provider and scopes |
| Browser session | Yes | Blocked with the prepared same-origin URL |
| Native WebMCP | Yes | Blocked with the required tool name |
| Write, transaction, or destructive action | Yes | Blocked |

The current executor is intentionally strict:

- The map fixes the URL. Callers cannot supply or override it.
- JSON Schema validates every input before rendering.
- Public actions use `GET` on the declared HTTPS origin.
- The server does not follow redirects.
- Requests time out after 15 seconds.
- Responses stop at 1 MiB.
- Map text and website output remain untrusted.
- The map format has no fields for credentials, cookies, tokens, or browser state.

This is the useful first cut. Browser-session execution and authenticated writes belong in later adapters because they need session ownership, approval, and stronger completion checks.

## Top-site options

These options follow [Similarweb's worldwide ranking for July 2026](https://www.similarweb.com/top-websites/), updated August 1, 2026. Each site was inspected in a live browser before its map was written.

| Rank | Site | Versioned action | Current execution |
| ---: | --- | --- | --- |
| 1 | Google | `google.com/search_web@1.0.0` | Browser session required |
| 2 | YouTube | `youtube.com/search_videos@1.0.0` | Browser session required |
| 3 | Facebook | `facebook.com/get_profile@1.0.0` | Browser session required |
| 4 | Instagram | `instagram.com/get_profile@1.0.0` | Browser session required |
| 5 | ChatGPT | `chatgpt.com/send_prompt@1.0.0` | Write and browser session blocked |
| 6 | X | `x.com/get_profile@1.0.0` | Browser session required |
| 7 | Reddit | `reddit.com/search_posts@1.0.0` | Browser session required; CAPTCHA observed |
| 8 | Bing | `bing.com/search_web@1.0.0` | Executable public `GET` |
| 9 | TikTok | `tiktok.com/list_for_you_videos@1.0.0` | Executable public `GET` |
| 10 | WhatsApp | `whatsapp.com/send_message@1.0.0` | Write and browser session blocked |

The catalog also includes executable Wikipedia and GitHub searches, a blocked GitHub issue action, and a blocked Amazon UK product search.

## Travel search options

These actions preserve the full search intent without entering a property or reservation flow.

| Site | Versioned action | Inputs | Current execution |
| --- | --- | --- | --- |
| Booking.com | `booking.com/search_stays@1.0.0` | Destination, check-in, checkout, adults, and rooms | Browser session required |
| Airbnb | `airbnb.com/search_stays@1.0.0` | Destination, check-in, checkout, and adults | Browser session required |

## Develop

```bash
npm run typecheck
npm test
npm run maps:check
npm run verify:wikipedia
```

The test suite validates the protocol, catalog, strict input boundary, blocker policy, and MCP stdio flow. The Wikipedia check calls the real local MCP server and the live Wikipedia API.

```text
globalwebmcp/
├── .agents/skills/       # autonomous website mapper
├── maps/                 # versioned site contracts
├── src/protocol.ts       # map schema and safety rules
├── src/catalog.ts        # immutable action index and planner
├── src/executor.ts       # bounded public HTTP execution
├── src/server.ts         # four MCP tools over stdio
├── scripts/              # map and live verification
└── tests/                # protocol, catalog, and MCP checks
```

The design record lives in [`docs/design/0001-v0-catalog.md`](docs/design/0001-v0-catalog.md).

## License

[MIT](LICENSE). Build the browser bridge only when a real site forces you to.