@softure-ai/mcp-access 0.3.0 → 0.5.0

package/src/server/endpoint.ts

@@ -19,6 +19,14 @@ import { getProtectedResourceMetadataUrl, isOAuthEnabled } from "./oauth-http.js
 import { resolveMcpOrigins } from "./origins.js";
 import { MCP_READ_SCOPE, MCP_WRITE_SCOPE } from "./scopes.js";
 import { verifyAccessToken, type McpAccessContext } from "./tokens.js";
+import {
+  createSessionRenewalResponse,
+  createToolListSessionId,
+  isInitializeRequest,
+  isToolListSessionCurrent,
+  MCP_SESSION_ID_HEADER,
+  rewriteInitializeAnswer,
+} from "./tool-list-session.js";
 import { isWritingEnabled } from "./writes-switch.js";
 
 export { MCP_READ_SCOPE, MCP_WRITE_SCOPE };
@@ -37,8 +45,21 @@ const NO_STORE = { "cache-control": "no-store" };
 /** The app's MCP server for one request. It registers write tools only when `canWrite` is true. */
 export type McpServerFactory = (identity: McpServerIdentity) => McpServer | Server | Promise<McpServer | Server>;
 
+/** Reads the tool list version the factory's servers answer at `initialize` for the identity. */
+export type ToolListVersionReader = (identity: McpServerIdentity) => Promise<string>;
+
+/** A factory that can tell its tool list version without building a server; `createMcpServerFactory` returns one. */
+export interface VersionedMcpServerFactory extends McpServerFactory {
+  readonly toolListVersion: ToolListVersionReader;
+}
+
 export interface McpEndpointOptions {
-  readonly createServer: McpServerFactory;
+  readonly createServer: McpServerFactory | VersionedMcpServerFactory;
+  /**
+   * The tool list version per identity, for sessions tied to it (#1055). Default: the factory's own
+   * `toolListVersion` (`createMcpServerFactory`). Without either, the endpoint issues no session id.
+   */
+  readonly toolListVersion?: ToolListVersionReader;
 }
 
 /** Serves one request to the MCP endpoint. */
@@ -50,7 +71,8 @@ export type McpEndpoint = (ctx: McpAccessContext, request: Request) => Promise<R
  * (`responseMode: "json"`): a stream would add proxy buffering and timeouts for no tool that needs
  * it, and mid-call notifications are dropped.
  */
