@ractive-ch/tab-mcp 0.1.0-alpha.1 → 0.2.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.2.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.2.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/config.d.ts

@@ -45,6 +45,8 @@ export interface Site {
  * chunk (below 896 bytes).
  */
 export declare const MIN_MESSAGE_BYTES = 16384;
+/** Longest grace period for a page to (re)connect (DEC-074). */
+export declare const MAX_PAGE_WAIT_MS = 60000;
 /** Longest app name (configured or sent by the page). */
 export declare const MAX_APP_NAME = 64;
 export interface RelayConfig {
@@ -77,6 +79,11 @@ export interface RelayConfig {
     helloTimeoutMs: number;
     /** Deadline for receiving an MCP request body (Bun's idle timer does not cover it). */
     bodyTimeoutMs: number;
+    /**
+     * How long an MCP request waits for its page to (re)connect before the relay
+     * answers "the page is not open" (DEC-074); 0 answers at once.
+     */
+    pageWaitMs: number;
     /** Limit for MCP request bodies and for messages from the tab. */
     maxMessageBytes: number;
     accessTokenTtlMs: number;

package/exchange.d.ts

@@ -17,6 +17,18 @@ export declare const RelayErrorCode: {
     readonly storeUnavailable: -31008;
 };
 export type CancelReason = "client_closed" | "timeout" | "error";
+/**
+ * What to do when the page goes away mid-request (DEC-074): send the request
+ * to the page again once it is back (only while nothing was sent to the AI
+ * app), or answer with this JSON-RPC message at HTTP 200 (`undefined` for a
+ * notification: then 503).
+ */
+export type PageGoneReply = {
+    retry: true;
+} | {
+    retry: false;
+    body?: string;
+};
 export interface ExchangeOptions {
     id: string;
     /** JSON-RPC id of the request; `undefined` for a notification. */
@@ -36,6 +48,11 @@ export interface ExchangeOptions {
     cancel: (reason: CancelReason) => void;
     /** Called once when the exchange is over. */
     onDone: (exchange: Exchange) => void;
+    /**
+     * Decides the answer when the page goes away mid-request; `waiting` is true
+     * while nothing was sent to the AI app. Without it: 503, `-31003`.
+     */
+    pageGone?: (waiting: boolean) => PageGoneReply;
 }
 /** One SSE `message` event carrying `data` (split into `data:` lines). */
 export declare function sseEvent(data: string): string;
@@ -60,6 +77,12 @@ export declare class Exchange {
     onEnd(): void;
     /** The AI app went away: tell the tab, send nothing more. */
     clientClosed(): void;
+    /**
+     * The page's session ended. With a retry the exchange ends without an
+     * answer (its `response` never settles; the relay sends the request again),
+     * else the AI app gets the `pageGone` answer at HTTP 200 (DEC-074).
+     */
+    tabGone(): void;
     /**
      * End the exchange with an error the AI app can read: an HTTP error while
      * nothing was sent, else a JSON-RPC error event if the stream is at an

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";