# SiteBridge — website to MCP

> **Experimental prototype.** Browser and model compatibility varies. Read [TESTING.md](TESTING.md) for verified checks and remaining manual validation.

Add a website, open it in Chrome, sign in yourself, and create a scoped MCP connection that an AI app can use. SiteBridge exposes the site's visible browser interface through MCP. It does not need its own AI API key: your MCP-capable AI application supplies the model.

This is a **personal, local gateway with a Chrome companion extension**. It includes a dashboard, per-website MCP configurations, an official SDK-based MCP server, a browser relay, and reviewed browser actions. It is not an automatic reverse engineering system for every website's private API.

## Quick start

1. Extract the ZIP to a permanent folder. Install **Node.js 22 or later** if needed from [nodejs.org](https://nodejs.org/).
2. In the extracted `sitebridge` folder, run `start.cmd` on Windows. On macOS/Linux, open a terminal in that folder and run `sh start.sh`. The launcher installs the locked runtime dependencies on first use, then starts the local gateway. An internet connection is needed for that first dependency installation.
3. Open the **private setup link printed in the terminal** in Chrome. It looks like a localhost URL with a setup fragment. Do not share it. Leave the terminal open while using SiteBridge.
4. In Chrome, open `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and select this package's **`extension`** folder.
5. Pin **SiteBridge** in Chrome and click its icon. Copy the eight-digit pairing code from the dashboard into the Chrome panel and click **Pair Chrome**. If you changed the gateway port, update its address in the panel too.
6. In the dashboard, add your website URL. In the Chrome panel, click **Allow & open** for that website. Approve Chrome's site-access request.
7. **Sign in normally on the website.** Enter passwords, MFA and other login details only on the real website. The login session stays in your normal Chrome profile.
8. Once you are back on an allowed website page, click **I'm signed in · Create MCP** in the dashboard. SiteBridge reads the current interface and prepares the connector.
9. Click **Connect AI** and copy/download the generated MCP configuration into your AI application's MCP settings. Prefer **Local app · stdio** for a desktop/CLI application. Local HTTP is also available for clients that support it.

Chrome 120+ is required. This package is for **unpacked extension installation**; it has not been submitted to the Chrome Web Store. Keep the source folder in place because generated stdio configurations use its absolute path. If you move it, regenerate the configuration. Reload the extension after changing its files and reopen the panel.

## How it works

- **Your website stays in Chrome.** A selected tab uses your existing website session. SiteBridge does not export cookies, ask for website passwords, call hidden private APIs, or give the model arbitrary JavaScript execution.
- **Each website gets its own connection.** The gateway generates a separate website ID and access token. A connector is restricted to that website's explicitly allowed origins and selected tab. It cannot enumerate or control your other website connectors.
- **The AI uses MCP tools.** Reading returns current page text and observable controls. A proposed change gets an action ID and a review card in the Chrome panel.
- **You approve the change.** The AI receives `approval_required`; nothing changes yet. You approve or decline in Chrome. The AI checks `action_status` and reads the page again to verify the result.

The scan observes the **current page** and control counts. It does not crawl the whole website, infer whether you are successfully logged in, learn every workflow, or produce a native semantic API like `list_invoices` from a login alone. You confirm that the browser session is ready. A site without a login can also be connected. Dedicated APIs or recorded workflows would be separate extensions to this project.

## Available tools

Each site exposes these nine tools through its own MCP endpoint/process:

| Tool | Behavior |
| --- | --- |
| `site_status` | Connection, selected-tab, and connector status for this website. |
| `read_page` | Read rendered text, selection, standard fields, buttons, links and exact target IDs. Sensitive fields are redacted. |
| `read_selection` | Read selected text on the selected website tab. |
| `navigate` | Propose navigation within allowed origins. Requires approval. |
| `click` | Propose a click on an observed target, including Send/Submit. Requires approval. |
| `fill_field` | Propose replacing text in a supported field. Requires approval. |
| `select_option` | Propose selecting a standard dropdown option. Requires approval. |
| `scroll` | Propose scrolling the page. Requires approval. |
| `action_status` | Check a proposed action; optionally wait up to 20 seconds for an update. |

Possible action states include `approval_required`, `completed`, `declined`, `expired`, and `failed`. A completed click only proves that the click was dispatched. The AI should read the page to confirm a message was sent or a submission succeeded. Field changes dispatch standard input/change events; the website may autosave or react to them. The extension does not explicitly submit a form when filling a field.

Approvals expire after two minutes and are consumed before execution. Changed target/form data or page navigation invalidates the old preview. Concurrent proposals have separate approvals, and a change can invalidate another proposal's earlier observation. No action is retried automatically. If an in-flight page action's response fails, the website may still have acted: check the page before retrying. At most ten approval cards can wait in Chrome at a time.

## Connecting AI applications

Use the configuration generated by the dashboard rather than inventing a website endpoint.

**Stdio:** a local MCP-capable desktop or CLI application launches `src/mcp-stdio.mjs` with the selected website ID and local data directory. The generated JSON has no token embedded; the local process reads that site's credential from the protected data file. The gateway must already be running. Your AI application's exact configuration format or server registration command can differ; the generated `command` and `args` are the values to use.

**Local HTTP:** the dashboard also gives a Streamable HTTP URL and a website-specific Bearer header. The example JSON uses a common `mcpServers` format with `type: "http"`; adapt its URL/header fields to your client's format if required. Keep this configuration private because it contains the site's access token. The server supports the official SDK's current MCP transport and its 2025-era compatibility path.

**Cloud AI services:** localhost is reachable only on your own computer. A cloud-hosted ChatGPT/MCP client cannot directly connect to this localhost server. A separately hosted, authenticated relay with a suitable remote authorization flow would be needed. This release does not publish such a relay, implement remote OAuth, or install itself into your ChatGPT account. Do not expose the local port to the internet to work around this limit.

MCP support belongs to the AI application, not the model's API alone. A model without an MCP-capable host cannot connect merely by receiving this configuration. Website automation quality also depends on the model following tool instructions and understanding the observed page.

## Website access and login

- Use the exact website URL you want. The initial allowed origin includes its scheme, host and port.
- If the workflow uses a second origin, add it under the site's **Allowed origins** in the dashboard. Then click Allow & open or Use current tab in Chrome to grant the additional access. Wildcards and arbitrary cross-origin navigation are not exposed to the model.
- SSO can navigate to a separate identity provider while **you** log in. The controller will not read or act outside its allowed origins. Return to the approved application after login; you normally do not need to authorize the identity provider itself.
- Use **Use current tab** if you already have the desired page open. This explicitly selects that tab for the connector. Keep it open while the AI works. A navigation or logout can change which data is available.
- Browser restarts clear tab bindings and pending approvals. Existing website cookies follow the website/Chrome's own persistence rules. Bind the desired tab again after restarting Chrome. A persisted “MCP ready” connector does not prove that a login session is still active.
- Deleting the website in the dashboard revokes its MCP credential and browser policy. It does not log you out of the website. Chrome's previously granted host permission may remain; revoke it in Chrome's extension settings if desired.
- **Unpair** disconnects Chrome from the gateway and removes the saved browser connection. A new pairing code is required to reconnect. A new successful pairing replaces the old browser connection. Only one Chrome profile is paired to a gateway at a time.

## Privacy and trust boundaries

Website passwords and cookies are not exported. The model can still receive **visible signed-in page content** and the task results you ask it to use. Your AI provider/application controls how it handles that content. Connect only pages you intend that AI to read.

Standard password/file inputs, recognizable payment/credential fields, and private-marked content are redacted or excluded by the page reader. Redaction is heuristic, not a guarantee that all sensitive text is recognized. Ordinary visible personal data can be read. Edits to recognized sensitive fields are blocked and require manual interaction.

SiteBridge binds its HTTP server to `127.0.0.1`, validates Host and Origin, authenticates dashboard/MCP/bridge access separately, uses one-time pairing codes, and issues credentials per website. Requests, websocket messages, input sizes and queued approvals have limits. API tokens stay out of URL query parameters and the bridge's websocket URL. The dashboard setup link uses a fragment and removes it from the address bar after loading.

Local state is stored under `~/.sitebridge` by default (or the directory supplied with `--data-dir`). It contains site metadata, gateway credentials and website MCP credentials. On systems with POSIX permissions, the directory is mode `0700` and files are `0600`. These files and the extension's locally stored pairing token are **not encrypted**; protect your OS account. On Windows, access follows your account's filesystem permissions. The dashboard's setup token is retained in that tab's session storage. No model keys are needed by SiteBridge.

Page snapshots are passed through in memory for the active tool call and are not saved as a page archive. The persistent registry stores website name/URL, allowed origins, readiness, scan title and control counts. Approval previews stay in Chrome-session storage. Recent action outcomes, including draft values when relevant, stay in gateway memory for up to 30 minutes, bounded to 500 actions. Closing/restarting the gateway clears those results. There is no analytics or cloud relay.

Page content is explicitly treated as untrusted data in the MCP instructions; the extension executes a fixed set of packaged operations. These controls and approvals reduce risk but do not make a model immune to prompt injection or make an untrusted website safe. Review recipients, content, destinations and destructive operations before approving. Only the extension's own panel can approve; the AI has no approval tool.

## Limits

This version works with standard rendered web pages, ordinary form inputs, textareas, single-select dropdowns, buttons, links and basic contenteditable elements. It also inspects open shadow roots. It prioritizes controls in the current viewport and caps page/element output.

Chrome's internal pages, Chrome Web Store, other extensions, file URLs, nested/cross-origin frames, closed shadow roots, canvas-only editors, file pickers, CAPTCHAs, protected login/permission dialogs and controls requiring trusted hardware input are not automated. Some rich editors and custom SaaS interfaces need dedicated adapters. Links that open a new tab may require you to bind that tab manually. Website redesigns or session expiration can break a workflow. Native website APIs and application-specific bulk actions are not generated automatically.

This is a single-user local tool, not a multi-tenant hosted product or a production-ready remote authorization service.

## Run and configure manually

```sh
npm ci --omit=dev
npm start
```

To choose another local port or data directory:

```sh
node src/main.mjs --port 4319 --data-dir /absolute/path/to/private/sitebridge-data
```

Keep one gateway instance per data directory. Stop it with Ctrl+C. If the port is already in use, stop the old instance or choose a different port. Use the newly printed setup link and update the Chrome panel's gateway address. The generated stdio process discovers the active local gateway through the data directory's runtime file.

The first run installs npm dependencies. The Chrome extension itself has no build step or runtime package dependency. Never put production website passwords, browser cookies, generated access tokens, `.sitebridge` data, or private setup links into this source package or public version control.

## Testing

```sh
npm ci
npm test
npm run check
npm run test:browser
npm run package
```

The optional browser suite uses the development-only Linux Chromium package, a real rendered DOM, a local practice form, the actual gateway/relay/MCP client and production extension code with **simulated Chrome extension APIs**. You may specify an installed Chromium path with `SITEBRIDGE_CHROMIUM_PATH`. It does not sign into a real website or exercise native Chrome permission dialogs. See `TESTING.md` for what was run and the remaining desktop checks.

For manual practice, serve the extracted folder with `python3 -m http.server 8000 --bind 127.0.0.1`, add `http://127.0.0.1:8000/tests/fixture.html`, and try the practice form. It sends nothing to a real service. Use a local MCP-capable AI client and ask it to fill a message, wait for your approval, then verify the displayed result.

## Source map

| Path | Purpose |
| --- | --- |
| `src/gateway.mjs` | Local dashboard/API, MCP HTTP endpoints and site scope enforcement |
| `src/mcp.mjs` | Official SDK MCP tools and instructions |
| `src/mcp-stdio.mjs` | Per-website stdio connection process |
| `src/relay.mjs` | Authenticated Chrome bridge and action outcomes |
| `src/store.mjs` / `src/policy.mjs` | Private local state, URL rules and tool validation |
| `extension/` | Chrome side panel, browser relay controller and page reader |
| `public/` | Local website/MCP setup dashboard |
| `tests/` | Gateway, protocol, policy and browser integration checks |
| `start.cmd` / `start.sh` | First-run dependency install and local startup |

## References

- [Official MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [MCP transport specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)
- [Chrome Side Panel API](https://developer.chrome.com/docs/extensions/reference/api/sidePanel)
- [Chrome extension installation](https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-world#load-unpacked)

MIT licensed. Independent project; not affiliated with Chrome, any website provider, or an AI platform.