@softure-ai/mcp-access 0.2.6 → 0.2.9

package/src/server/oauth-http.ts

@@ -25,6 +25,7 @@ import { resolveMcpOrigins } from "./origins.js";
 import { isClientRegistrationOpen } from "./registration-window.js";
 import { isValidCodeChallenge, PKCE_METHOD } from "./pkce.js";
 import type { McpAccessContext } from "./tokens.js";
+import { isWritingEnabled } from "./writes-switch.js";
 
 /** The security bucket OAuth registration and token requests count in. */
 export const MCP_OAUTH_RATE_LIMIT_BUCKET = "mcp-oauth";
@@ -175,10 +176,11 @@ export function isWriteScopeRequested(scope: string | null): boolean {
 
 /**
  * Whether the request asks to write, where a missing or blank `scope` is the server's default
- * (RFC 6749 §3.3): both scopes while the app allows writes, `mcp:read` otherwise.
+ * (RFC 6749 §3.3): both scopes while the app allows writes (`allowWrites` and the writes switch),
+ * `mcp:read` otherwise.
  */
-function isWriteRequestedOrDefault(config: SoftureConfig, scope: string | null): boolean {
-  if (scope === null || scope.trim() === "") return getMcpAccessOptions(config).allowWrites;
+function isWriteRequestedOrDefault(isWriteAllowed: boolean, scope: string | null): boolean {
+  if (scope === null || scope.trim() === "") return isWriteAllowed;
   return isWriteScopeRequested(scope);
 }
 
@@ -399,6 +401,11 @@ export interface AuthorizationRequest {
   readonly codeChallenge: string;
   /** The client asked for `mcp:write`. */
   readonly isWriteRequested: boolean;
+  /**
+   * Writes are on offer: the client asked for them (or sent no scope while writes are allowed) and the
+   * app allows writes right now (`allowWrites` and the `mcp-access.writes_enabled` switch).
+   */
+  readonly isWriteOffered: boolean;
 }
 
 /** Why the consent page shows an error instead of sending one back: the client is not confirmed. */
@@ -467,7 +474,9 @@ export async function validateAuthorizationRequest(
     return back("invalid_request", "PKCE is required: code_challenge with code_challenge_method S256.");
   }
   if (!isAcceptableResource(ctx.config, params.get("resource"), origins)) return back("invalid_target", "The resource parameter does not name this MCP server.");
-  return { kind: "valid", request: { client, redirectUri, state, codeChallenge, isWriteRequested: isWriteRequestedOrDefault(ctx.config, params.get("scope")) } };
+  const isWriteAllowed = await isWritingEnabled(ctx);
+  const isWriteRequested = isWriteRequestedOrDefault(isWriteAllowed, params.get("scope"));
+  return { kind: "valid", request: { client, redirectUri, state, codeChallenge, isWriteRequested, isWriteOffered: isWriteRequested && isWriteAllowed } };
 }
 
 /** The consent page with the request's parameters: where the decision sends the person back. */
@@ -531,7 +540,7 @@ export async function handleAuthorizationDecision(ctx: McpAccessContext, request
     if (outcome.kind === "show-error") return seeOther(consent);
     if (outcome.kind === "redirect-error") return seeOther(outcome.location);
 
-    const { client, redirectUri, state, codeChallenge, isWriteRequested } = outcome.request;
+    const { client, redirectUri, state, codeChallenge, isWriteOffered } = outcome.request;
     if (form.get("decision") !== "allow") {
       return seeOther(buildClientRedirect(ctx.config, redirectUri, { error: "access_denied", error_description: "The person denied access.", state }, origins));
     }
@@ -540,8 +549,8 @@ export async function handleAuthorizationDecision(ctx: McpAccessContext, request
       userId,
       redirectUri,
       codeChallenge,
-      // Writes need the client's request, the app's allowWrites and the person's tick.
-      canWrite: isWriteRequested && getMcpAccessOptions(ctx.config).allowWrites && form.get("canWrite") !== null,
+      // Writes need the client's request, the app's allowWrites, the writes switch and the person's tick.
+      canWrite: isWriteOffered && form.get("canWrite") !== null,
     });
     return seeOther(buildClientRedirect(ctx.config, redirectUri, { code, state }, origins));
   } catch (error) {

package/src/server/server-factory.ts

@@ -0,0 +1,78 @@
+// The app's MCP server factory with a version that follows its tool list. The tools are measured once
+// per access level (a read-only token sees fewer tools) on a recording server, and each request's
+// server answers `initialize` with that level's version, so a client drops its cached `tools/list`
+// whenever a release changes a tool. The factory plugs into `createMcpEndpoint`, `serveMcpStdio` and
+// the catalog check like a hand-written one.
+//
+//   export const createServer = createMcpServerFactory({
+//     name: "acme",
+//     registerTools: (server, identity) => registerNoteTools(server, identity),
+//   });
+import { McpServer, type McpServerOptions } from "@modelcontextprotocol/server";
+import type { McpServerIdentity } from "../contract.js";
+import type { McpServerFactory } 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";
+
+export interface McpServerFactoryOptions {
+  /** `serverInfo.name`. */
+  readonly name: string;
+  /** `serverInfo.title`, the name a client shows. */
+  readonly title?: string;
+  /** The `MAJOR.MINOR.PATCH` before `-tools-`. Default: `1.0.0`. */
+  readonly release?: string;
+  /** A fixed `serverInfo.version` instead of the measured one. */
+  readonly version?: string;
+  readonly serverOptions?: McpServerOptions;
+  /**
+   * Registers the tools for one request. The tool list may depend on `identity.canWrite` only: it is
+   * measured once per access level. A list that depends on the account needs `measureToolList` per call.
+   */
+  readonly registerTools: (server: McpServer, identity: McpServerIdentity) => unknown;
+  /** Every tool's input is strict (`withStrictToolInput`), on the served and the measured server alike. */
+  readonly strictToolInput?: boolean | StrictToolInputOptions;
+  /**
+   * Adds the read-only `get_server_info` tool for every access level: the build info (pass `readBuildInfo` of
+   * `@softure-ai/ops/server`) with the served name and version. Off by default.
+   */
+  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 {
+  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.
+  const registerTools = async (server: McpServer, identity: McpServerIdentity, version = ""): Promise<void> => {
+    const target = strictOptions === undefined ? server : withStrictToolInput(server, strictOptions);
+    await options.registerTools(target, identity);
+    if (options.serverInfoTool !== undefined) registerServerInfoTool(target, { ...options.serverInfoTool, server: { name: options.name, version } });
+  };
+  const measurements = new Map<boolean, Promise<ToolListMeasurement>>();
+
+  // The promise is cached, so parallel first requests measure once; a failed measurement is dropped so
+  // the next request tries again instead of failing for good.
+  const measure = (identity: McpServerIdentity): Promise<ToolListMeasurement> => {
+    const cached = measurements.get(identity.canWrite);
+    if (cached !== undefined) return cached;
+    const measurement = measureToolList((server) => registerTools(server, identity), {
+      ...(options.release === undefined ? {} : { release: options.release }),
+      name: options.name,
+      ...(options.serverOptions === undefined ? {} : { serverOptions: options.serverOptions }),
+    });
+    measurements.set(identity.canWrite, measurement);
+    void measurement.catch(() => measurements.delete(identity.canWrite));
+    return measurement;
+  };
+
+  return async (identity) => {
+    const version = options.version ?? (await measure(identity)).toolListVersion;
+    const server = new McpServer(
+      { name: options.name, version, ...(options.title === undefined ? {} : { title: options.title }) },
+      options.serverOptions,
+    );
+    await registerTools(server, identity, version);
+    return server;
+  };
+}

package/src/server/server-info.ts

@@ -0,0 +1,76 @@
+// The `get_server_info` tool (#885): an assistant checks a "done" against production in one call. It answers the
+// public facts of the ops build info route (release, commit, build and start times, the optional changelog) and the
+// name and version the server answered at `initialize`, which follows the tool list. It reads no user data.
+//
+// The app passes the build info reader, so `/server` never loads `@softure-ai/ops` (an optional peer):
+//
+//   import { readBuildInfo } from "@softure-ai/ops/server";
+//   createMcpServerFactory({ name: "acme", registerTools, serverInfoTool: { buildInfo: () => readBuildInfo() } });
+import type { McpServer } from "@modelcontextprotocol/server";
+import { errorLogLabel } from "@softure-ai/core";
+import { z } from "zod";
+import { en } from "../messages/en.js";
+import { toolResult } from "./tools.js";
+
+export const SERVER_INFO_TOOL_NAME = "get_server_info";
+
+/** The build info of `@softure-ai/ops` (`readBuildInfo()`), typed by shape so mcp-access does not import ops. */
+export interface McpBuildInfo {
+  readonly release: string | null;
+  readonly commit: string | null;
+  readonly builtAt: string | null;
+  readonly startedAt: string;
+}
+
+export interface ServerInfoToolOptions {
+  /** The build info, e.g. `() => readBuildInfo()` from `@softure-ai/ops/server` with the route's options. */
+  readonly buildInfo: () => McpBuildInfo | Promise<McpBuildInfo>;
+  /** The changelog the build info route answers, when the app passes one there. Only what is public. */
+  readonly changelog?: () => unknown;
+  /** Default: `serverInfoTool.description` of the module dictionary. */
+  readonly description?: string;
+}
+
+/** What `initialize` answers as `serverInfo`. */
+export interface ServedServerInfo {
+  readonly name: string;
+  readonly version: string;
+}
+
+export interface RegisterServerInfoToolOptions extends ServerInfoToolOptions {
+  /** The name and version the server answers at `initialize`; `createMcpServerFactory` passes them in. */
+  readonly server: ServedServerInfo;
+}
+
+/** The tool's answer: the served name and version, the build info and, with a provider, the changelog. */
+export type ServerInfoAnswer = McpBuildInfo & { readonly server: ServedServerInfo; readonly changelog?: unknown };
+
+/** Registers `get_server_info`: no input fields, read only. A failing `buildInfo` reaches the SDK, which answers a tool error. */
+export function registerServerInfoTool(server: McpServer, options: RegisterServerInfoToolOptions): void {
+  server.registerTool(
+    SERVER_INFO_TOOL_NAME,
+    {
+      description: options.description ?? en.serverInfoTool.description,
+      // An empty object rather than no schema, so strict input refuses a field sent to it.
+      inputSchema: z.object({}),
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    },
+    async () => toolResult(await readServerInfo(options)),
+  );
+}
+
+async function readServerInfo(options: RegisterServerInfoToolOptions): Promise<ServerInfoAnswer> {
+  const { release, commit, builtAt, startedAt } = await options.buildInfo();
+  const answer: ServerInfoAnswer = { server: { name: options.server.name, version: options.server.version }, release, commit, builtAt, startedAt };
+  return options.changelog === undefined ? answer : { ...answer, changelog: await readChangelog(options.changelog) };
+}
+
+/** As the build info route: a failing provider answers `null` and logs the error class, so the build info still answers. */
+async function readChangelog(provider: () => unknown): Promise<unknown> {
+  try {
+    return (await provider()) ?? null;
+  } catch (error) {
+    console.error(`get_server_info: the changelog provider failed: ${errorLogLabel(error)}`);
+    return null;
+  }
+}

package/src/server/strict-input.ts

@@ -0,0 +1,191 @@
+// Strict tool input. zod objects strip unknown keys, so a tool call with a misspelt field (`notes` for
+// `note`) or a field of a newer tool list answers as a write that worked while the value was dropped.
+// `withStrictToolInput` rewrites every input schema once, at registration: each object refuses a field
+// it does not know and names the ones it accepts, a field sent under its old name is refused with the
+// stable code `input.field_renamed`, and boolean and number fields also take their exact text (a client
+// on an older tool list sends a field it does not know as text). The SDK validates before the handler
+// runs, so a refused call saves nothing.
+//
+//   const server = withStrictToolInput(new McpServer({ name: "acme", version }), { renamedFields: { notes: "note" } });
+import type { McpServer } from "@modelcontextprotocol/server";
+import { formatMessage } from "@softure-ai/core";
+import { z } from "zod";
+import type * as core from "zod/v4/core";
+import { en } from "../messages/en.js";
+
+/** The texts of a refused field: `toolInput` of the module dictionary (`getMcpAccessMessages(config).toolInput`). */
+export type StrictToolInputMessages = typeof en.toolInput;
+
+export interface StrictToolInputOptions {
+  /** Old field name → new field name, refused as `input.field_renamed` wherever an object accepts the new name. */
+  readonly renamedFields?: Readonly<Record<string, string>>;
+  /** Boolean fields also take `"true"`/`"false"` and number fields a number written as text. Default: `true`. */
+  readonly coerceTextScalars?: boolean;
+  /** Default: the module's English dictionary. */
+  readonly messages?: StrictToolInputMessages;
+}
+
+/** A JSON number literal: no spaces, no hex, no empty text. */
+const NUMBER_TEXT = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+
+const strictServers = new WeakSet<McpServer>();
+
+type ToolConfig = Readonly<Record<string, unknown>> & { readonly inputSchema?: unknown };
+type RegisterTool = (name: string, config: ToolConfig, callback: unknown) => unknown;
+
+/** Makes every tool registered on the server from now on strict; wrapping a server twice changes nothing. */
+export function withStrictToolInput<Server extends McpServer>(server: Server, options: StrictToolInputOptions = {}): Server {
+  if (strictServers.has(server)) return server;
+  // The SDK's overloads only differ in how the schema is typed; at runtime it is one method.
+  const register = server.registerTool.bind(server) as unknown as RegisterTool;
+  const registerStrict: RegisterTool = (name, config, callback) =>
+    register(name, config.inputSchema === undefined ? config : { ...config, inputSchema: toStrictToolInput(config.inputSchema, options) }, callback);
+  Object.defineProperty(server, "registerTool", { value: registerStrict, configurable: true, writable: true });
+  strictServers.add(server);
+  return server;
+}
+
+/** The strict form of a tool's input schema: a zod 4 schema or raw shape is rewritten, anything else passes unchanged. */
+export function toStrictToolInput(schema: unknown, options: StrictToolInputOptions = {}): unknown {
+  const zodSchema = isZodSchema(schema) ? schema : isRawShape(schema) ? z.object(schema) : null;
+  if (zodSchema === null) return schema;
+  const rewriter = new StrictRewriter({
+    renamedFields: options.renamedFields ?? {},
+    coerceTextScalars: options.coerceTextScalars ?? true,
+    messages: options.messages ?? en.toolInput,
+  });
+  return rewriter.rewrite(zodSchema);
+}
+
+function isZodSchema(value: unknown): value is core.$ZodType {
+  return typeof value === "object" && value !== null && "_zod" in value;
+}
+
+function isRawShape(value: unknown): value is Record<string, core.$ZodType> {
+  if (typeof value !== "object" || value === null || Object.getPrototypeOf(value) !== Object.prototype) return false;
+  return Object.values(value).every(isZodSchema);
+}
+
+type RewriteSettings = Required<StrictToolInputOptions>;
+
+/** A schema node as the rewriter reads it: its kind and the parts it rewrites. */
+type AnyDef = core.$ZodTypeDef & Record<string, unknown>;
+
+class StrictRewriter {
+  // The same node (a shared field, a recursive `z.lazy`) is rewritten once.
+  private readonly rewritten = new Map<core.$ZodType, core.$ZodType>();
+
+  constructor(private readonly settings: RewriteSettings) {}
+
+  rewrite(schema: core.$ZodType): core.$ZodType {
+    const known = this.rewritten.get(schema);
+    if (known !== undefined) return known;
+    const result = this.rewriteNode(schema);
+    this.rewritten.set(schema, result);
+    return result;
+  }
+
+  private rewriteNode(schema: core.$ZodType): core.$ZodType {
+    const def = schema._zod.def as AnyDef;
+    switch (def.type) {
+      case "object":
+        return this.rewriteObject(schema as core.$ZodObject);
+      case "array":
+        return this.cloneWith(schema, { element: this.rewrite(def.element as core.$ZodType) });
+      case "optional":
+      case "nullable":
+      case "default":
+      case "prefault":
+      case "nonoptional":
+      case "readonly":
+      case "catch":
+        return this.cloneWith(schema, { innerType: this.rewrite(def.innerType as core.$ZodType) });
+      case "union":
+        return this.cloneWith(schema, { options: (def.options as core.$ZodType[]).map((option) => this.rewrite(option)) });
+      case "intersection":
+        return this.cloneWith(schema, { left: this.rewrite(def.left as core.$ZodType), right: this.rewrite(def.right as core.$ZodType) });
+      case "record":
+        return this.cloneWith(schema, { valueType: this.rewrite(def.valueType as core.$ZodType) });
+      case "tuple":
+        return this.cloneWith(schema, {
+          items: (def.items as core.$ZodType[]).map((item) => this.rewrite(item)),
+          rest: def.rest === null ? null : this.rewrite(def.rest as core.$ZodType),
+        });
+      case "pipe":
+        return this.rewritePipe(schema, def);
+      case "lazy": {
+        const getter = def.getter as () => core.$ZodType;
+        return this.cloneWith(schema, { getter: () => this.rewrite(getter()) });
+      }
+      case "boolean":
+        return this.settings.coerceTextScalars && def.coerce !== true ? z.preprocess(readBooleanText, schema) : schema;
+      case "number":
+        return this.settings.coerceTextScalars && def.coerce !== true ? z.preprocess(readNumberText, schema) : schema;
+      default:
+        return schema;
+    }
+  }
+
+  /** Only the input side: `in`, or `out` after a preprocess (whose `in` is the transform). */
+  private rewritePipe(schema: core.$ZodType, def: AnyDef): core.$ZodType {
+    const input = def.in as core.$ZodType;
+    if (input._zod.traits.has("$ZodTransform")) return this.cloneWith(schema, { out: this.rewrite(def.out as core.$ZodType) });
+    return this.cloneWith(schema, { in: this.rewrite(input) });
+  }
+
+  private rewriteObject(schema: core.$ZodObject): core.$ZodType {
+    const def = schema._zod.def;
+    const shape = Object.fromEntries(Object.entries(def.shape).map(([name, field]) => [name, this.rewrite(field)]));
+    // An object with its own catchall (`looseObject`, `.catchall(x)`) accepts extra fields on purpose.
+    if (def.catchall !== undefined && def.catchall._zod.def.type !== "never") return this.cloneWith(schema, { shape });
+    // The object's own map, read for any issue: its parameter type is narrowed to the issues an object raises.
+    const ownError = def.error as core.$ZodErrorMap | undefined;
+    const describe = (issue: core.$ZodRawIssue): string | undefined => describeUnknownFields(issue, Object.keys(shape), this.settings);
+    const error: core.$ZodErrorMap = (issue) => describe(issue) ?? ownError?.(issue);
+    return this.cloneWith(schema, { shape, catchall: z.never(), error });
+  }
+
+  /** A copy of the node with some parts replaced; its description and other metadata stay with it. */
+  private cloneWith(schema: core.$ZodType, parts: Record<string, unknown>): core.$ZodType {
+    const copy = (schema as unknown as z.ZodType).clone({ ...schema._zod.def, ...parts });
+    const meta = z.globalRegistry.get(schema);
+    if (meta !== undefined) {
+      // An id names one schema in the JSON Schema output; the copy replaces the original, so it may not carry it twice.
+      const rest = { ...meta };
+      delete rest.id;
+      z.globalRegistry.add(copy, rest);
+    }
+    return copy;
+  }
+}
+
+/** The text for an object's unknown fields: renamed ones first, then the rest with the fields it accepts. */
+function describeUnknownFields(issue: core.$ZodRawIssue, accepted: readonly string[], settings: RewriteSettings): string | undefined {
+  if (issue.code !== "unrecognized_keys") return undefined;
+  const { messages, renamedFields } = settings;
+  const renamed: string[] = [];
+  const unknown: string[] = [];
+  for (const field of issue.keys) {
+    const newName = Object.hasOwn(renamedFields, field) ? renamedFields[field] : undefined;
+    if (newName !== undefined && accepted.includes(newName)) renamed.push(formatMessage(messages.fieldRenamed, { field, renamed: newName }));
+    else unknown.push(field);
+  }
+  if (unknown.length > 0) {
+    renamed.push(formatMessage(messages.unknownFields, { fields: quoteAll(unknown), accepted: accepted.length > 0 ? quoteAll(accepted) : messages.noFields }));
+  }
+  return renamed.join(" ");
+}
+
+function quoteAll(names: readonly string[]): string {
+  return names.map((name) => JSON.stringify(name)).join(", ");
+}
+
+function readBooleanText(value: unknown): unknown {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  return value;
+}
+
+function readNumberText(value: unknown): unknown {
+  return typeof value === "string" && NUMBER_TEXT.test(value) ? Number(value) : value;
+}

package/src/server/tool-list.ts

@@ -0,0 +1,105 @@
+// The server version that follows the tool list. MCP clients keep a cached `tools/list` until the
+// version they read at `initialize` changes, so a release that adds a tool or changes a schema under
+// the same version leaves the assistant on the old schemas. `measureToolList` fingerprints the list
+// as the client reads it, `<release>-tools-<12 hex>`: a semver prerelease, since comparisons ignore
+// build metadata. The same registrations always give the same version.
+import { createHash } from "node:crypto";
+import { createMcpHandler, McpServer, METHOD_NOT_FOUND, type McpServerOptions, type Server } from "@modelcontextprotocol/server";
+
+/** The release part when none is given. */
+export const DEFAULT_TOOL_LIST_RELEASE = "1.0.0";
+
+/** Hex digits of the fingerprint in the version. */
+const FINGERPRINT_LENGTH = 12;
+const RELEASE_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+/** What a client reads from `tools/list`: one entry per tool, as JSON. */
+export type ServedTool = Readonly<Record<string, unknown>> & { readonly name: string };
+
+export interface ToolListMeasurement {
+  /** `<release>-tools-<12 hex>`, for `serverInfo.version`. */
+  readonly toolListVersion: string;
+  readonly toolCount: number;
+}
+
+/** Registers the app's tools on the server it is given, e.g. `(server) => registerNoteTools(server, identity)`. */
+export type RegisterTools = (server: McpServer) => unknown;
+
+export interface MeasureToolListOptions {
+  /** The `MAJOR.MINOR.PATCH` before `-tools-`. Default: `1.0.0`. */
+  readonly release?: string;
+  /** The served server's name, so the recording server is shaped like it. Default: `tool-list`. */
+  readonly name?: string;
+  /** The served server's options (capabilities, instructions), for the same reason. */
+  readonly serverOptions?: McpServerOptions;
+}
+
+/**
+ * Registers the tools on a recording server shaped like the served one, lists them the way the endpoint
+ * serves them and returns the version with the tool count. Any change of a tool's name, title,
+ * description, annotations or input or output schema changes the version; the order of registration does not.
+ */
+export async function measureToolList(registerTools: RegisterTools, options: MeasureToolListOptions = {}): Promise<ToolListMeasurement> {
+  const release = options.release ?? DEFAULT_TOOL_LIST_RELEASE;
+  assertRelease(release);
+  const server = new McpServer({ name: options.name ?? "tool-list", version: release }, options.serverOptions);
+  await registerTools(server);
+  return describeToolList(await listServedTools(() => server), release);
+}
+
+/** The version and count for a listed tool set. */
+export function describeToolList(tools: readonly ServedTool[], release: string = DEFAULT_TOOL_LIST_RELEASE): ToolListMeasurement {
+  assertRelease(release);
+  return { toolListVersion: `${release}-tools-${fingerprintToolList(tools)}`, toolCount: tools.length };
+}
+
+/** The first 12 hex digits of a sha256 over the tools in name order, each as canonical JSON (keys sorted at every level). */
+export function fingerprintToolList(tools: readonly ServedTool[]): string {
+  const ordered = [...tools].sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+  return createHash("sha256").update(toCanonicalJson(ordered)).digest("hex").slice(0, FINGERPRINT_LENGTH);
+}
+
+/** Every tool a fresh server from the factory lists (none when it registered none), asked with one stateless `tools/list` as the endpoint serves it. */
+export async function listServedTools(createServer: () => McpServer | Server | Promise<McpServer | Server>): Promise<ServedTool[]> {
+  const handler = createMcpHandler(createServer, { responseMode: "json" });
+  const response = await handler.fetch(
+    new Request("http://localhost/api/mcp", {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }),
+    }),
+  );
+  const answer = readAnswer(await response.text());
+  // A server that registered no tool declares no tools capability, so it does not know the method.
+  if (answer.error?.code === METHOD_NOT_FOUND) return [];
+  if (answer.result?.tools === undefined) {
+    throw new Error(`@softure-ai/mcp-access: listing the server's tools failed: ${typeof answer.error?.message === "string" ? answer.error.message : `HTTP ${String(response.status)}`}`);
+  }
+  return answer.result.tools.filter((tool): tool is ServedTool => typeof tool.name === "string" && tool.name !== "");
+}
+
+interface ToolsListAnswer {
+  readonly result?: { readonly tools?: readonly (Readonly<Record<string, unknown>> & { readonly name?: unknown })[] };
+  readonly error?: { readonly code?: unknown; readonly message?: unknown };
+}
+
+/** The JSON-RPC answer, sent as JSON or as one SSE `message` event. */
+function readAnswer(body: string): ToolsListAnswer {
+  const data = body.startsWith("event:") ? (body.split("\n").find((line) => line.startsWith("data: "))?.slice("data: ".length) ?? "null") : body;
+  return (JSON.parse(data) ?? {}) as ToolsListAnswer;
+}
+
+function toCanonicalJson(value: unknown): string {
+  return JSON.stringify(value, (_key, entry: unknown) =>
+    entry !== null && typeof entry === "object" && !Array.isArray(entry)
+      ? Object.fromEntries(Object.entries(entry).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)))
+      : entry,
+  );
+}
+
+/** A release that is not `MAJOR.MINOR.PATCH` would make an invalid version: a setup bug, thrown. */
+function assertRelease(release: string): void {
+  if (!RELEASE_PATTERN.test(release)) {
+    throw new Error(`@softure-ai/mcp-access: the tool list release must be MAJOR.MINOR.PATCH, got "${release}"`);
+  }
+}

