@softure-ai/mcp-access 0.5.0 → 0.7.0

package/src/server/server-factory.ts

@@ -13,7 +13,7 @@ import type { McpServerIdentity } from "../contract.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";
+import { describeToolList, listRecordedTools, type ServedTool, type ToolListMeasurement } from "./tool-list.js";
 
 export interface McpServerFactoryOptions {
   /** `serverInfo.name`. */
@@ -34,7 +34,8 @@ export interface McpServerFactoryOptions {
   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.
+   * `@softure-ai/ops/server`) with the served name and version. Off by default. With `tools: true` it also answers the
+   * served tool contract of the caller's access level, taken from the measured list (#1078).
    */
   readonly serverInfoTool?: ServerInfoToolOptions;
 }
@@ -46,25 +47,32 @@ export interface McpServerFactoryOptions {
  */
 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.
-  const registerTools = async (server: McpServer, identity: McpServerIdentity, version = ""): Promise<void> => {
+  // The served version and the measured tools reach `get_server_info` here; the recording server registers it with a
+  // placeholder version and no tools, since its handler never runs there and neither is part of the listed tool.
+  const registerTools = async (server: McpServer, identity: McpServerIdentity, served?: ServedToolList): 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 } });
+    if (options.serverInfoTool !== undefined) {
+      registerServerInfoTool(target, {
+        ...options.serverInfoTool,
+        server: { name: options.name, version: served?.version ?? "" },
+        servedTools: async () => (served === undefined ? [] : (await served.measure()).tools),
+      });
+    }
   };
-  const measurements = new Map<boolean, Promise<ToolListMeasurement>>();
+  const measurements = new Map<boolean, Promise<MeasuredToolList>>();
 
   // 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 measure = (identity: McpServerIdentity): Promise<MeasuredToolList> => {
     const cached = measurements.get(identity.canWrite);
     if (cached !== undefined) return cached;
-    const measurement = measureToolList((server) => registerTools(server, identity), {
-      ...(options.release === undefined ? {} : { release: options.release }),
+    const release = options.release;
+    const measurement = listRecordedTools((server) => registerTools(server, identity), {
+      ...(release === undefined ? {} : { release }),
       name: options.name,
       ...(options.serverOptions === undefined ? {} : { serverOptions: options.serverOptions }),
-    });
+    }).then((tools) => ({ ...describeToolList(tools, release), tools }));
     measurements.set(identity.canWrite, measurement);
     void measurement.catch(() => measurements.delete(identity.canWrite));
     return measurement;
@@ -77,8 +85,20 @@ export function createMcpServerFactory(options: McpServerFactoryOptions): Versio
       { name: options.name, version, ...(options.title === undefined ? {} : { title: options.title }) },
       options.serverOptions,
     );
-    await registerTools(server, identity, version);
+    await registerTools(server, identity, { version, measure: () => measure(identity) });
     return server;
   };
   return Object.assign(factory, { toolListVersion });
 }
+
+/** The measured version with the tools it was computed from, as `tools/list` answers them. */
+interface MeasuredToolList extends ToolListMeasurement {
+  readonly tools: readonly ServedTool[];
+}
+
+/** What a served server's `get_server_info` reads: its version and its access level's measurement. */
+interface ServedToolList {
+  readonly version: string;
+  /** Read only when the tool answers the contract, so a fixed version still measures nothing otherwise. */
+  readonly measure: () => Promise<MeasuredToolList>;
+}

package/src/server/server-info.ts

@@ -2,6 +2,10 @@
 // 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.
 //
+// With `tools: true` (#1078) it also answers the served tool contract: each tool's name, description and input schema
+// as `tools/list` answers them for the caller's access level. A hosted client may keep a stale tool list for good, but
+// it never caches a tool result, so the model can always read the current contract in-band.
+//
 // The app passes the build info reader, so `/server` never loads `@softure-ai/ops` (an optional peer):
 //
 //   import { readBuildInfo } from "@softure-ai/ops/server";
@@ -10,6 +14,7 @@ import type { McpServer } from "@modelcontextprotocol/server";
 import { errorLogLabel } from "@softure-ai/core";
 import { z } from "zod";
 import { en } from "../messages/en.js";
+import type { ServedTool } from "./tool-list.js";
 import { toolResult } from "./tools.js";
 
 export const SERVER_INFO_TOOL_NAME = "get_server_info";
@@ -27,10 +32,22 @@ export interface ServerInfoToolOptions {
   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;
+  /**
+   * Also answers the served tool contract (`tools`), with an optional `name` input that narrows it to one tool. Turning
+   * it on changes the tool's input schema, so the version changes once. Default: off.
+   */
+  readonly tools?: boolean;
   /** Default: `serverInfoTool.description` of the module dictionary. */
   readonly description?: string;
 }
 
