@bevel-software/platform-mcp-core 0.8.0

package/src/code-mode-names.ts

@@ -0,0 +1,107 @@
+import type { Tool } from '@utcp/sdk';
+import type { CodeModeUtcpClient } from '@utcp/code-mode';
+
+/**
+ * Pure helpers for mapping UTCP tool names to their code-mode (TypeScript)
+ * accessible form. Kept Mastra-free so the agent's Mastra tools
+ * (`code-mode.tool.ts`), the hosted MCP proxy and the local MCP server can all
+ * share them.
+ */
+
+export function sanitizeIdentifier(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_]/g, '_').replace(/^[0-9]/, '_$&');
+}
+
+/** `MANUAL.tool` → the `manual.tool` form the code-mode runtime exposes. */
+export function utcpNameToTsInterfaceName(utcpName: string): string {
+  if (utcpName.includes('.')) {
+    const [manualName, ...toolParts] = utcpName.split('.');
+    return `${sanitizeIdentifier(manualName!)}.${toolParts.map(sanitizeIdentifier).join('_')}`;
+  }
+  return sanitizeIdentifier(utcpName);
+}
+
+/**
+ * Sanitized TS name → every UTCP tool that claims it, from ONE catalog fetch.
+ * Collisions are kept, not collapsed: sanitization is lossy (`a-b` and `a_b`
+ * both become `a_b`), and a lookup that silently picked one would describe —
+ * or dispatch — the wrong tool.
+ */
+async function tsNameIndex(client: CodeModeUtcpClient): Promise<Map<string, Tool[]>> {
+  const index = new Map<string, Tool[]>();
+  for (const tool of await client.config.tool_repository.getTools()) {
+    const tsName = utcpNameToTsInterfaceName(tool.name);
+    const bucket = index.get(tsName);
+    if (bucket) bucket.push(tool);
+    else index.set(tsName, [tool]);
+  }
+  return index;
+}
+
+function resolveSanitized(
+  index: Map<string, Tool[]>,
+  name: string,
+): { tool: Tool; utcpName: string } | null {
+  const bucket = index.get(name);
+  if (!bucket || bucket.length === 0) return null;
+  if (bucket.length > 1) {
+    throw new AmbiguousToolNameError(
+      `Tool name "${name}" is ambiguous: ${bucket.map((t) => `"${t.name}"`).join(', ')} ` +
+        'all sanitize to it. Call the tool by its exact UTCP name instead.',
+    );
+  }
+  return { tool: bucket[0]!, utcpName: bucket[0]!.name };
+}
+
+/**
+ * The TYPED half of the ambiguity contract: callers that contain ambiguity
+ * per-name while letting real failures (an outage, a broken repository)
+ * fail the call need something sturdier to branch on than the message text
+ * of a bare Error thrown in another package.
+ */
+export class AmbiguousToolNameError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AmbiguousToolNameError';
+  }
+}
+
+/**
+ * Resolve a tool by its raw UTCP name or its sanitized TS-accessible name.
+ * Throws when the sanitized name is claimed by more than one tool (an exact
+ * UTCP name always wins and can't be ambiguous).
+ */
+export async function findToolByName(
+  client: CodeModeUtcpClient,
+  name: string,
+): Promise<{ tool: Tool; utcpName: string } | null> {
+  const direct = await client.config.tool_repository.getTool(name);
+  if (direct) return { tool: direct, utcpName: name };
+  return resolveSanitized(await tsNameIndex(client), name);
+}
+
+/**
+ * Resolve a batch of names against ONE catalog fetch (`tools_info` takes a
+ * list, and a per-name `getTools()` re-fetch scales with the list). Names that
+ * resolve are in the map; missing ones are simply absent; an ambiguous
+ * sanitized name throws, as in {@link findToolByName}.
+ */
+export async function findToolsByNames(
+  client: CodeModeUtcpClient,
+  names: string[],
+): Promise<Map<string, { tool: Tool; utcpName: string }>> {
+  const out = new Map<string, { tool: Tool; utcpName: string }>();
+  let index: Map<string, Tool[]> | undefined;
+  for (const name of names) {
+    if (out.has(name)) continue;
+    const direct = await client.config.tool_repository.getTool(name);
+    if (direct) {
+      out.set(name, { tool: direct, utcpName: name });
+      continue;
+    }
+    index ??= await tsNameIndex(client);
+    const resolved = resolveSanitized(index, name);
+    if (resolved) out.set(name, resolved);
+  }
+  return out;
+}

