@softure-ai/mcp-access 0.2.6 → 0.2.8

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