-export function createMcpEndpoint({ createServer }: McpEndpointOptions): McpEndpoint {
+export function createMcpEndpoint({ createServer, toolListVersion }: McpEndpointOptions): McpEndpoint {
+  const readToolListVersion = toolListVersion ?? getFactoryToolListVersion(createServer);
   const handler = createMcpHandler(
     (requestContext) => createServer(readIdentity(requestContext.authInfo)),
     {
@@ -83,8 +105,40 @@ export function createMcpEndpoint({ createServer }: McpEndpointOptions): McpEndp
 
     const authInfo = await authenticate(ctx, request);
     if (authInfo instanceof Response) return authInfo;
-    return handler.fetch(request, { authInfo });
+    return serveInSession(request, authInfo);
   };
+
+  /**
+   * Sessions tied to the tool list version (#1055): a session from another version (a release changed a tool, or the
+   * access level changed) answers 404, so the client initializes again and lists the tools again; `initialize` gets a
+   * new session id. A request without a session id is served as it always was.
+   */
+  async function serveInSession(request: Request, authInfo: AuthInfo): Promise<Response> {
+    const sessionId = request.headers.get(MCP_SESSION_ID_HEADER);
+    const isInitialize = sessionId === null && (await isInitializeRequest(request, MAX_MCP_REQUEST_BYTES));
+    if (readToolListVersion === undefined || (sessionId === null && !isInitialize)) {
+      const response = await handler.fetch(request, { authInfo });
+      return isInitialize ? rewriteInitializeAnswer(response, null) : response;
+    }
+    let version;
+    try {
+      version = await readToolListVersion(readIdentity(authInfo));
+    } catch (error) {
+      // Without the version no session can be checked or issued: serve the request statelessly, as before #1055.
+      console.error(`@softure-ai/mcp-access: reading the tool list version failed: ${errorLogLabel(error)}`);
+      const response = await handler.fetch(request, { authInfo });
+      return isInitialize ? rewriteInitializeAnswer(response, null) : response;
+    }
+    if (sessionId !== null) {
+      return isToolListSessionCurrent(sessionId, version) ? handler.fetch(request, { authInfo }) : createSessionRenewalResponse();
+    }
+    return rewriteInitializeAnswer(await handler.fetch(request, { authInfo }), createToolListSessionId(version));
+  }
+}
+
+/** The factory's own version reader, when it has one (`createMcpServerFactory`). */
+function getFactoryToolListVersion(factory: McpServerFactory | VersionedMcpServerFactory): ToolListVersionReader | undefined {
+  return "toolListVersion" in factory && typeof factory.toolListVersion === "function" ? factory.toolListVersion : undefined;
 }
 
 /**

package/src/server/index.ts

@@ -9,6 +9,8 @@ export {
   type McpEndpoint,
   type McpEndpointOptions,
   type McpServerFactory,
+  type ToolListVersionReader,
+  type VersionedMcpServerFactory,
 } from "./endpoint.js";
 export { actionTool, toFormData, type ActionToolOptions, type FormActionHandler } from "./action-tool.js";
 export {
@@ -155,6 +157,12 @@ export {
   type ServedTool,
   type ToolListMeasurement,
 } from "./tool-list.js";
+export {
+  createToolListSessionId,
+  isToolListSessionCurrent,
+  MCP_SESSION_ID_HEADER,
+  readToolListSessionVersion,
+} from "./tool-list-session.js";
 export {
   toolError,
   toolResult,

package/src/server/server-factory.ts

@@ -10,7 +10,7 @@
 //   });
 import { McpServer, type McpServerOptions } from "@modelcontextprotocol/server";
 import type { McpServerIdentity } from "../contract.js";
-import type { McpServerFactory } from "./endpoint.js";
+import type { VersionedMcpServerFactory } from "./endpoint.js";
 import { withStrictToolInput, type StrictToolInputOptions } from "./strict-input.js";
 import { registerServerInfoTool, type ServerInfoToolOptions } from "./server-info.js";
 import { measureToolList, type ToolListMeasurement } from "./tool-list.js";
@@ -39,8 +39,12 @@ export interface McpServerFactoryOptions {
   readonly serverInfoTool?: ServerInfoToolOptions;
 }
 
-/** An `McpServerFactory` whose servers carry the tool list's version for the identity's access level. */
-export function createMcpServerFactory(options: McpServerFactoryOptions): McpServerFactory {
+/**
+ * An `McpServerFactory` whose servers carry the tool list's version for the identity's access level. Its
+ * `toolListVersion(identity)` reads that version without building a server, so `createMcpEndpoint` ties each session
+ * to it (#1055).
+ */
+export function createMcpServerFactory(options: McpServerFactoryOptions): VersionedMcpServerFactory {
   const strictOptions = options.strictToolInput === true ? {} : options.strictToolInput === false ? undefined : options.strictToolInput;
   // The served version reaches `get_server_info` here; the recording server registers it with a placeholder, since
   // its handler never runs there and the version is not part of the listed tool.
@@ -66,8 +70,9 @@ export function createMcpServerFactory(options: McpServerFactoryOptions): McpSer
     return measurement;
   };
 
-  return async (identity) => {
-    const version = options.version ?? (await measure(identity)).toolListVersion;
+  const toolListVersion = async (identity: McpServerIdentity): Promise<string> => options.version ?? (await measure(identity)).toolListVersion;
+  const factory = async (identity: McpServerIdentity): Promise<McpServer> => {
+    const version = await toolListVersion(identity);
     const server = new McpServer(
       { name: options.name, version, ...(options.title === undefined ? {} : { title: options.title }) },
       options.serverOptions,
@@ -75,4 +80,5 @@ export function createMcpServerFactory(options: McpServerFactoryOptions): McpSer
     await registerTools(server, identity, version);
     return server;
   };
+  return Object.assign(factory, { toolListVersion });
 }

package/src/server/tool-list-session.ts

@@ -0,0 +1,103 @@
+// Sessions tied to the tool list version (#1055). A hosted client keeps its cached `tools/list` for as long as its
+// connection lives, even after a release changed a tool, and the endpoint has no channel to send
+// `notifications/tools/list_changed`. So the endpoint answers `initialize` with an `Mcp-Session-Id` that carries the
+// tool list version of the identity's access level, and a later request whose session carries another version gets
+// `404 Not Found`: Streamable HTTP defines that as "start a new session", so the client initializes again and lists
+// the tools again. Nothing is stored: the id itself holds the version, so any instance can check it.
+import { randomBytes } from "node:crypto";
+
+/** The header that carries the session id, both ways. */
+export const MCP_SESSION_ID_HEADER = "mcp-session-id";
+
+/** Random bytes after the version, as hex. */
+const RANDOM_BYTES = 16;
+const SESSION_ID_PATTERN = /^([A-Za-z0-9_-]+)\.[0-9a-f]+$/;
+const SSE_DATA_PREFIX = "data: ";
+
+/** A new session id for the version: `<base64url(version)>.<32 hex>`, visible ASCII whatever the version holds. */
+export function createToolListSessionId(toolListVersion: string): string {
+  return `${Buffer.from(toolListVersion, "utf8").toString("base64url")}.${randomBytes(RANDOM_BYTES).toString("hex")}`;
+}
+
+/** The tool list version a session id carries, or `null` when the id is not one the endpoint issues. */
+export function readToolListSessionVersion(sessionId: string): string | null {
+  const match = SESSION_ID_PATTERN.exec(sessionId);
+  if (match?.[1] === undefined) return null;
+  return Buffer.from(match[1], "base64url").toString("utf8");
+}
+
+/** Whether a request in this session may be served: its version is the current one. */
+export function isToolListSessionCurrent(sessionId: string, toolListVersion: string): boolean {
+  return readToolListSessionVersion(sessionId) === toolListVersion;
+}
+
+/** The answer to a request in a session from another tool list version: the client starts a new session. */
+export function createSessionRenewalResponse(): Response {
+  return Response.json(
+    { jsonrpc: "2.0", error: { code: -32001, message: "Session not found: the tool list changed, initialize again" }, id: null },
+    { status: 404, headers: { "cache-control": "no-store" } },
+  );
+}
+
+/**
+ * Whether the request is a JSON-RPC `initialize`: a POST without a session id whose JSON body asks for it. The body
+ * is read from a clone, and a body over `maxBytes` is not read (the SDK refuses it with 413 anyway).
+ */
+export async function isInitializeRequest(request: Request, maxBytes: number): Promise<boolean> {
+  if (request.method !== "POST" || request.headers.has(MCP_SESSION_ID_HEADER)) return false;
+  const length = Number(request.headers.get("content-length") ?? "0");
+  if (!Number.isFinite(length) || length > maxBytes) return false;
+  let body: unknown;
+  try {
+    const text = await request.clone().text();
+    if (text.length > maxBytes) return false;
+    body = JSON.parse(text);
+  } catch {
+    // Not JSON: the SDK answers the parse error itself.
+    return false;
+  }
+  return typeof body === "object" && body !== null && !Array.isArray(body) && (body as { method?: unknown }).method === "initialize";
+}
+
+/**
+ * The `initialize` answer with `capabilities.tools.listChanged: false`, since no answer of the endpoint ever carries
+ * the notification, and with the session id when there is one. The body keeps its format (JSON or one SSE event);
+ * an answer that is not a successful `InitializeResult` is returned as it is.
+ */
+export async function rewriteInitializeAnswer(response: Response, sessionId: string | null): Promise<Response> {
+  if (response.status !== 200) return response;
+  const text = await response.text();
+  const isEventStream = (response.headers.get("content-type") ?? "").includes("text/event-stream");
+  const lines = text.split("\n");
+  const dataIndex = isEventStream ? lines.findIndex((line) => line.startsWith(SSE_DATA_PREFIX)) : -1;
+  const json = isEventStream ? (dataIndex === -1 ? null : (lines[dataIndex] ?? "").slice(SSE_DATA_PREFIX.length)) : text;
+
+  const answer = parseInitializeAnswer(json);
+  const headers = new Headers(response.headers);
+  // The body changes length, so the old one would be wrong.
+  headers.delete("content-length");
+  const tools = answer?.result?.capabilities?.tools;
+  if (answer === null || answer.result?.protocolVersion === undefined) {
+    return new Response(text, { status: response.status, statusText: response.statusText, headers });
+  }
+  if (tools !== undefined && tools !== null && typeof tools === "object") tools.listChanged = false;
+  if (sessionId !== null) headers.set(MCP_SESSION_ID_HEADER, sessionId);
+
+  const rewritten = JSON.stringify(answer);
+  if (isEventStream) lines[dataIndex] = `${SSE_DATA_PREFIX}${rewritten}`;
+  return new Response(isEventStream ? lines.join("\n") : rewritten, { status: response.status, statusText: response.statusText, headers });
+}
+
+/** The answer as JSON, or `null` when there is none or it is not JSON (the SDK's own error text). */
+function parseInitializeAnswer(json: string | null): InitializeAnswer | null {
+  if (json === null) return null;
+  try {
+    return JSON.parse(json) as InitializeAnswer;
+  } catch {
+    return null;
+  }
+}
+
+interface InitializeAnswer {
+  result?: { protocolVersion?: unknown; capabilities?: { tools?: { listChanged?: boolean } | null } };
+}

package/src/testing/index.ts

@@ -6,3 +6,4 @@ export {
   type ServedToolLists,
   type ToolCatalogDifferences,
 } from "./catalog.js";
+export { expectToolListSessionRenewed } from "./sessions.js";

package/src/testing/sessions.ts

@@ -0,0 +1,41 @@
+// Sessions tied to the tool list version (#1055), checked on the app's factories: a release that changes a tool must
+// renew the sessions opened before it, or a connected client keeps the old schemas. Framework-free: it throws.
+import type { McpServerIdentity } from "../contract.js";
+import type { McpServerFactory, VersionedMcpServerFactory } from "../server/endpoint.js";
+import { createToolListSessionId, isToolListSessionCurrent } from "../server/tool-list-session.js";
+import { fingerprintToolList, listServedTools } from "../server/tool-list.js";
+
+const READER: McpServerIdentity = { userId: "00000000-0000-4000-8000-000000000001", canWrite: false, tokenId: "session-check" };
+const WRITER: McpServerIdentity = { ...READER, canWrite: true };
+const LEVELS = [
+  ["read", READER],
+  ["write", WRITER],
+] as const;
+
+/**
+ * Throws unless a session opened under `before` (the previous release's factory) is renewed under `after` for every
+ * access level whose served tool list changed, and kept for every level whose list did not. A pair where no level
+ * changed throws too: the check would prove nothing.
+ */
+export async function expectToolListSessionRenewed(before: McpServerFactory, after: McpServerFactory): Promise<void> {
+  const problems: string[] = [];
+  const unchanged: string[] = [];
+  for (const [level, identity] of LEVELS) {
+    const sessionId = createToolListSessionId(await readVersion(before, identity));
+    const isCurrent = isToolListSessionCurrent(sessionId, await readVersion(after, identity));
+    const hasChanged = fingerprintToolList(await listServedTools(() => before(identity))) !== fingerprintToolList(await listServedTools(() => after(identity)));
+    if (!hasChanged) unchanged.push(level);
+    if (hasChanged && isCurrent) problems.push(`the ${level} tool list changed but a session opened before is kept`);
+    if (!hasChanged && !isCurrent) problems.push(`the ${level} tool list did not change but a session opened before is renewed`);
+  }
+  if (unchanged.length === LEVELS.length) problems.push(`the tool list did not change for any access level (${unchanged.join(", ")})`);
+  if (problems.length > 0) throw new Error(`@softure-ai/mcp-access: sessions do not follow the tool list: ${problems.join("; ")}`);
+}
+
+async function readVersion(factory: McpServerFactory, identity: McpServerIdentity): Promise<string> {
+  const reader = (factory as Partial<VersionedMcpServerFactory>).toolListVersion;
+  if (typeof reader !== "function") {
+    throw new Error("@softure-ai/mcp-access: the factory has no toolListVersion; build it with createMcpServerFactory or pass toolListVersion to createMcpEndpoint");
+  }
+  return reader(identity);
+}