@ractive-ch/tab-mcp 0.1.0 → 0.2.1

package/README.md

@@ -10,7 +10,7 @@ and gets an MCP address. The user adds that address to an AI app and pairs it by
 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.
+**Status: 0.2.1.** 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.
@@ -32,7 +32,7 @@ Or with Docker (linux/amd64 and linux/arm64):
 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
+  ractive/tab-mcp:0.2.1
 ```
 
 The image is also on `ghcr.io/ractive/tab-mcp`. Put the relay behind a reverse proxy

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.js

@@ -38,6 +38,7 @@ function shortAddress(id) {
 }
 // src/config.ts
 var MIN_MESSAGE_BYTES = 16384;
+var MAX_PAGE_WAIT_MS = 60000;
 var MAX_APP_NAME = 64;
 var DEFAULT_CONFIG = {
   port: 8080,
@@ -59,6 +60,7 @@ var DEFAULT_CONFIG = {
   heartbeatMs: 25000,
   helloTimeoutMs: 1e4,
   bodyTimeoutMs: 1e4,
+  pageWaitMs: 1e4,
   maxMessageBytes: 1048576,
   accessTokenTtlMs: 3600000,
   refreshTokenTtlMs: 2592000000,
@@ -142,6 +144,9 @@ function resolveConfig(input = {}) {
       throw new ConfigError(`${key} must be a positive number`);
     }
   }
+  if (typeof config.pageWaitMs !== "number" || !Number.isFinite(config.pageWaitMs) || config.pageWaitMs < 0 || config.pageWaitMs > MAX_PAGE_WAIT_MS) {
+    throw new ConfigError(`pageWaitMs must be 0-${MAX_PAGE_WAIT_MS} (0-${MAX_PAGE_WAIT_MS / 1000} seconds)`);
+  }
   if (config.maxMessageBytes < MIN_MESSAGE_BYTES) {
     throw new ConfigError(`maxMessageBytes must be at least ${MIN_MESSAGE_BYTES} (16 KiB)`);
   }
@@ -265,6 +270,16 @@ function seconds(env, name) {
   }
   return Math.round(n * 1000);
 }
+function secondsOrZero(env, name) {
+  const raw = env[name];
+  if (raw === undefined || raw === "")
+    return;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) {
+    throw new ConfigError(`${name} must be 0 or a positive number of seconds`);
+  }
+  return Math.round(n * 1000);
+}
 function integer(env, name) {
   const raw = env[name];
   if (raw === undefined || raw === "")
@@ -341,6 +356,7 @@ function configFromEnv(env) {
   set("sessionLifetimeMs", seconds(env, "TAB_MCP_SESSION_LIFETIME_S"));
   set("heartbeatMs", seconds(env, "TAB_MCP_HEARTBEAT_S"));
   set("bodyTimeoutMs", seconds(env, "TAB_MCP_BODY_TIMEOUT_S"));
+  set("pageWaitMs", secondsOrZero(env, "TAB_MCP_PAGE_WAIT_S"));
   set("maxMessageBytes", integer(env, "TAB_MCP_MAX_MESSAGE_BYTES"));
   set("accessTokenTtlMs", seconds(env, "TAB_MCP_ACCESS_TOKEN_TTL_S"));
   set("refreshTokenTtlMs", seconds(env, "TAB_MCP_REFRESH_TOKEN_TTL_S"));
@@ -708,7 +724,7 @@ function parseTabMessage(text) {
   }
 }
 // package.json
-var version = "0.1.0";
+var version = "0.2.1";
 
 // src/exchange.ts
 var RelayErrorCode = {
@@ -866,6 +882,31 @@ class Exchange {
     this.#options.cancel("client_closed");
     this.#finish("client_closed", false);
   }
+  tabGone() {
+    if (this.#state === "done")
+      return;
+    const waiting = this.#state === "waiting";
+    const reply = this.#options.pageGone?.(waiting);
+    if (reply?.retry === true && waiting) {
+      clearTimeout(this.#startTimer);
+      this.#finish("page_gone_retry");
+      return;
+    }
+    const body = reply?.retry === false ? reply.body : undefined;
+    if (body === undefined) {
+      this.fail(503, RelayErrorCode.tabGone, "The page closed its connection to the relay.", false);
+      return;
+    }
+    if (waiting) {
+      this.#respond(new Response(body, {
+        status: 200,
+        headers: this.#headers({ "content-type": "application/json" })
+      }), 200);
+    } else if (this.#atBoundary) {
+      this.#write(sseEvent(body));
+    }
+    this.#finish("page_gone");
+  }
   fail(status, code, message, cancelTab) {
     if (this.#state === "done")
       return;
@@ -1004,6 +1045,67 @@ class Exchange {
   }
 }
 
+// src/notopen.ts
+var RETRYABLE = new Set(["tools/list"]);
+function isRetryable(method) {
+  return typeof method === "string" && RETRYABLE.has(method);
+}
+function pageName(appName) {
+  return appName ?? "the web page";
+}
+function notOpenText(appName) {
+  return `The page is not open, or not in front. Ask the user to open ${pageName(appName)} and keep it in front (on a phone, in split screen), then try again.`;
+}
+function goneDuringCallText(appName) {
+  return `The page closed while the tool was running, so it may or may not have finished. Ask the user to open ${pageName(appName)} and keep it in front (on a phone, in split screen), then check the result before trying again.`;
+}
+function notOpenAnswer(body, rpcId, appName, phase, relay) {
+  if (rpcId === undefined)
+    return;
+  const id = rpcId;
+  const method = body["method"];
+  if (method === "tools/call") {
+    const text = phase === "gone" ? goneDuringCallText(appName) : notOpenText(appName);
+    return JSON.stringify({
+      jsonrpc: "2.0",
+      id,
+      result: {
+        resultType: "complete",
+        content: [{ type: "text", text }],
+        isError: true
+      }
+    });
+  }
+  if (method === "server/discover") {
+    return JSON.stringify({
+      jsonrpc: "2.0",
+      id,
+      result: {
+        resultType: "complete",
+        supportedVersions: [MCP_PROTOCOL_VERSION],
+        capabilities: { tools: { listChanged: true } },
+        instructions: notOpenText(appName),
+        ttlMs: 0,
+        cacheScope: "private",
+        _meta: {
+          "io.modelcontextprotocol/serverInfo": {
+            name: relay.name,
+            version: relay.version
+          }
+        }
+      }
+    });
+  }
+  return JSON.stringify({
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code: phase === "gone" ? RelayErrorCode.tabGone : RelayErrorCode.pageNotOpen,
+      message: notOpenText(appName)
+    }
+  });
+}
+
 // src/oauth/server.ts
 import { timingSafeEqual as timingSafeEqual2 } from "crypto";
 
@@ -2669,6 +2771,7 @@ class TabSession {
       library: `${library.name}@${library.version}`,
       replaced: replaced !== undefined
     });
+    this.#host.ready?.(this);
   }
   #tick() {
     if (this.#state !== "ready")
@@ -2707,7 +2810,8 @@ class TabSession {
         this.pending.delete(id);
         this.#lastRequestAt = Date.now();
         input.onDone(e);
-      }
+      },
+      ...input.pageGone === undefined ? {} : { pageGone: input.pageGone }
     });
     this.pending.set(id, exchange);
     const sent = this.send({
@@ -2746,10 +2850,9 @@ class TabSession {
     clearTimeout(this.#helloTimer);
     clearInterval(this.#heartbeatTimer);
     clearTimeout(this.#lifetimeTimer);
-    for (const exchange of [...this.pending.values()]) {
-      exchange.fail(503, RelayErrorCode.tabGone, "The page closed its connection to the relay.", false);
-    }
     this.#host.released(this);
+    for (const exchange of [...this.pending.values()])
+      exchange.tabGone();
     if (wasReady) {
       this.#host.logger.info("tab.closed", {
         session: this.sessionId,
@@ -3001,6 +3104,8 @@ class SqliteTokenStore {
 
 // src/relay.ts
 var VERSION = version;
+var RELAY_INFO = { name: "tab-mcp", version };
+var RETRY = Symbol("retry");
 var CLAUDE_MISMATCHED_HEADER = "2025-11-25";
 var FORWARDED_HEADERS = new Set([
   "content-type",
@@ -3061,6 +3166,9 @@ function startRelay(options, hooks) {
   const sessions = new Map;
   const allSessions = new Set;
   const perIp = new Map;
+  const waiters = new Map;
+  let waitingCount = 0;
+  const appNames = new Map;
   let claudeWorkarounds = 0;
   let publicUrl = config.publicUrl ?? "";
   const corsHeaders = config.cors ? {
@@ -3124,8 +3232,68 @@ function startRelay(options, hooks) {
         sessions.delete(session.addressId);
       }
       releaseIp(session.ip);
+    },
+    ready(session) {
+      const id = session.addressId;
+      if (id === undefined)
+        return;
+      if (session.appName !== undefined) {
+        appNames.delete(id);
+        appNames.set(id, session.appName);
+        if (appNames.size > config.maxSessions * 2) {
+          const oldest = appNames.keys().next().value;
+          if (oldest !== undefined)
+            appNames.delete(oldest);
+        }
+      }
+      const waiting = waiters.get(id);
+      if (waiting !== undefined)
+        for (const wake of [...waiting])
+          wake(session);
     }
   };
+  function readySession(addressId) {
+    const s = sessions.get(addressId);
+    return s?.ready === true ? s : undefined;
+  }
+  function waitForPage(addressId, signal, waitMs) {
+    const now = readySession(addressId);
+    if (now !== undefined)
+      return Promise.resolve(now);
+    if (waitMs === 0 || stopping !== undefined) {
+      return Promise.resolve(undefined);
+    }
+    const set = waiters.get(addressId) ?? new Set;
+    if (set.size >= config.maxConcurrentRequests || waitingCount >= config.maxSessions) {
+      return Promise.resolve(undefined);
+    }
+    return new Promise((resolve) => {
+      let timer;
+      let settled = false;
+      const done = (result) => {
+        if (settled)
+          return;
+        settled = true;
+        clearTimeout(timer);
+        signal.removeEventListener("abort", onAbort);
+        set.delete(wake);
+        waitingCount--;
+        if (set.size === 0 && waiters.get(addressId) === set) {
+          waiters.delete(addressId);
+        }
+        resolve(result);
+      };
+      const wake = (session) => done(session);
+      const onAbort = () => done("aborted");
+      set.add(wake);
+      waiters.set(addressId, set);
+      waitingCount++;
+      timer = setTimeout(() => done(undefined), waitMs);
+      signal.addEventListener("abort", onAbort, { once: true });
+      if (signal.aborted)
+        onAbort();
+    });
+  }
   function releaseIp(ip) {
     const n = (perIp.get(ip) ?? 1) - 1;
     if (n <= 0)
@@ -3329,15 +3497,6 @@ function startRelay(options, hooks) {
         "www-authenticate": wwwAuthenticate(addressId, auth === "invalid")
       });
     }
-    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 app".', corsHeaders);
-    }
-    if (session.pending.size >= session.limits.maxConcurrentRequests) {
-      logDone(429, method);
-      return rpcError(429, rpcId, RelayErrorCode.overloaded, "Too many requests at once for this page.", corsHeaders);
-    }
     const headers = {};
     for (const [k, v] of req.headers) {
       const key = k.toLowerCase();
@@ -3352,33 +3511,89 @@ function startRelay(options, hooks) {
         return "";
       }
     })();
-    if (req.signal.aborted) {
+    const isListen = body.value["method"] === "subscriptions/listen";
+    const waitMs = body.value["method"] === "server/discover" || Buffer.byteLength(body.text) > MIN_MESSAGE_BYTES ? 0 : config.pageWaitMs;
+    const closed = () => {
       logDone(499, method, { outcome: "client_closed" });
       return new Response(null, { status: 499 });
+    };
+    if (readySession(addressId) === undefined && waitMs > 0) {
+      server.timeout(req, 0);
     }
-    server.timeout(req, 0);
-    const exchange = session.forward({
-      method: "POST",
-      headers,
-      body: body.text,
-      rpcId,
-      isListen: body.value["method"] === "subscriptions/listen",
-      grant: {
-        grantId: auth.grantId,
-        clientId: auth.clientId,
-        scopes: auth.scopes
-      },
-      extraHeaders: corsHeaders,
-      onDone: (e) => logDone(e.status, method, {
-        session: session.sessionId,
-        client: clientHostName,
-        outcome: e.outcome
-      })
-    });
-    req.signal.addEventListener("abort", () => exchange.clientClosed(), {
-      once: true
+    let retried = false;
+    for (;; ) {
+      const found = await waitForPage(addressId, req.signal, waitMs);
+      if (found === "aborted" || req.signal.aborted)
+        return closed();
+      if (found === undefined) {
+        return pageNotOpen(body.value, rpcId, addressId, logDone, method);
+      }
+      const session = found;
+      if (Buffer.byteLength(body.text) > session.limits.maxMessageBytes) {
+        logDone(413, method);
+        return rpcError(413, rpcId, -32600, "Request body too large.", corsHeaders);
+      }
+      if (session.pending.size >= session.limits.maxConcurrentRequests) {
+        logDone(429, method);
+        return rpcError(429, rpcId, RelayErrorCode.overloaded, "Too many requests at once for this page.", corsHeaders);
+      }
+      server.timeout(req, 0);
+      let retry = () => {};
+      const retrying = new Promise((resolve) => {
+        retry = () => resolve(RETRY);
+      });
+      const mayRetry = !retried && waitMs > 0 && isRetryable(body.value["method"]);
+      const exchange = session.forward({
+        method: "POST",
+        headers,
+        body: body.text,
+        rpcId,
+        isListen,
+        grant: {
+          grantId: auth.grantId,
+          clientId: auth.clientId,
+          scopes: auth.scopes
+        },
+        extraHeaders: corsHeaders,
+        onDone: (e) => {
+          if (e.outcome === "page_gone_retry")
+            return;
+          logDone(e.status, method, {
+            session: session.sessionId,
+            client: clientHostName,
+            outcome: e.outcome,
+            ...e.outcome === "page_gone" ? { reason: "page_not_open" } : {}
+          });
+        },
+        pageGone: (waiting) => {
+          if (waiting && mayRetry && !req.signal.aborted) {
+            retry();
+            return { retry: true };
+          }
+          const answer = notOpenAnswer(body.value, rpcId, session.appName, "gone", RELAY_INFO);
+          return answer === undefined ? { retry: false } : { retry: false, body: answer };
+        }
+      });
+      const onAbort = () => exchange.clientClosed();
+      req.signal.addEventListener("abort", onAbort, { once: true });
+      const result = await Promise.race([exchange.response, retrying]);
+      if (result !== RETRY)
+        return result;
+      req.signal.removeEventListener("abort", onAbort);
+      retried = true;
+    }
+  }
+  function pageNotOpen(value, rpcId, addressId, logDone, method) {
+    const answer = notOpenAnswer(value, rpcId, appNames.get(addressId), "not_open", RELAY_INFO);
+    if (answer === undefined) {
+      logDone(503, method, { reason: "page_not_open" });
+      return rpcError(503, rpcId, RelayErrorCode.pageNotOpen, "The page is not open.", corsHeaders);
+    }
+    logDone(200, method, { reason: "page_not_open" });
+    return new Response(answer, {
+      status: 200,
+      headers: { ...corsHeaders, "content-type": "application/json" }
     });
-    return exchange.response;
   }
   function preflight(req) {
     if (!config.cors)
@@ -3413,14 +3628,15 @@ function startRelay(options, hooks) {
           status: "ok",
           version: VERSION,
           counters: { claudeHeaderWorkaround: claudeWorkarounds }
-        })
+        }, { "cache-control": "no-store" })
       },
       "/": {
         GET: () => new Response(INDEX_HTML, {
           headers: {
             "content-type": "text/html; charset=utf-8",
             "content-security-policy": "default-src 'none'; frame-ancestors 'none'",
-            "x-content-type-options": "nosniff"
+            "x-content-type-options": "nosniff",
+            "cache-control": "public, max-age=3600"
           }
         })
       },
@@ -3484,6 +3700,7 @@ function startRelay(options, hooks) {
       }
     }
   });
+  let stopping;
   const port = server.port ?? config.port;
   if (publicUrl === "")
     publicUrl = `http://localhost:${port}`;
@@ -3514,7 +3731,6 @@ function startRelay(options, hooks) {
     store: ownsStore ? config.store : "custom",
     origins: siteCount
   });
-  let stopping;
   return {
     url: publicUrl,
     port,
@@ -3526,6 +3742,10 @@ function startRelay(options, hooks) {
     stop() {
       stopping ??= (async () => {
         clearInterval(sweep);
+        for (const set of [...waiters.values()]) {
+          for (const wake of [...set])
+            wake(undefined);
+        }
         for (const session of [...allSessions]) {
           session.end(CloseCode.shuttingDown, "relay shutting down", "shutdown");
         }
@@ -3554,5 +3774,5 @@ export {
   resolveConfig
 };
 
-//# debugId=0BEEC7645167157064756E2164756E21
+//# debugId=819DDD907387E9BC64756E2164756E21
 //# sourceMappingURL=index.js.map