@ractive-ch/tab-mcp 0.1.0-alpha.0 → 0.1.0

package/README.md

@@ -0,0 +1,131 @@
+# @ractive-ch/tab-mcp
+
+The tab-mcp relay. It lets AI apps (Claude, ChatGPT, Claude Code) call
+[MCP](https://modelcontextprotocol.io) tools that a web page offers while it is open in a
+browser tab.
+
+The page connects to the relay over a WebSocket with the browser library
+[`@ractive-ch/tab-mcp-client`](https://www.npmjs.com/package/@ractive-ch/tab-mcp-client)
+and gets an MCP address. The user adds that address to an AI app and pairs it by typing
+a code from the page on the relay's sign-in page. The relay then forwards the AI app's
+requests to the page. It knows nothing about the tools themselves.
+
+**Status: 0.1.0.** Until 1.0, a new minor version can still change settings and the API.
+The relay speaks MCP revision 2026-07-28 only and accepts AI apps that register through
+OAuth Client ID Metadata Documents; see [compatibility](https://github.com/ractive/tab-mcp/blob/main/docs/compatibility.md)
+for which apps work.
+
+## Run it
+
+The relay needs [Bun](https://bun.sh) 1.4.3 or newer. It does not run on Node.js.
+
+```sh
+bun add --global @ractive-ch/tab-mcp
+TAB_MCP_PUBLIC_URL=https://relay.example.com \
+  TAB_MCP_ALLOWED_ORIGINS=https://app.example.com \
+  tab-mcp
+```
+
+Or with Docker (linux/amd64 and linux/arm64):
+
+```sh
+docker run -d -p 127.0.0.1:8080:8080 -v tab-mcp-data:/data \
+  -e TAB_MCP_PUBLIC_URL=https://relay.example.com \
+  -e TAB_MCP_ALLOWED_ORIGINS=https://app.example.com \
+  ractive/tab-mcp:0.1.0
+```
+
+The image is also on `ghcr.io/ractive/tab-mcp`. Put the relay behind a reverse proxy
+with TLS; see
+[self-hosting](https://github.com/ractive/tab-mcp/blob/main/docs/self-hosting.md) for
+WebSockets, event streams and proxy time limits.
+
+For a local test with a page on `http://localhost:3000`:
+
+```sh
+NODE_ENV=development TAB_MCP_PUBLIC_URL=http://localhost:8080 \
+  TAB_MCP_ALLOWED_ORIGINS=http://localhost:3000 TAB_MCP_STORE=memory tab-mcp
+```
+
+## Configuration
+
+Environment variables, all listed by `tab-mcp --help` and in
+[configuration](https://github.com/ractive/tab-mcp/blob/main/docs/configuration.md).
+The most important:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `TAB_MCP_PUBLIC_URL` | required | the relay's public origin; `https:` outside development |
+| `TAB_MCP_ALLOWED_ORIGINS` | empty: no page may connect | comma-separated page origins; `*` makes an open relay (read the warning in the docs first) |
+| `TAB_MCP_SITES` | empty | JSON array of sites with their own app name or limits |
+| `TAB_MCP_STORE` | `sqlite` | `sqlite` or `memory` |
+| `TAB_MCP_SQLITE_PATH` | `tab-mcp.db` | the SQLite file for grants and token hashes |
+| `TAB_MCP_TRUST_PROXY` | `none` | `x-real-ip` or `x-forwarded-for` behind a proxy |
+| `TAB_MCP_PORT` | `8080` | listen port |
+
+`GET /healthz` answers `200` with the version, for health checks.
+
+## Use it as a library
+
+```ts
+import { createRelay } from "@ractive-ch/tab-mcp";
+
+const relay = createRelay({
+  publicUrl: "https://relay.example.com",
+  allowedOrigins: ["https://app.example.com"],
+  store: "sqlite",
+  sqlitePath: "/var/lib/tab-mcp/tab-mcp.db",
+});
+console.log(`listening on port ${relay.port}`);
+
+process.on("SIGTERM", () => relay.stop().then(() => process.exit(0)));
+```
+
+`createRelay(options)` starts the server and returns once it listens. The options mean
+the same as the environment variables, with camel-case names, milliseconds instead of
+seconds and arrays instead of comma-separated lists (`allowedOrigins`, `sites`,
+`maxSessionsPerIp`, `requestTimeoutMs`, `maxMessageBytes`, …), plus:
+
+- `store`: `"sqlite"` (default), `"memory"`, or your own `TokenStore` object;
+- `logger`: your own logger; by default JSON lines on stdout.
+
+The returned `Relay` has `url`, `port`, `config`, `sessionCount`, `addressFor(secret)`
+and `stop()`, which sends `bye` to every page (close code 4004) and stops the server.
+
+The package also exports `MemoryTokenStore`, `SqliteTokenStore`, the `TokenStore` types,
+`configFromEnv`, `resolveConfig`, `DEFAULT_CONFIG`, `createLogger`, `SUBPROTOCOL`
+(`tab-mcp.v1`) and `VERSION`.
+
+### Your own token store
+
+A store keeps grants and the SHA-256 hashes of tokens, never the tokens. Check yours with
+the conformance suite for `bun test`:
+
+```ts
+import { tokenStoreConformance } from "@ractive-ch/tab-mcp/testing";
+import { MyTokenStore } from "./my-token-store.ts";
+
+tokenStoreConformance("MyTokenStore", () => new MyTokenStore());
+```
+
+[Token store](https://github.com/ractive/tab-mcp/blob/main/docs/token-store.md) explains
+the interface, its guarantees and a Redis example.
+
+## Security
+
+Connecting an AI app to a page means trusting that page, as with any MCP server. The
+relay operator can read every tool argument and result; the relay does not log them.
+Report vulnerabilities privately as described in
+[SECURITY.md](https://github.com/ractive/tab-mcp/blob/main/SECURITY.md). The
+[threat model](https://github.com/ractive/tab-mcp/blob/main/docs/threat-model.md) covers
+the details.
+
+## More
+
+- [Repository and overview](https://github.com/ractive/tab-mcp)
+- [Tab–relay protocol](https://github.com/ractive/tab-mcp/blob/main/docs/protocol.md)
+- [Changelog](https://github.com/ractive/tab-mcp/blob/main/CHANGELOG.md)
+
+## Licence
+
+MIT, see [LICENSE](LICENSE) and [AI_NOTICE](AI_NOTICE).

package/index.d.ts

@@ -9,4 +9,4 @@ export { SUBPROTOCOL } from "./protocol.js";
 export { type CreateRelayOptions, createRelay, type Relay, VERSION, } from "./relay.js";
 export { MemoryTokenStore } from "./store/memory.js";
 export { SqliteTokenStore } from "./store/sqlite.js";
-export type { GrantSummary, RevokeSelector, TokenKind, TokenRecord, TokenStore, } from "./store/types.js";
+export type { GrantSummary, RevokeOptions, RevokeSelector, TokenKind, TokenRecord, TokenStore, } from "./store/types.js";

package/index.js

@@ -708,7 +708,7 @@ function parseTabMessage(text) {
   }
 }
 // package.json
-var version = "0.1.0-alpha.0";
+var version = "0.1.0";
 
 // src/exchange.ts
 var RelayErrorCode = {
@@ -1461,7 +1461,7 @@ function renderPage(title, body) {
 <body>
 <main>
 ${body}
-<footer>tab-mcp relay. It passes requests between AI tools and web pages and does not store their contents.</footer>
+<footer>tab-mcp relay. It passes requests between AI apps and web pages and does not store their contents.</footer>
 </main>
 </body>
 </html>`;
@@ -1562,7 +1562,7 @@ var MESSAGES = {
   wrong: "That code is not right. Check the code shown in the page and try again.",
   expired: "That code has expired. The page now shows a new code: enter that one.",
   locked: "Too many wrong codes. The page now shows a new code: enter that one.",
-  inactive: "The page is not showing a code right now. In the page, open \u201CConnect your AI tool\u201D to see one, then enter it here.",
+  inactive: "The page is not showing a code right now. In the page, open \u201CConnect your AI app\u201D to see one, then enter it here.",
   malformed: "Enter the 6 digits shown in the page.",
   limited: "Too many attempts for this page. Wait a few minutes and try again. If it keeps happening, someone else may be guessing: use \u201CNew address\u201D in the page."
 };
@@ -1571,7 +1571,7 @@ var codePairing = {
   render() {
     return `<p><label for="code">Code shown in the page</label>
 <input id="code" name="code" type="text" inputmode="numeric" autocomplete="one-time-code" pattern="[0-9 ]{6,7}" maxlength="7" required autofocus aria-describedby="code-help"></p>
-<p id="code-help" class="help">In the page, \u201CConnect your AI tool\u201D shows a 6-digit code. It changes every 2 minutes.</p>`;
+<p id="code-help" class="help">In the page, \u201CConnect your AI app\u201D shows a 6-digit code. It changes every 2 minutes.</p>`;
   },
   check(target, form, admit) {
     const result = target.codes.check(form.get("code") ?? "", Date.now(), admit);
@@ -1768,7 +1768,7 @@ class AuthorizationServer {
   #errorPage(status, message) {
     return this.#page(status, "This connection cannot be made", `<h1>This connection cannot be made</h1>
 <p role="alert">${escapeHtml(message)}</p>
-<p>Go back to your AI tool and try again. If it keeps happening, the AI tool may not work with this relay.</p>`);
+<p>Go back to your AI app and try again. If it keeps happening, the AI app may not work with this relay.</p>`);
   }
   #errorUrl(redirectUri, state, error, description) {
     const url = new URL(redirectUri);
@@ -1786,8 +1786,8 @@ class AuthorizationServer {
     const url = this.#errorUrl(redirectUri, state, error, description);
     const host = hostOf(redirectUri);
     return this.#page(400, "This connection cannot be made", `<h1>This connection cannot be made</h1>
-<p role="alert">The AI tool sent a request this relay cannot accept: ${escapeHtml(description)} (${escapeHtml(error)}).</p>
-<p>You can go back to the AI tool at ${escapeHtml(host)} to tell it, or close this page.</p>
+<p role="alert">The AI app sent a request this relay cannot accept: ${escapeHtml(description)} (${escapeHtml(error)}).</p>
+<p>You can go back to the AI app at ${escapeHtml(host)} to tell it, or close this page.</p>
 <div class="actions"><a class="button" href="${escapeHtml(url)}">Go back to ${escapeHtml(host)}</a></div>`);
   }
   #redirectError(redirectUri, state, error, description) {
@@ -1937,7 +1937,7 @@ class AuthorizationServer {
     const body = `<h1>Open the page first</h1>
 ${errorHtml}
 <p><strong>${escapeHtml(client.name)}</strong> (${escapeHtml(client.host)}) wants to use the tools of a web page, but that page is not open right now.</p>
-<p>Open the page, click \u201CConnect your AI tool\u201D, then try again here.</p>
+<p>Open the page, click \u201CConnect your AI app\u201D, then try again here.</p>
 <div class="actions">
 <a class="button primary" href="${escapeHtml(retryUrl)}">Try again</a>
 <a class="button" href="${escapeHtml(cancelUrl)}">Cancel</a>
@@ -1951,7 +1951,7 @@ ${errorHtml}
       return this.#errorPage(403, "This form can only be sent from this page.");
     }
     if (!this.#attemptsPerIp.take(ip)) {
-      return this.#errorPage(429, "Too many attempts from your network. Wait a few minutes, then start again from your AI tool.");
+      return this.#errorPage(429, "Too many attempts from your network. Wait a few minutes, then start again from your AI app.");
     }
     const type = (req.headers.get("content-type") ?? "").split(";")[0]?.trim();
     if (type !== "application/x-www-form-urlencoded") {
@@ -2090,7 +2090,7 @@ ${errorHtml}
       const body = `<h1>Open the page first</h1>
 ${errorHtml}
 <p>${clientLabel} wants to use the tools of a web page, but that page is not open right now.</p>
-<p>Open the page, click \u201CConnect your AI tool\u201D, then try again here.</p>
+<p>Open the page, click \u201CConnect your AI app\u201D, then try again here.</p>
 <form method="post" action="/authorize">
 ${hidden}
 <div class="actions">
@@ -2119,7 +2119,7 @@ ${method.render(session)}
 ${cancel}
 </div>
 </form>
-<p class="help">After you connect, your browser goes back to ${escapeHtml(hostOf(pending.redirectUri))}. Only connect AI tools you started yourself.</p>`;
+<p class="help">After you connect, your browser goes back to ${escapeHtml(hostOf(pending.redirectUri))}. Only connect AI apps you started yourself.</p>`;
     return this.#page(status, heading, body, targets, extra);
   }
   async token(req, ip) {
@@ -3332,7 +3332,7 @@ function startRelay(options, hooks) {
     const session = sessions.get(addressId);
     if (session === undefined || !session.ready) {
       logDone(503, method, { reason: "page_not_open" });
-      return rpcError(503, rpcId, RelayErrorCode.pageNotOpen, 'The page is not open. Open the web page that offers these tools and click "Connect your AI tool".', corsHeaders);
+      return rpcError(503, rpcId, RelayErrorCode.pageNotOpen, 'The page is not open. Open the web page that offers these tools and click "Connect your AI app".', corsHeaders);
     }
     if (session.pending.size >= session.limits.maxConcurrentRequests) {
       logDone(429, method);
@@ -3554,5 +3554,5 @@ export {
   resolveConfig
 };
 
-//# debugId=ACF1F76550B2129B64756E2164756E21
+//# debugId=0BEEC7645167157064756E2164756E21
 //# sourceMappingURL=index.js.map