package/src/server/writes-switch.ts

@@ -0,0 +1,24 @@
+// The runtime kill switch for writes. `mcp-access.writes_enabled` is read through the switch-reader
+// contract of `@softure-ai/core` on every request: when the app defines it in
+// `@softure-ai/feature-switches`, turning it off takes writes away at once, without a deploy. An app that
+// does not define it keeps `allowWrites` alone.
+import { errorLogLabel, readSwitch } from "@softure-ai/core";
+import { WRITES_ENABLED_SWITCH } from "../index.js";
+import { getMcpAccessOptions } from "./options.js";
+import type { McpAccessContext } from "./tokens.js";
+
+/**
+ * Whether the app lets anyone write right now: `allowWrites` and the switch (on when the app does not
+ * define it). Without `allowWrites` the switch is not read. A read that throws counts as off (writes
+ * are the risky side) and is logged by the switch's name.
+ */
+export async function isWritingEnabled(ctx: McpAccessContext): Promise<boolean> {
+  if (!getMcpAccessOptions(ctx.config).allowWrites) return false;
+  try {
+    const reading = await readSwitch(ctx, WRITES_ENABLED_SWITCH);
+    return reading.kind === "undeclared" || reading.isEnabled;
+  } catch (error) {
+    console.error(`@softure-ai/mcp-access: reading the ${WRITES_ENABLED_SWITCH} switch failed, writes are off: ${errorLogLabel(error)}`);
+    return false;
+  }
+}

