@modelprofile.com/flexharness 10.20.0 → 10.21.0

package/ts_mcp/index.ts

@@ -124,62 +124,30 @@ export const createMcpTools = async (
 
     const exposedTools: plugins.ToolSet = {};
     const toolNameMap: Record<string, IMcpToolNameMapping> = {};
-    const usedToolNames = new Set<string>(['invalid']);
-    const formatResult = options.formatResult ?? formatMcpToolResult;
     const shouldPrefixToolNames = options.prefixToolNames ?? connectedServers.length > 1;
 
-    for (const server of connectedServers) {
-      for (const mcpTool of server.tools) {
-        const baseToolName = createExposedToolName(server.name, mcpTool.name, shouldPrefixToolNames);
-        const exposedToolName = createUniqueToolName(baseToolName, usedToolNames);
-        usedToolNames.add(exposedToolName);
-        toolNameMap[exposedToolName] = {
+    for (const { server, tool: mcpTool, exposedToolName } of nameMcpTools(connectedServers, shouldPrefixToolNames)) {
+      toolNameMap[exposedToolName] = {
+        serverName: server.name,
+        toolName: mcpTool.name,
+      };
+
+      exposedTools[exposedToolName] = plugins.tool({
+        description: mcpTool.description ?? `MCP tool ${mcpTool.name} from ${server.name}`,
+        inputSchema: plugins.jsonSchema(mcpTool.inputSchema as never),
+        execute: async (input: unknown, invocationOptions?: plugins.ToolExecutionOptions<unknown>) => callMcpTool({
           serverName: server.name,
           toolName: mcpTool.name,
-        };
-
-        exposedTools[exposedToolName] = plugins.tool({
-          description: mcpTool.description ?? `MCP tool ${mcpTool.name} from ${server.name}`,
-          inputSchema: plugins.jsonSchema(mcpTool.inputSchema as never),
-          execute: async (input: unknown, invocationOptions?: plugins.ToolExecutionOptions<unknown>) => {
-            const normalizedArguments = normalizeMcpArguments(input);
-            await options.authorizeToolCall?.({
-              serverName: server.name,
-              toolName: mcpTool.name,
-              exposedToolName,
-              arguments: normalizedArguments,
-              tool: mcpTool,
-              toolCallId: invocationOptions?.toolCallId ?? '',
-              abortSignal: invocationOptions?.abortSignal,
-            });
-            const configuredCallToolOptions: plugins.RequestOptions = {
-              ...options.requestOptions,
-              ...options.callToolRequestOptions,
-            };
-            const result = await withMcpRequestOptions(
-              configuredCallToolOptions,
-              invocationOptions?.abortSignal,
-              (requestOptions) => server.client.callTool(
-                {
-                  name: mcpTool.name,
-                  arguments: normalizedArguments,
-                },
-                undefined,
-                requestOptions,
-              ),
-            );
-            const formattedResult = formatResult(result, {
-              serverName: server.name,
-              toolName: mcpTool.name,
-              exposedToolName,
-            });
-            if ((result as Record<string, unknown>).isError === true) {
-              throw new Error(formatMcpError(formattedResult));
-            }
-            return formattedResult;
-          },
-        });
-      }
+          tool: mcpTool,
+          exposedToolName,
+          arguments: normalizeMcpArguments(input),
+          toolCallId: invocationOptions?.toolCallId ?? '',
+          abortSignal: invocationOptions?.abortSignal,
+          authorize: (context) => options.authorizeToolCall?.(context),
+          client: () => server.client,
+          options,
+        }),
+      });
     }
 
     return {
@@ -197,6 +165,114 @@ export const createMcpTools = async (
   }
 };
 
+/** The tools one MCP server lists, as `listTools` answered them. `IMcpConnectedServer` is one. */
+export interface IMcpToolCatalogServer {
+  name: string;
+  tools: readonly TMcpToolMetadata[];
+}
+
+export interface IMcpToolCatalogToolContext extends IMcpToolFormatContext {
+  tool: TMcpToolMetadata;
+}
+
+/** A catalog call of an MCP tool: the run's `call` context names the scope, session, run and `requestPermission`. */
+export interface IMcpToolCatalogCallContext<TScope = unknown> extends IMcpToolFormatContext {
+  call: plugins.IFlexCatalogRunContext<TScope>;
+}
+
+export interface IMcpToolCatalogAuthorizeToolCallContext<TScope = unknown> extends IMcpAuthorizeToolCallContext {
+  abortSignal: AbortSignal;
+  call: plugins.IFlexCatalogRunContext<TScope>;
+}
+
+export interface ICreateMcpToolCatalogOptions<TScope = unknown> {
+  /** The servers and the tools they list, in the order `createMcpTools` was given them. */
+  servers: readonly IMcpToolCatalogServer[];
+  /**
+   * The client that runs a call: the one connected for the call's run, which `call.provider.runId`
+   * names. The catalog stays the same object across runs; only the clients change.
+   */
+  resolveClient(context: IMcpToolCatalogCallContext<TScope>): IMcpClientLike | PromiseLike<IMcpClientLike>;
+  /** As for `createMcpTools`: `<server>__<tool>`, by default when there is more than one server. */
+  prefixToolNames?: boolean;
+  requestOptions?: plugins.RequestOptions;
+  callToolRequestOptions?: plugins.RequestOptions;
+  formatResult?: (result: TMcpCallToolResult, context: IMcpToolFormatContext) => unknown;
+  /**
+   * Resolve to allow the call, or throw to deny it, before the client is resolved. It sees `execute`
+   * and `run_code` calls as `createMcpTools`' hook sees tool calls. Omission allows all calls.
+   */
+  authorizeToolCall?: (context: IMcpToolCatalogAuthorizeToolCallContext<TScope>) => PromiseLike<void> | void;
+  /**
+   * Declares a tool's method read-only: its calls run concurrently with other reads and a turn
+   * answers identical ones once. A tool whose calls ask for permission must not be. Omission
+   * declares none; a server's `readOnlyHint` annotation is not trusted for it.
+   */
+  isReadOnly?: (context: IMcpToolCatalogToolContext) => boolean;
+}
+
+export interface ICreateMcpToolCatalogResult<TScope = unknown> {
+  catalog: plugins.IFlexToolCatalog<TScope>;
+  /** The server and tool of each method path. */
+  toolNameMap: Record<string, IMcpToolNameMapping>;
+}
+
+/**
+ * The MCP tools of `servers` as a tool catalog, which the model searches, describes and calls through
+ * `execute` and `run_code`. A method's path is the name `createMcpTools` gives the tool; a name that
+ * is no identifier (with `-`, or a reserved word) is declared as `FlexToolCatalog.identifierOf()`
+ * makes it. Create one catalog per set of tool definitions and return the same object on every run.
+ */
+export const createMcpToolCatalog = <TScope = unknown>(
+  options: ICreateMcpToolCatalogOptions<TScope>,
+): ICreateMcpToolCatalogResult<TScope> => {
+  if (typeof options?.resolveClient !== 'function') {
+    throw new Error('createMcpToolCatalog requires resolveClient().');
+  }
+  const shouldPrefixToolNames = options.prefixToolNames ?? options.servers.length > 1;
+  const named = nameMcpTools(options.servers, shouldPrefixToolNames);
+  // A name that is an identifier is its path; a mapped one gets a path no such name has.
+  const usedPaths = new Set(named.map(({ exposedToolName }) => exposedToolName)
+    .filter((exposedToolName) => catalogPathOf(exposedToolName) === exposedToolName));
+  const toolNameMap: Record<string, IMcpToolNameMapping> = {};
+  const methods: plugins.IFlexCatalogMethod<TScope, Record<string, unknown>>[] = [];
+  for (const { server, tool: mcpTool, exposedToolName } of named) {
+    const identifier = catalogPathOf(exposedToolName);
+    const path = identifier === exposedToolName ? identifier : createUniqueToolName(identifier, usedPaths);
+    usedPaths.add(path);
+    toolNameMap[path] = { serverName: server.name, toolName: mcpTool.name };
+    const toolContext: IMcpToolCatalogToolContext = {
+      serverName: server.name,
+      toolName: mcpTool.name,
+      exposedToolName: path,
+      tool: mcpTool,
+    };
+    const text = mcpTool.description?.trim() || `MCP tool ${mcpTool.name} from ${server.name}`;
+    const summary = summaryOf(text);
+    const description = text === summary ? undefined : truncateUtf8(text, plugins.FLEX_TOOL_CATALOG_LIMITS.maxDescriptionBytes);
+    methods.push({
+      method: path,
+      summary,
+      ...(description ? { description } : {}),
+      inputSchema: mcpTool.inputSchema,
+      ...(options.isReadOnly?.(toolContext) ? { readOnly: true } : {}),
+      run: (params, call) => callMcpTool({
+        serverName: server.name,
+        toolName: mcpTool.name,
+        tool: mcpTool,
+        exposedToolName: path,
+        arguments: normalizeMcpArguments(params),
+        toolCallId: call.toolCallId,
+        abortSignal: call.abortSignal,
+        authorize: (context) => options.authorizeToolCall?.({ ...context, abortSignal: call.abortSignal, call }),
+        client: () => options.resolveClient({ serverName: server.name, toolName: mcpTool.name, exposedToolName: path, call }),
+        options,
+      }),
+    });
+  }
+  return { catalog: { methods }, toolNameMap };
+};
+
 export const sanitizeMcpToolName = (name: string, fallback = 'mcp_tool'): string => {
   const sanitized = name
     .trim()
@@ -340,6 +416,100 @@ const normalizeMaxListToolsPages = (maxPages = DEFAULT_MAX_LIST_TOOLS_PAGES): nu
   return maxPages;
 };
 
+/** Every tool of `servers` with the name it is exposed under, unique across them, in order. */
+const nameMcpTools = <TServer extends IMcpToolCatalogServer>(
+  servers: readonly TServer[],
+  prefixToolNames: boolean,
+): Array<{ server: TServer; tool: TMcpToolMetadata; exposedToolName: string }> => {
+  const usedToolNames = new Set<string>(['invalid']);
+  const named: Array<{ server: TServer; tool: TMcpToolMetadata; exposedToolName: string }> = [];
+  for (const server of servers) {
+    for (const mcpTool of server.tools) {
+      const exposedToolName = createUniqueToolName(
+        createExposedToolName(server.name, mcpTool.name, prefixToolNames),
+        usedToolNames,
+      );
+      usedToolNames.add(exposedToolName);
+      named.push({ server, tool: mcpTool, exposedToolName });
+    }
+  }
+  return named;
+};
+
+interface IMcpToolCall extends IMcpToolFormatContext {
+  tool: TMcpToolMetadata;
+  arguments: Record<string, unknown>;
+  toolCallId: string;
+  abortSignal?: AbortSignal;
+  authorize: (context: IMcpAuthorizeToolCallContext) => PromiseLike<void> | void;
+  client: () => IMcpClientLike | PromiseLike<IMcpClientLike>;
+  options: Pick<ICreateMcpToolsOptions, 'requestOptions' | 'callToolRequestOptions' | 'formatResult'>;
+}
+
+/** Authorizes a call, runs it on the client and formats its result; an MCP error result throws. */
+const callMcpTool = async (call: IMcpToolCall): Promise<unknown> => {
+  await call.authorize({
+    serverName: call.serverName,
+    toolName: call.toolName,
+    exposedToolName: call.exposedToolName,
+    arguments: call.arguments,
+    tool: call.tool,
+    toolCallId: call.toolCallId,
+    abortSignal: call.abortSignal,
+  });
+  const client = await call.client();
+  const configuredCallToolOptions: plugins.RequestOptions = {
+    ...call.options.requestOptions,
+    ...call.options.callToolRequestOptions,
+  };
+  const result = await withMcpRequestOptions(
+    configuredCallToolOptions,
+    call.abortSignal,
+    (requestOptions) => client.callTool(
+      {
+        name: call.toolName,
+        arguments: call.arguments,
+      },
+      undefined,
+      requestOptions,
+    ),
+  );
+  const formattedResult = (call.options.formatResult ?? formatMcpToolResult)(result, {
+    serverName: call.serverName,
+    toolName: call.toolName,
+    exposedToolName: call.exposedToolName,
+  });
+  if ((result as Record<string, unknown>).isError === true) {
+    throw new Error(formatMcpError(formattedResult));
+  }
+  return formattedResult;
+};
+
+/** A catalog method path: the exposed name where it is an identifier, else the identifier made of it. */
+const catalogPathOf = (exposedToolName: string): string => plugins.FlexToolCatalog.identifierOf(exposedToolName);
+
+/** The first line of a description, as one line of at most the catalog's summary length. */
+const summaryOf = (text: string): string => {
+  const line = text.split(/\r?\n/).find((candidate) => candidate.trim())!.replace(/[\s\u0000-\u001f\u007f]+/g, ' ').trim();
+  const characters = [...line];
+  const max = plugins.FLEX_TOOL_CATALOG_LIMITS.maxSummaryCharacters;
+  return characters.length <= max ? line : `${characters.slice(0, max - 1).join('').trimEnd()}…`;
+};
+
+/** The text cut to at most `maxBytes` UTF-8 bytes on a character boundary, marked with `…` when cut. */
+const truncateUtf8 = (text: string, maxBytes: number): string => {
+  const encoder = new TextEncoder();
+  if (encoder.encode(text).length <= maxBytes) return text;
+  let bytes = encoder.encode('…').length;
+  let kept = '';
+  for (const character of text) {
+    bytes += encoder.encode(character).length;
+    if (bytes > maxBytes) break;
+    kept += character;
+  }
+  return `${kept}…`;
+};
+
 const createExposedToolName = (
   serverName: string,
   toolName: string,

package/ts_mcp/plugins.ts

@@ -10,6 +10,12 @@ export type { StreamableHTTPClientTransportOptions } from '@modelcontextprotocol
 export type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
 export type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 
+// @modelprofile.com scope
+import { FLEX_TOOL_CATALOG_LIMITS, FlexToolCatalog } from '@modelprofile.com/flexharness';
+
+export { FLEX_TOOL_CATALOG_LIMITS, FlexToolCatalog };
+export type { IFlexCatalogMethod, IFlexCatalogRunContext, IFlexToolCatalog } from '@modelprofile.com/flexharness';
+
 // ai-sdk core
 import { jsonSchema, tool } from 'ai';
 

package/ts_mcp/readme.md

@@ -8,6 +8,14 @@ the agent and harness do not install or register vendor SDKs.
 pnpm add @modelprofile.com/flexharness @modelcontextprotocol/sdk
 ```
 
+`createMcpTools()` connects MCP servers and exposes their tools as AI SDK tools.
+`createMcpToolCatalog()` makes the tools servers list into a FlexHarness tool catalog
+(`search_tools`, `describe_tools`, `execute`, `run_code`): one catalog object for every
+run, each call on the client `resolveClient` names for its run, method paths equal to
+`createMcpTools()`' tool names, `authorizeToolCall` deciding catalog calls as it decides
+tool calls, and read-only methods only where `isReadOnly` declares them. The root readme's
+Tool Catalog section shows a tool provider that connects clients per run.
+
 See the [toolbox usage and migration guide](https://code.foss.global/modelprofile.com/flexharness#readme)
 for composition examples and the SmartAI/SmartAgent migration map.