package/src/dispatch.ts

@@ -0,0 +1,88 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CodeModeUtcpClient } from '@utcp/code-mode';
+import type { CallTemplate } from '@utcp/sdk';
+import type { ProxiedTool } from './proxied-tool.js';
+import { toCallToolResult, toolError, describeToolFailure, renderProgress } from './results.js';
+
+/**
+ * Register one manual on a client, reduced to a verdict.
+ *
+ * Deliberately NOT a loop over every manual: the two surfaces disagree about
+ * what a failure means. The hosted proxy memoizes per (user, manual) so a
+ * broken credential doesn't re-dial its provider on every session rebuild; the
+ * local server has one user and one process and just logs. Sharing the
+ * per-manual mechanics without sharing the retry policy keeps both honest.
+ *
+ * Never throws: a registration failure is a runtime problem (network, dead
+ * credential), not a schema one — the templates were validated before they got
+ * here — so it comes back as `{ ok: false }` for the caller to police.
+ */
+export async function registerManual(
+  client: CodeModeUtcpClient,
+  manual: CallTemplate,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    const result = await client.registerManual(manual);
+    if (result && result.success === false) {
+      const errors = Array.isArray(result.errors) ? result.errors.join('; ') : 'unknown error';
+      return { ok: false, error: errors };
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Run one tool call through `callToolStreaming` with a one-chunk lookahead:
+ * every chunk except the last becomes a progress notification, the last is the
+ * result.
+ *
+ * Dispatch always uses `callToolStreaming`, which is uniform across tool kinds:
+ * a plain `http` tool yields exactly one chunk (its final result, emitted as
+ * the tool result with no progress), while a `streamable_http` tool yields many.
+ * Because of that, adding — or later upgrading a tool to streaming — never
+ * touches this function.
+ *
+ * Continuity is the caller's: a tool that supports it (e.g. `ask`) returns its
+ * `sessionId` in the result verbatim, and the caller echoes it back per the
+ * tool's own schema — nothing here rewrites args. Args pass through to UTCP
+ * verbatim; each communication protocol does its own serialization (http reads
+ * the template's `body_field` out of the args, mcp forwards them untouched as
+ * MCP `arguments`), and the advertised schema is the tool's UTCP `inputs`
+ * verbatim too, so any reshaping here would be wrong for at least one protocol.
+ */
+export async function dispatchToolCall(
+  client: CodeModeUtcpClient,
+  tool: ProxiedTool,
+  args: Record<string, unknown>,
+  onProgress?: (progress: number, message: string) => Promise<void>,
+): Promise<CallToolResult> {
+  let prev: unknown;
+  let hasPrev = false;
+  let progress = 0;
+
+  try {
+    for await (const chunk of client.callToolStreaming(tool.utcpName, args)) {
+      if (hasPrev && onProgress) {
+        progress += 1;
+        await onProgress(progress, renderProgress(prev)).catch((err) =>
+          console.warn('[mcp] progress notification failed:', err),
+        );
+      }
+      prev = chunk;
+      hasPrev = true;
+    }
+  } catch (err) {
+    return toolError(`The "${tool.mcpName}" tool failed: ${describeToolFailure(err)}`);
+  }
+
+  // A stream that closes without ever yielding is a transport fault, not an
+  // empty result — every tool kind yields at least its final value (see above).
+  // Say so, instead of serializing the never-assigned `prev` into a "null".
+  if (!hasPrev) {
+    return toolError(`The "${tool.mcpName}" tool produced no output: its stream ended without a result.`);
+  }
+
+  return toCallToolResult(prev);
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+/**
+ * @bevel-software/platform-mcp-core — the transport-agnostic half of Bevel's
+ * MCP surface.
+ *
+ * Two surfaces re-expose the same UTCP tool catalog over MCP and differ only in
+ * where they run and how they reach it:
+ *
+ *   - the HOSTED proxy (`platform-core-backend`) registers the KB manual over
+ *     loopback plus each `.tool` the caller can read, resolves `${VAR}` from
+ *     the Secrets Vault, and speaks streamable HTTP;
+ *   - the LOCAL server (`@bevel-software/hexis-mcp`) registers the deployment's
+ *     own MCP endpoint as one `mcp` manual plus the `remote: false` manuals the
+ *     hosted endpoint cannot serve, resolves `${VAR}` from the process env, and
+ *     speaks stdio.
+ *
+ * Everything between "a UTCP client with manuals registered" and "an MCP result"
+ * is identical, and lives here: name flattening, the tool-name/schema guards
+ * that stop one bad tool blanking a client's whole toolset, streaming dispatch,
+ * and the code-mode meta-tools.
+ *
+ * What is NOT here, on purpose: manual DISCOVERY (who may see which manual is
+ * an access-control question the hosted REST surface answers), credential
+ * resolution (a vault loader server-side, `process.env` locally), and retry
+ * policy (see `registerManual`).
+ */
+
+export {
+  type ProxiedTool,
+  toListedTool,
+  sanitizeInputSchema,
+  flattenManualTool,
+  flattenDiscoveredTool,
+} from './proxied-tool.js';
+
+export {
+  describeToolFailure,
+  toCallToolResult,
+  renderProgress,
+  toolError,
+  needsAuthorizationResult,
+} from './results.js';
+
+export {
+  CODE_MODE_META_TOOLS,
+  META_TOOL_NAMES,
+  CALL_TOOL_CHAIN_MAX_OUTPUT,
+  type SpillPort,
+  dispatchMetaTool,
+} from './meta-tools.js';
+
+export { registerManual, dispatchToolCall } from './dispatch.js';
+
+export {
+  type SkillSummary,
+  type LoadedSkill,
+  skillPromptText,
+} from './skills.js';
+
+export {
+  utcpNamespacePrefix,
+  utcpNamespacedKey,
+  seedBevelHostedManualVars,
+} from './utcp-namespace.js';
+
+export {
+  sanitizeIdentifier,
+  utcpNameToTsInterfaceName,
+  findToolByName,
+  findToolsByNames,
+  AmbiguousToolNameError,
+} from './code-mode-names.js';

package/src/meta-tools.ts

@@ -0,0 +1,186 @@
+import type { Tool as McpTool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CodeModeUtcpClient } from '@utcp/code-mode';
+import { utcpNameToTsInterfaceName, findToolsByNames } from './code-mode-names.js';
+import { toCallToolResult, toolError, describeToolFailure } from './results.js';
+
+/**
+ * Code-mode meta-tools exposed ALONGSIDE the direct tools. They let an external
+ * agent batch many Bevel calls into one isolated-vm run (`call_tool_chain`)
+ * instead of one MCP round-trip per call — the same efficiency our own agent
+ * gets. `call_tool_chain`'s description carries the code-mode protocol (there is
+ * no system prompt over MCP), so the client learns the convention from the tool
+ * itself; `list_tools`/`tools_info` are how it discovers what to call.
+ *
+ * Security is identical to the direct surface: the chain runs in an isolated-vm
+ * but calls tools with the CALLER's credentials against the external catalog —
+ * internal-only tools aren't in that catalog, so a chain can't reach them either.
+ *
+ * These three belong to whichever client holds the registry. A surface that
+ * registers ANOTHER Bevel MCP endpoint as one of its manuals therefore has to
+ * drop that endpoint's copies from the passthrough (see {@link META_TOOL_NAMES}):
+ * the remote trio describes the remote registry, and locally they must describe
+ * the merged one.
+ */
+const CALL_TOOL_CHAIN_DESCRIPTION = [
+  'Execute a short JavaScript program with direct access to every registered UTCP tool as a synchronous function. Call tools as `KNOWLEDGE_BASE.<tool>({ body: { ...args } })` with NO `await` (results are already resolved), and `return` the final value. The runtime is plain JavaScript (no type annotations / no TypeScript-only syntax).',
+  'Discover first: `list_tools` lists every tool in callable form (e.g. `KNOWLEDGE_BASE.read_file`); `tools_info` returns their exact argument + return shapes — do not guess. Batch multiple tool calls into one chain to avoid a round-trip per call. The chain runs with your own connection key, so it can only reach the tools you can already call directly.',
+  'Large results: if the combined result+logs exceed `max_output_size` (default 200000 chars) the full JSON is spilled to a shared store and you get back a `__tool_chain_spill__/…` ref instead. Read it with `read_file` (pass that ref as `path` — `branch` is ignored — plus `offset`/`limit` to slice it), or better, re-run a narrower chain that returns only what you need.',
+].join('\n\n');
+
+export const CODE_MODE_META_TOOLS: McpTool[] = [
+  {
+    name: 'list_tools',
+    description:
+      'List every UTCP tool currently registered, in TypeScript-accessible form (e.g. `KNOWLEDGE_BASE.read_file`) for use inside `call_tool_chain`.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false } as McpTool['inputSchema'],
+  },
+  {
+    name: 'tools_info',
+    description:
+      'Get full TypeScript interface definitions for named tools (names from `list_tools`). The schemas are the source of truth — do not guess shapes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tool_names: { type: 'array', items: { type: 'string' }, minItems: 1, description: 'Tool names to describe.' },
+      },
+      required: ['tool_names'],
+      additionalProperties: false,
+    } as McpTool['inputSchema'],
+  },
+  {
+    name: 'call_tool_chain',
+    description: CALL_TOOL_CHAIN_DESCRIPTION,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        code: { type: 'string', minLength: 1, description: 'JavaScript to execute against the registered tools.' },
+        timeout: { type: 'integer', minimum: 1000, maximum: 120000, description: 'Timeout in ms (default 30000).' },
+        max_output_size: { type: 'integer', minimum: 1000, maximum: 1000000, description: 'Max result+logs size in chars before spilling (default 200000, max 1000000).' },
+      },
+      required: ['code'],
+      additionalProperties: false,
+    } as McpTool['inputSchema'],
+  },
+];
+
+export const META_TOOL_NAMES: ReadonlySet<string> = new Set(CODE_MODE_META_TOOLS.map((t) => t.name));
+
+/** Default cap on a `call_tool_chain` result's stringified size before it spills. */
+export const CALL_TOOL_CHAIN_MAX_OUTPUT = 200_000;
+
+/**
+ * UTF-8 byte length without Node's `Buffer` — this module stays free of
+ * runtime-specific globals. Matches `Buffer.byteLength`: a lone surrogate
+ * encodes as the 3-byte replacement character.
+ */
+function utf8ByteLength(s: string): number {
+  let bytes = 0;
+  for (const ch of s) {
+    const cp = ch.codePointAt(0)!;
+    bytes += cp <= 0x7f ? 1 : cp <= 0x7ff ? 2 : cp <= 0xffff ? 3 : 4;
+  }
+  return bytes;
+}
+
+/**
+ * Where an oversized `call_tool_chain` payload goes. The hosted proxy hands in
+ * the shared workspace spill store, whose refs `read_file` can read back. A
+ * surface with nowhere to put it (the local server has no server-side store of
+ * its own) passes nothing and gets a truncation notice instead — the caller is
+ * told to narrow the chain rather than handed a ref that resolves nowhere.
+ */
+export interface SpillPort {
+  write(json: string): Promise<{ ref: string; bytes: number }>;
+}
+
+/**
+ * Handle a code-mode meta-tool. `list_tools`/`tools_info` reflect on the
+ * client's discovered catalog; `call_tool_chain` runs the caller's JavaScript in
+ * the client's isolated-vm, where every registered tool is reachable as
+ * `<manual>.tool(...)`.
+ */
+export async function dispatchMetaTool(
+  client: CodeModeUtcpClient,
+  name: string,
+  args: Record<string, unknown>,
+  spill?: SpillPort,
+): Promise<CallToolResult> {
+  try {
+    if (name === 'list_tools') {
+      const tools = await client.config.tool_repository.getTools();
+      return toCallToolResult({ tools: tools.map((t) => utcpNameToTsInterfaceName(t.name)) });
+    }
+    if (name === 'tools_info') {
+      // The schema is advisory over a raw JSON-RPC call: a missing array or a
+      // non-string entry must be a named validation error here, not a generic
+      // failure out of a repository lookup it was never valid input for.
+      const rawNames = args.tool_names;
+      // Empty included — the schema says minItems 1, and an empty success
+      // payload for invalid input would read as "no tools exist".
+      if (!Array.isArray(rawNames) || rawNames.length === 0 || rawNames.some((n) => typeof n !== 'string')) {
+        return toolError('The "tools_info" tool requires "tool_names": a non-empty array of tool name strings.');
+      }
+      const names = rawNames as string[];
+      const interfaces: string[] = [];
+      const notFound: string[] = [];
+      const resolved = await findToolsByNames(client, names);
+      for (const n of names) {
+        const found = resolved.get(n);
+        if (found) interfaces.push(client.toolToTypeScriptInterface(found.tool));
+        else notFound.push(n);
+      }
+      return toCallToolResult({ interfaces: interfaces.join('\n\n'), not_found: notFound });
+    }
+    // call_tool_chain
+    // Same advisory-schema rule as above: a missing or non-string `code` must
+    // not silently execute an empty program and report success.
+    const code = args.code;
+    if (typeof code !== 'string' || code.length === 0) {
+      return toolError('The "call_tool_chain" tool requires a non-empty "code" string.');
+    }
+    // Clamp both knobs to their schema bounds — the schema is advisory over a
+    // raw JSON-RPC call, and an unclamped `timeout` would let one chain hold
+    // the isolate far past the documented 120s cap.
+    const timeout =
+      typeof args.timeout === 'number' && Number.isFinite(args.timeout)
+        ? Math.min(120_000, Math.max(1_000, Math.trunc(args.timeout)))
+        : 30_000;
+    // Clamp to [1000, 1_000_000] so a caller can't force oversized inline
+    // output past the spill.
+    const maxOutputSize =
+      typeof args.max_output_size === 'number' && Number.isFinite(args.max_output_size)
+        ? Math.min(1_000_000, Math.max(1_000, Math.trunc(args.max_output_size)))
+        : CALL_TOOL_CHAIN_MAX_OUTPUT;
+    const { result, logs } = await client.callToolChain(code, timeout);
+    // Bound the payload: an external session has no ambient workspace, so an
+    // oversized result spills to the shared store and we return only a ref —
+    // parity with the in-process agent's `call_tool_chain`.
+    if (JSON.stringify({ success: true, result, logs }).length <= maxOutputSize) {
+      return toCallToolResult({ success: true, result, logs });
+    }
+    const fullJson = JSON.stringify({ result, logs }, null, 2);
+    if (!spill) {
+      return toCallToolResult({
+        success: true,
+        truncated: true,
+        // Bytes, not chars: the spill branch reports the store's byte count,
+        // and `result_bytes` must mean one thing across both paths.
+        result_bytes: utf8ByteLength(fullJson),
+        message:
+          `Result+logs payload was ${fullJson.length} characters (exceeded max_output_size of ${maxOutputSize}), ` +
+          'and this server has no spill store to park it in. Re-run a narrower chain that returns only what you ' +
+          'need, or raise max_output_size.',
+      });
+    }
+    const { ref, bytes } = await spill.write(fullJson);
+    return toCallToolResult({
+      success: true,
+      truncated: true,
+      result_ref: ref,
+      result_bytes: bytes,
+      message: `Result+logs payload was ${fullJson.length} characters (exceeded max_output_size of ${maxOutputSize}). Full JSON saved to the shared spill store as \`${ref}\`. Read it back with \`read_file\` (pass that ref as \`path\`, \`branch\` ignored, plus \`offset\`/\`limit\` to slice), or re-run a narrower chain that returns only what you need.`,
+    });
+  } catch (err) {
+    return toolError(`The "${name}" tool failed: ${describeToolFailure(err)}`);
+  }
+}