+/** One served tool's contract, exactly as `tools/list` answers it. */
+export interface ServedToolContract {
+  readonly name: string;
+  readonly description?: unknown;
+  readonly inputSchema: unknown;
+}
+
 /** What `initialize` answers as `serverInfo`. */
 export interface ServedServerInfo {
   readonly name: string;
@@ -40,22 +57,48 @@ export interface ServedServerInfo {
 export interface RegisterServerInfoToolOptions extends ServerInfoToolOptions {
   /** The name and version the server answers at `initialize`; `createMcpServerFactory` passes them in. */
   readonly server: ServedServerInfo;
+  /**
+   * The tools the caller's `tools/list` answers, read when `tools` is on. `createMcpServerFactory` passes its measured
+   * list; a hand-built server passes `() => listServedTools(createServer)` for the caller's access level.
+   */
+  readonly servedTools?: () => readonly ServedTool[] | Promise<readonly ServedTool[]>;
+}
+
+/** The contract part of the answer, with `tools` on. */
+export interface ServerInfoToolsAnswer {
+  /** Tells the model that the server's contract wins over its own copy. */
+  readonly toolsHint: string;
+  readonly tools: readonly ServedToolContract[];
+  /** Every served tool's name, when `name` matched none. */
+  readonly toolNames?: readonly string[];
 }
 
 /** 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 };
+export type ServerInfoAnswer = McpBuildInfo & { readonly server: ServedServerInfo; readonly changelog?: unknown } & Partial<ServerInfoToolsAnswer>;
 
-/** Registers `get_server_info`: no input fields, read only. A failing `buildInfo` reaches the SDK, which answers a tool error. */
+/**
+ * Registers `get_server_info`, read only: no input fields, or an optional `name` with `tools` on. A failing `buildInfo`
+ * reaches the SDK, which answers a tool error.
+ */
 export function registerServerInfoTool(server: McpServer, options: RegisterServerInfoToolOptions): void {
+  const annotations = { readOnlyHint: true, idempotentHint: true, openWorldHint: false };
+  const description = options.description ?? (options.tools === true ? en.serverInfoTool.descriptionWithTools : en.serverInfoTool.description);
+  if (options.tools !== true) {
+    // An empty object rather than no schema, so strict input refuses a field sent to it.
+    server.registerTool(SERVER_INFO_TOOL_NAME, { description, inputSchema: z.object({}), annotations }, async () => toolResult(await readServerInfo(options)));
+    return;
+  }
+  const readServedTools = options.servedTools;
+  if (readServedTools === undefined) {
+    throw new Error("@softure-ai/mcp-access: get_server_info with tools: true needs servedTools, e.g. () => listServedTools(createServer)");
+  }
   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 },
+    { description, inputSchema: z.object({ name: z.string().optional().describe(en.serverInfoTool.nameInputDescription) }), annotations },
+    async ({ name }) => {
+      const answer = await readServerInfo(options);
+      return toolResult({ ...answer, ...describeToolContract(await readServedTools(), name) });
     },
-    async () => toolResult(await readServerInfo(options)),
   );
 }
 
@@ -65,6 +108,15 @@ async function readServerInfo(options: RegisterServerInfoToolOptions): Promise<S
   return options.changelog === undefined ? answer : { ...answer, changelog: await readChangelog(options.changelog) };
 }
 
+/** The contract of every served tool, or of the one named; an unknown name answers no tool and every name. */
+function describeToolContract(served: readonly ServedTool[], name: string | undefined): ServerInfoToolsAnswer {
+  const tools = served.map((tool): ServedToolContract => ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema }));
+  if (name === undefined) return { toolsHint: en.serverInfoTool.toolsHint, tools };
+  const named = tools.filter((tool) => tool.name === name);
+  if (named.length > 0) return { toolsHint: en.serverInfoTool.toolsHint, tools: named };
+  return { toolsHint: en.serverInfoTool.unknownToolHint, tools: [], toolNames: tools.map((tool) => tool.name).sort() };
+}
+
 /** 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 {

package/src/server/tool-list.ts

@@ -42,9 +42,14 @@ export interface MeasureToolListOptions {
 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);
+  return describeToolList(await listRecordedTools(registerTools, options), release);
+}
+
+/** The tools as `tools/list` answers them, registered on a recording server shaped like the served one. */
+export async function listRecordedTools(registerTools: RegisterTools, options: MeasureToolListOptions = {}): Promise<ServedTool[]> {
+  const server = new McpServer({ name: options.name ?? "tool-list", version: options.release ?? DEFAULT_TOOL_LIST_RELEASE }, options.serverOptions);
   await registerTools(server);
-  return describeToolList(await listServedTools(() => server), release);
+  return listServedTools(() => server);
 }
 
 /** The version and count for a listed tool set. */