@softure-ai/mcp-access 0.2.5 → 0.2.8

package/src/server/tools.ts

@@ -1,8 +1,9 @@
 // Tool results for the app's MCP server and the boundary that keeps failures safe: the assistant gets
 // a value, a `PublicError`'s message or a hint, never a thrown error's text (a failed query carries
-// its SQL and parameters). The log gets the error's kind only (`errorLogLabel`).
+// its SQL and parameters). The log gets the error's kind only (`errorLogLabel`). An optional hook sees
+// each call as a whole: which tool, which client, the outcome with its code, and how long it took.
 import { isCallToolResult, type CallToolResult } from "@modelcontextprotocol/server";
-import { errorLogLabel, getPublicMessage, safeError } from "@softure-ai/core";
+import { errorLogLabel, getPublicMessage, safeError, type CoreErrorCode } from "@softure-ai/core";
 
 /** What the assistant reads for an error code: the app's own text per code, e.g. `{ "orders.not_found": "No order with that number." }`. */
 export type ToolErrorHints = Readonly<Record<string, string>>;
@@ -10,10 +11,46 @@ export type ToolErrorHints = Readonly<Record<string, string>>;
 export interface ToolErrorOptions {
   /** Texts per error code; a code without one is answered as the code itself. */
   readonly hints?: ToolErrorHints;
-  /** The tool's name in the log line. */
+  /** The tool's name in the log line and in the `onToolCall` record. */
   readonly label?: string;
+  /** Called once after each call with its record. Its failure is logged by kind and never changes the answer. */
+  readonly onToolCall?: ToolCallHook;
+  /** Who called, for the record: built once per request in the app's server factory. */
+  readonly caller?: ToolCaller;
+  /** The tool's arguments, for the record: only their names are read, never their values. */
+  readonly args?: Readonly<Record<string, unknown>>;
 }
 
+/** The client behind a call: the token's id (`McpServerIdentity.tokenId`) and its name (`findTokenClientName`). */
+export interface ToolCaller {
+  readonly tokenId: string;
+  readonly clientName: string | null;
+}
+
+/**
+ * How a call ended. `succeeded`: `itemCount` is the length of an array value, else `null`. `failed`: the
+ * result's error code, `null` for a `CallToolResult` the tool marked `isError` itself. `thrown`: the
+ * `safeError` code, `null` for a `PublicError` (a deliberate message, no code).
+ */
+export type ToolCallOutcome =
+  | { readonly kind: "succeeded"; readonly itemCount: number | null }
+  | { readonly kind: "failed"; readonly code: string | null }
+  | { readonly kind: "thrown"; readonly code: CoreErrorCode | null };
+
+/** One tool call as the `onToolCall` hook sees it. */
+export interface ToolCallRecord {
+  /** The tool's `label`, else `"call"`. */
+  readonly tool: string;
+  readonly tokenId: string | null;
+  readonly clientName: string | null;
+  readonly argumentNames: readonly string[];
+  readonly outcome: ToolCallOutcome;
+  readonly startedAt: Date;
+  readonly durationMs: number;
+}
+
+export type ToolCallHook = (record: ToolCallRecord) => unknown;
+
 /** For failures the tool did not expect: what `safeError` makes of them, unless a hint replaces it. */
 const DEFAULT_FAILURE_TEXT: ToolErrorHints = {
   "core.database_failed": "The database could not answer; try again later.",
@@ -37,11 +74,47 @@ export function toolError(message: string): CallToolResult {
  * anything else is logged by kind and answered with the hint for its `safeError` code, else a fixed text.
  */
 export async function withToolErrors(work: () => unknown, options: ToolErrorOptions = {}): Promise<CallToolResult> {
+  const startedAt = Date.now();
+  let answer: CallToolResult;
+  let outcome: ToolCallOutcome;
   try {
-    return answerValue(await work(), options.hints);
+    const value = await work();
+    answer = answerValue(value, options.hints);
+    outcome = describeValueOutcome(value);
   } catch (error) {
-    return answerFailure(error, options);
+    answer = answerFailure(error, options);
+    outcome = { kind: "thrown", code: getPublicMessage(error) === null ? safeError(error).error : null };
   }
+  if (options.onToolCall !== undefined) await reportToolCall(options, outcome, startedAt);
+  return answer;
+}
+
+async function reportToolCall(options: ToolErrorOptions, outcome: ToolCallOutcome, startedAt: number): Promise<void> {
+  const tool = options.label ?? "call";
+  const record: ToolCallRecord = {
+    tool,
+    tokenId: options.caller?.tokenId ?? null,
+    clientName: options.caller?.clientName ?? null,
+    argumentNames: Object.keys(options.args ?? {}),
+    outcome,
+    startedAt: new Date(startedAt),
+    durationMs: Date.now() - startedAt,
+  };
+  try {
+    await options.onToolCall?.(record);
+  } catch (error) {
+    console.error(`@softure-ai/mcp-access: the onToolCall hook failed for tool ${tool}: ${errorLogLabel(error)}`);
+  }
+}
+
+function describeValueOutcome(value: unknown): ToolCallOutcome {
+  if (isCallToolResult(value)) return value.isError === true ? { kind: "failed", code: null } : { kind: "succeeded", itemCount: null };
+  if (isResult(value)) return value.ok ? countItems(value.value) : { kind: "failed", code: value.error };
+  return countItems(value);
+}
+
+function countItems(value: unknown): ToolCallOutcome {
+  return { kind: "succeeded", itemCount: Array.isArray(value) ? value.length : null };
 }
 
 /** The answer for a value a tool or an action returned. */

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