package/src/proxied-tool.ts

@@ -0,0 +1,200 @@
+import type { Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
+import type { JsonSchema, Tool as UtcpTool } from '@utcp/sdk';
+
+/** A tool discovered from a UTCP manual, flattened into what an MCP surface advertises. */
+export interface ProxiedTool {
+  utcpName: string;
+  mcpName: string;
+  description: string;
+  inputSchema: JsonSchema;
+  /** The UTCP manual this tool came from (the `<manual>` in `<manual>.<tool>`),
+   * used to look up the manual's declared per-user credentials before dispatch. */
+  manualName: string;
+}
+
+/**
+ * MCP tool-name grammar (also the Anthropic API's), and a length bound. A
+ * remote MCP server can expose a tool whose flattened name breaks this — too
+ * long, or an illegal char the `<manual>_<name>` flattening didn't remove — and
+ * an MCP client (or the model API behind it) rejects the ENTIRE `tools/list`
+ * response when a single entry is non-conforming. That makes EVERY tool vanish
+ * the moment one bad tool from a newly-added server enters the catalog, with no
+ * server-side error (the rejection is the client's). `toListedTool` isolates it
+ * per tool: drop the offender (logged), normalize an odd schema, keep the rest.
+ */
+const MCP_TOOL_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+// The Anthropic API caps a tool name at 128 chars — but the MCP CLIENT (Claude
+// Code, claude.ai) prepends `mcp__<server>__` (≈20+ chars) before sending it,
+// and that FULL name is what the 128 applies to. So budget for the prefix here,
+// or a long `googlecalendar_…` name we pass gets the whole request 400'd. This
+// is deliberately conservative; a dropped tool is logged so it's diagnosable.
+const MCP_TOOL_NAME_MAX = 100;
+
+/** A discovered tool as an MCP listing entry, or null if its name can't be listed. */
+export function toListedTool(tool: ProxiedTool): McpTool | null {
+  if (!MCP_TOOL_NAME_RE.test(tool.mcpName) || tool.mcpName.length > MCP_TOOL_NAME_MAX) {
+    console.warn(
+      `[mcp] dropping tool "${tool.mcpName}" from the listing — not a valid MCP tool name ` +
+        `(must match ${MCP_TOOL_NAME_RE} and be ≤${MCP_TOOL_NAME_MAX} chars). ` +
+        'One non-conforming tool would otherwise make the whole toolset disappear on the client.',
+    );
+    return null;
+  }
+  // MCP requires an object inputSchema. A remote server's schema that isn't a
+  // plain object (or omits `type: 'object'`) can invalidate the whole response,
+  // so normalize it — keeping any declared properties — rather than pass it
+  // through verbatim.
+  const raw = tool.inputSchema;
+  let inputSchema: Record<string, unknown> =
+    raw && typeof raw === 'object' && !Array.isArray(raw)
+      ? { type: 'object', ...(raw as Record<string, unknown>) }
+      : { type: 'object', properties: {} };
+  // Sanitize the schema into what the Anthropic tool validator accepts. A
+  // remote server that emits a construct the validator rejects — Google's
+  // gmail/calendar use `$ref`/`$defs` AND OpenAPI `format` values like
+  // `int32`/`byte` — makes the CLIENT reject the ENTIRE tools/list response,
+  // so all tools vanish and nothing registers. Sanitizing per-tool means one
+  // odd server can't blank the whole toolset.
+  inputSchema = sanitizeInputSchema(inputSchema) as Record<string, unknown>;
+  // The MCP/Anthropic validator requires the top-level `type` to be exactly
+  // "object" and (for the Anthropic API) `properties` to be present. Force both
+  // so a remote schema that declared something else — or a union like
+  // `["object","null"]` — can't reject the whole tools/list.
+  inputSchema.type = 'object';
+  // An array passes `typeof === 'object'` but is not a property map, so it
+  // must coerce like any other non-object or it poisons the whole listing.
+  if (
+    typeof inputSchema.properties !== 'object' ||
+    inputSchema.properties === null ||
+    Array.isArray(inputSchema.properties)
+  ) {
+    inputSchema.properties = {};
+  }
+  return {
+    name: tool.mcpName,
+    description: tool.description,
+    inputSchema: inputSchema as McpTool['inputSchema'],
+  };
+}
+
+/** JSON-Schema string `format` values the Anthropic tool validator accepts. */
+const SUPPORTED_SCHEMA_FORMATS = new Set([
+  'date-time',
+  'time',
+  'date',
+  'duration',
+  'email',
+  'hostname',
+  'uri',
+  'ipv4',
+  'ipv6',
+  'uuid',
+]);
+
+/**
+ * Make a remote server's JSON Schema safe for the Anthropic tool validator:
+ *  - inline local `$ref` pointers (`#/$defs/...`, `#/definitions/...`) and drop
+ *    the now-unreferenced `$defs`/`definitions` blocks (the API restricts `$ref`
+ *    and MCP clients converting our schemas reject it outright);
+ *  - drop non-standard `format` values (OpenAPI's `int32`/`byte`/… — only the
+ *    JSON-Schema-standard formats above are accepted; `format` is advisory, so
+ *    dropping it doesn't change tool behavior).
+ * Depth-bounded so a recursive schema degrades to a permissive `{}` node instead
+ * of hanging or emitting the unsupported recursion; non-local/external refs
+ * degrade the same way. Exported for direct testing.
+ */
+export function sanitizeInputSchema(schema: unknown): unknown {
+  const root = schema;
+  const resolvePointer = (pointer: string): unknown => {
+    if (!pointer.startsWith('#/')) return undefined;
+    let node: unknown = root;
+    for (const partRaw of pointer.slice(2).split('/')) {
+      const part = partRaw.replace(/~1/g, '/').replace(/~0/g, '~');
+      if (!node || typeof node !== 'object') return undefined;
+      node = (node as Record<string, unknown>)[part];
+    }
+    return node;
+  };
+  // `isPropertyMap` marks the value of `properties`/`patternProperties`: its
+  // keys are the tool's OWN field names, not schema keywords, so a field
+  // literally named `format`, `$ref` or `definitions` must survive untouched
+  // (its VALUE is still a schema and is walked as one).
+  const walk = (node: unknown, depth: number, isPropertyMap = false): unknown => {
+    if (depth > 20) return {}; // recursion/cycle guard — permissive fallback
+    if (Array.isArray(node)) return node.map((item) => walk(item, depth + 1));
+    if (!node || typeof node !== 'object') return node;
+    const obj = node as Record<string, unknown>;
+    if (!isPropertyMap && typeof obj.$ref === 'string') {
+      const target = resolvePointer(obj.$ref);
+      // JSON Schema allows siblings next to $ref; keep them, target wins ties.
+      const siblings: Record<string, unknown> = { ...obj };
+      delete siblings.$ref;
+      const resolved = walk(target ?? {}, depth + 1);
+      return resolved && typeof resolved === 'object' && !Array.isArray(resolved)
+        ? { ...siblings, ...(resolved as Record<string, unknown>) }
+        : Object.keys(siblings).length
+          ? siblings
+          : resolved ?? {};
+    }
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      if (isPropertyMap) {
+        out[key] = walk(value, depth + 1);
+        continue;
+      }
+      if (key === '$defs' || key === 'definitions') continue; // inlined above
+      // Drop a non-standard `format` (OpenAPI `int32`/`byte`/…) — the validator
+      // only allows the JSON-Schema-standard set; the annotation is non-load-bearing.
+      if (key === 'format' && (typeof value !== 'string' || !SUPPORTED_SCHEMA_FORMATS.has(value))) {
+        continue;
+      }
+      out[key] = walk(value, depth + 1, key === 'properties' || key === 'patternProperties');
+    }
+    return out;
+  };
+  return walk(schema, 0);
+}
+
+/**
+ * Flatten a discovered UTCP tool (`<manual>.<tool>`) into the advertised shape
+ * when MULTIPLE manuals are registered. Tools from `kbManualName` keep their
+ * bare name (so existing agents still call `read_file`); every other manual's
+ * tool is namespaced as `<manual>_<tool>` to guarantee a unique, dot-free MCP
+ * name.
+ *
+ * `kbManualName` is a parameter rather than a constant because the two surfaces
+ * that call this reach the KB through different manuals: the hosted proxy
+ * registers it over loopback, the local server registers the deployment's MCP
+ * endpoint. Whichever manual carries the core toolset is the one whose names
+ * must stay bare.
+ */
+export function flattenManualTool(tool: UtcpTool, kbManualName: string): ProxiedTool {
+  const dot = tool.name.indexOf('.');
+  const manual = dot >= 0 ? tool.name.slice(0, dot) : '';
+  const bare = dot >= 0 ? tool.name.slice(dot + 1) : tool.name;
+  const mcpName = manual === kbManualName ? bare : tool.name.replace(/\./g, '_');
+  return {
+    utcpName: tool.name,
+    mcpName,
+    description: tool.description,
+    inputSchema: tool.inputs,
+    manualName: manual,
+  };
+}
+
+/**
+ * Flatten one discovered UTCP tool into the advertised shape: strip the
+ * `<manual>.` namespace prefix for the MCP name and keep the UTCP input schema
+ * verbatim (Bevel-hosted HTTP tools show their `{body}` envelope, exactly as in
+ * `call_tool_chain`).
+ */
+export function flattenDiscoveredTool(prefix: string, tool: UtcpTool): ProxiedTool {
+  return {
+    utcpName: tool.name,
+    mcpName: tool.name.startsWith(prefix) ? tool.name.slice(prefix.length) : tool.name,
+    description: tool.description,
+    inputSchema: tool.inputs,
+    // `prefix` is `<manual>.`; the manual is that without the trailing dot.
+    manualName: prefix.endsWith('.') ? prefix.slice(0, -1) : prefix,
+  };
+}