# dot bridge

An MCP bridge your dot deploys into its own private Site. Your dot calls any HTTPS API through it: you add the service and its key on the bridge's setup page once, and from then on the dot sends requests with that key.

The bridge is only a bridge. It sends the method, path, query, headers and body your dot gives it to the service's origin, adds the saved key, and returns the response. It does not judge paths, list paths or filter names. The service at the other end decides what each request may do.

![dot bridge](docs/assets/jailbreak-dot-api-bridge.png)

## Start here

- Give your dot the [build instructions](agent-handoff.md) and ask it to build your bridge.
- [Setup guide](SETUP.md): first deployment, adding a service, updating.
- [Cookiejar publishing sample](examples/README.md): a small static site to deploy.
- Source: [rkz211/dot-bridge](https://github.com/rkz211/dot-bridge). The version is in `package.json` and in the MCP `initialize` response (`serverInfo.version`).

## Add a service

1. Open the bridge's private page and choose **New service**.
2. Enter a name, an HTTPS endpoint the bridge can GET to check the key, and the key.
3. Choose **Save & test**. The key is saved when the check passes.

The default header is `Authorization: Bearer <key>`. **Authentication options** also offers `X-API-Key` and any custom header and prefix. The endpoint's origin becomes the service's base URL. Your dot can also prepare a service from the provider's documentation with `bridge_prepare_connection`; you then add the key on the page.

Cookiejar is built in. Use your account key (`sites_…`); the page checks it with `GET /sites`.

## Tools

| Tool | What it does |
| --- | --- |
| `bridge_connection_info` | Shows the Sites-managed sign-in status and the signed-in user ID |
| `bridge_prepare_connection` | Adds a service: origin, auth header, prefix, description |
| `bridge_connection_status` | Lists services, whether each has a key, and setup links |
| `bridge_services` | Lists services and whether each has a key |
| `bridge_api_preview` | Shows the request the bridge would send, without sending it |
| `bridge_api_read` | Sends GET or HEAD and returns the response |
| `bridge_api_write` | Sends POST, PUT, PATCH or DELETE and returns the response, recorded under a UUID `operationId` |
| `bridge_api_upload` | Uploads source bytes to the signed Cookiejar source URL from `POST /deploy` |
| `bridge_operation_status` | Shows the recorded outcome of a write |
| `cookiejar_owned_sites` | Lists the Cookiejar sites the saved key owns |
| `cookiejar_create_site` | Creates a Cookiejar site |
| `cookiejar_deploy_site` | Deploys a source ZIP to a Cookiejar site and starts the build |
| `cookiejar_operation_status` | Shows the recorded outcome of a create or deploy |

Any path on the service works. There is no endpoint map to maintain: the dot reads the service's own documentation and sends the request.

## How it works

- Requests always go to the saved origin of the service named by `serviceId`, with the saved auth header and key. A request cannot change the origin or the auth header.
- Redirects are returned as `redirectRefused` instead of followed, so the key never travels to another host.
- The bridge removes its own saved key values from responses and errors. Everything else in the response passes through unchanged.
- Each write is recorded under its `operationId`. Sending the same ID again returns the recorded result instead of repeating the write.
- Keys are saved in the Site's own D1 database and are never shown again on the page.
- The Site is owner-private. Sites-managed sign-in identifies the caller.

## Development

Node.js 22.13 or later (Node.js 24 recommended). No runtime dependencies.

```sh
npm test
npm run check
npm run build
```

`npm test` regenerates `ui.mjs` from `ui/` first. The build writes the Worker and its modules to `dist/server/`.

## License

MIT. See [LICENSE](LICENSE).