package/src/stdio/serve.ts

@@ -8,11 +8,11 @@
 import type { Transport } from "@modelcontextprotocol/server";
 import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { resolveOnlyAccount } from "@softure-ai/auth/server";
-import { errorLogLabel, type SoftureConfig, type SoftureDatabaseConfig } from "@softure-ai/core";
+import { errorLogLabel, systemClock, type SoftureConfig, type SoftureDatabaseConfig } from "@softure-ai/core";
 import { openCommandDatabase, type CommandDatabase } from "@softure-ai/db";
 import type { McpServerIdentity } from "../contract.js";
 import type { McpServerFactory } from "../server/endpoint.js";
-import { getMcpAccessOptions } from "../server/options.js";
+import { isWritingEnabled } from "../server/writes-switch.js";
 
 /** The variable naming the account to serve, unless the entry is told another one. */
 export const DEFAULT_MCP_USER_ID_ENV = "MCP_USER_ID";
@@ -72,11 +72,9 @@ export async function serveMcpStdio(options: ServeMcpStdioOptions): Promise<McpS
     return { ok: false, error: userId };
   }
 
-  const identity: McpServerIdentity = {
-    userId,
-    canWrite: (options.allowWrites ?? false) && getMcpAccessOptions(config).allowWrites,
-    tokenId: STDIO_TOKEN_ID,
-  };
+  // The writes switch is read once, at start: a stdio server serves one local session.
+  const canWrite = (options.allowWrites ?? false) && (await isWritingEnabled({ db: database.handle.db, clock: systemClock, config }));
+  const identity: McpServerIdentity = { userId, canWrite, tokenId: STDIO_TOKEN_ID };
   let closed = false;
   const closeDatabase = async () => {
     if (closed) return;

package/src/testing/catalog.ts

@@ -1,11 +1,11 @@
 // Catalog parity: the tools listed in softure.config.ts (the token page shows them, agent docs read
 // them) against the tools the app's MCP server really registers, for a read-only and a write identity.
 // Framework-free: `expectToolCatalogMatchesServer` throws, so it works in any test runner.
-import { createMcpHandler } from "@modelcontextprotocol/server";
 import type { SoftureConfig } from "@softure-ai/core";
 import type { McpServerIdentity } from "../contract.js";
 import type { McpServerFactory } from "../server/endpoint.js";
 import { getMcpAccessOptions } from "../server/options.js";
+import { describeToolList, listServedTools, type ToolListMeasurement } from "../server/tool-list.js";
 
 export interface ToolCatalogDifferences {
   /** Configured tools the server does not register for the identity that should get them. */
@@ -16,6 +16,12 @@ export interface ToolCatalogDifferences {
   readonly writeForReaders: readonly string[];
 }
 
+/** What `measureServedToolLists` reports: a read-only and a write identity. */
+export interface ServedToolLists {
+  readonly read: ToolListMeasurement;
+  readonly write: ToolListMeasurement;
+}
+
 const READER: McpServerIdentity = { userId: "00000000-0000-4000-8000-000000000001", canWrite: false, tokenId: "catalog-check" };
 const WRITER: McpServerIdentity = { ...READER, canWrite: true };
 
@@ -47,28 +53,13 @@ export async function expectToolCatalogMatchesServer(config: SoftureConfig, crea
 
 /** The tool names a fresh server lists for the identity, asked the way the endpoint serves it. */
 async function listServerTools(createServer: McpServerFactory, identity: McpServerIdentity): Promise<string[]> {
-  const handler = createMcpHandler(() => createServer(identity), { responseMode: "json" });
-  const response = await handler.fetch(
-    new Request("http://localhost/api/mcp", {
-      method: "POST",
-      headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
-      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }),
-    }),
-  );
-  const answer = readAnswer(await response.text());
-  if (answer.result?.tools === undefined) {
-    throw new Error(`@softure-ai/mcp-access: listing the server's tools failed: ${typeof answer.error?.message === "string" ? answer.error.message : `HTTP ${String(response.status)}`}`);
-  }
-  return answer.result.tools.map((tool) => (typeof tool.name === "string" ? tool.name : "")).filter((name) => name !== "");
+  return (await listServedTools(() => createServer(identity))).map((tool) => tool.name);
 }
 
-interface ToolsListAnswer {
-  readonly result?: { readonly tools?: readonly { readonly name?: unknown }[] };
-  readonly error?: { readonly message?: unknown };
-}
-
-/** The JSON-RPC answer, sent as JSON or as one SSE `message` event. */
-function readAnswer(body: string): ToolsListAnswer {
-  const data = body.startsWith("event:") ? (body.split("\n").find((line) => line.startsWith("data: "))?.slice("data: ".length) ?? "null") : body;
-  return (JSON.parse(data) ?? {}) as ToolsListAnswer;
+/** The tool list's version and count for each access level, for a snapshot that changes whenever a tool's schema does. */
+export async function measureServedToolLists(createServer: McpServerFactory, release?: string): Promise<ServedToolLists> {
+  return {
+    read: describeToolList(await listServedTools(() => createServer(READER)), release),
+    write: describeToolList(await listServedTools(() => createServer(WRITER)), release),
+  };
 }

package/src/testing/index.ts

@@ -1,2 +1,8 @@
 // `@softure-ai/mcp-access/testing`: checks for an app's own tests.
-export { expectToolCatalogMatchesServer, getToolCatalogDifferences, type ToolCatalogDifferences } from "./catalog.js";
+export {
+  expectToolCatalogMatchesServer,
+  getToolCatalogDifferences,
+  measureServedToolLists,
+  type ServedToolLists,
+  type ToolCatalogDifferences,
+} from "./catalog.js";