@bevel-software/platform-mcp-core 0.26.0 → 0.27.0

package/src/mcp-app.ts

@@ -0,0 +1,194 @@
+/**
+ * The MCP Apps extension (`io.modelcontextprotocol/ui`, specification
+ * 2026-01-26), as much of it as a SERVER has to speak.
+ *
+ * The pattern is two primitives tied together by one URI: a tool whose
+ * `_meta.ui.resourceUri` names a `ui://` resource, and that resource — an HTML
+ * page served under {@link MCP_APP_MIME_TYPE} — which the host renders in an
+ * iframe and then pushes the tool's result into. A host without the extension
+ * sees an ordinary tool with an ordinary text result and ignores the metadata,
+ * which is why the tool's answer must stand on its own.
+ *
+ * Deliberately no dependency: the extension's SDK would be a new package on
+ * both the server and the view, and the wire shape it would hide is the three
+ * literals below (see the Specification's Decision 10). Hexis tracks the
+ * specification by hand instead.
+ *
+ * Lives in `mcp-core` because BOTH surfaces serve the same view: the hosted
+ * proxy from the deployment it runs in, and `hexis-mcp` by fetching it from
+ * the deployment it bridges. One definition, so the two cannot drift.
+ */
+
+/** The `_meta` key the extension's metadata rides under, on a tool and on a resource alike. */
+export const MCP_APP_UI_META_KEY = 'ui';
+
+/**
+ * The media type of an MCP App view. A host that supports the extension
+ * recognises an app by this and nothing else; a non-conforming explicit type
+ * is rejected rather than coerced, so it is spelled once, here.
+ */
+export const MCP_APP_MIME_TYPE = 'text/html;profile=mcp-app';
+
+/** The `ui://` scheme every app resource's URI uses. */
+export const MCP_APP_URI_SCHEME = 'ui://';
+
+/** A tool's UI metadata: which view renders its result. */
+export interface McpAppToolUi {
+  /** The `ui://` URI of the view resource. */
+  resourceUri: string;
+}
+
+/** A view resource's UI metadata: what the host's sandbox may do with it. */
+export interface McpAppResourceUi {
+  /**
+   * What the sandbox may load from outside itself. `frameDomains` are the
+   * origins the view may put in an iframe — for Hexis, exactly the
+   * deployment's own public origin, because the view's whole job is to frame
+   * this deployment's `/embed` page.
+   */
+  csp?: {
+    frameDomains?: string[];
+    connectDomains?: string[];
+    resourceDomains?: string[];
+  };
+  /**
+   * The stable sandbox domain the host gives the view. Stable matters: the
+   * host derives the iframe's opaque origin from it, so a value that changed
+   * per render would throw away the sandbox's storage on every call.
+   */
+  domain?: string;
+  /** Whether the host should draw a border around the view. */
+  prefersBorder?: boolean;
+}
+
+/** One MCP App view, as `resources/list` and `resources/read` answer for it. */
+export interface McpAppResource {
+  /** `ui://…` — the URI a tool's `resourceUri` points at. */
+  uri: string;
+  name: string;
+  title?: string;
+  description?: string;
+  /** Always {@link MCP_APP_MIME_TYPE}. */
+  mimeType: string;
+  /** The view's HTML. */
+  text: string;
+  ui: McpAppResourceUi;
+}
+
+/**
+ * Everything a surface needs to serve a deployment's MCP Apps: which tools
+ * carry UI metadata, and the views they name.
+ *
+ * `hexis-mcp` fetches exactly this shape over HTTP from the deployment, so
+ * the local server advertises the same apps as the hosted endpoint without
+ * knowing anything about what they render.
+ */
+export interface McpAppManifest {
+  /** Tool name → its UI metadata. */
+  tools: Record<string, McpAppToolUi>;
+  resources: McpAppResource[];
+}
+
+/** The `_meta` object a tool carrying a view advertises. */
+export function toolUiMeta(ui: McpAppToolUi): Record<string, unknown> {
+  return { [MCP_APP_UI_META_KEY]: { resourceUri: ui.resourceUri } };
+}
+
+/** The `_meta` object a view resource advertises, on both list and read. */
+export function resourceUiMeta(ui: McpAppResourceUi): Record<string, unknown> {
+  return { [MCP_APP_UI_META_KEY]: { ...ui } };
+}
+
+/** A resource's listing entry (no content), as `resources/list` returns it. */
+export function toListedResource(resource: McpAppResource): {
+  uri: string;
+  name: string;
+  title?: string;
+  description?: string;
+  mimeType: string;
+  _meta: Record<string, unknown>;
+} {
+  return {
+    uri: resource.uri,
+    name: resource.name,
+    ...(resource.title !== undefined ? { title: resource.title } : {}),
+    ...(resource.description !== undefined ? { description: resource.description } : {}),
+    mimeType: resource.mimeType,
+    _meta: resourceUiMeta(resource.ui),
+  };
+}
+
+/**
+ * A resource's content, as `resources/read` returns it. The metadata rides
+ * the CONTENTS entry as well as the listing: a host that preloads a view
+ * straight from a tool's `resourceUri` never saw the listing, and the CSP is
+ * what decides whether its sandbox may frame anything at all.
+ */
+export function toReadResourceResult(resource: McpAppResource): {
+  contents: Array<{ uri: string; mimeType: string; text: string; _meta: Record<string, unknown> }>;
+} {
+  return {
+    contents: [
+      {
+        uri: resource.uri,
+        mimeType: resource.mimeType,
+        text: resource.text,
+        _meta: resourceUiMeta(resource.ui),
+      },
+    ],
+  };
+}
+
+/**
+ * Parse a manifest off the wire (the local server's fetch from a deployment),
+ * keeping only what is well-formed. A deployment too old to serve one, or one
+ * whose answer is a proxy's HTML, must leave the local server with NO apps
+ * rather than with a half-built one — the tools it bridges still work.
+ */
+export function parseMcpAppManifest(body: unknown): McpAppManifest {
+  const empty: McpAppManifest = { tools: {}, resources: [] };
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return empty;
+  const raw = body as { tools?: unknown; resources?: unknown };
+  const tools: Record<string, McpAppToolUi> = {};
+  if (raw.tools && typeof raw.tools === 'object' && !Array.isArray(raw.tools)) {
+    for (const [name, value] of Object.entries(raw.tools as Record<string, unknown>)) {
+      const uri = (value as { resourceUri?: unknown })?.resourceUri;
+      if (typeof uri === 'string' && uri.startsWith(MCP_APP_URI_SCHEME)) {
+        tools[name] = { resourceUri: uri };
+      }
+    }
+  }
+  const resources: McpAppResource[] = [];
+  if (Array.isArray(raw.resources)) {
+    for (const entry of raw.resources) {
+      if (!entry || typeof entry !== 'object') continue;
+      const r = entry as Partial<McpAppResource>;
+      // A view with no URI or no HTML is nothing a host can render, and a
+      // media type that is not the app one would be rejected downstream
+      // anyway — drop it here, where the reason is still legible.
+      if (typeof r.uri !== 'string' || !r.uri.startsWith(MCP_APP_URI_SCHEME)) continue;
+      if (typeof r.text !== 'string' || r.text === '') continue;
+      if (r.mimeType !== MCP_APP_MIME_TYPE) continue;
+      resources.push({
+        uri: r.uri,
+        name: typeof r.name === 'string' && r.name ? r.name : r.uri,
+        ...(typeof r.title === 'string' ? { title: r.title } : {}),
+        ...(typeof r.description === 'string' ? { description: r.description } : {}),
+        mimeType: MCP_APP_MIME_TYPE,
+        text: r.text,
+        ui:
+          r.ui && typeof r.ui === 'object' && !Array.isArray(r.ui)
+            ? (r.ui as McpAppResourceUi)
+            : {},
+      });
+    }
+  }
+  // Only tools whose view actually arrived: a `resourceUri` pointing at a
+  // resource this surface cannot serve would have a host preload a 404 and
+  // show the reader an empty frame where the text used to be.
+  const served = new Set(resources.map((r) => r.uri));
+  for (const name of Object.keys(tools)) {
+    if (!served.has(tools[name].resourceUri)) delete tools[name];
+  }
+  return { tools, resources };
+}

package/src/meta-tools.ts

@@ -4,6 +4,7 @@ import { utcpNameToTsInterfaceName, findToolsByNames, sanitizeIdentifier } from
 import { chainExample, type ChainExample, type ChainExampleTool } from './chain-example.js';
 import { toCallToolResult, toolError, describeToolFailure, withTransportDetail, omitImagePayloads } from './results.js';
 import { retiredToolInFailure } from './retired-tools.js';
+import { withCallExample } from './tool-interface.js';
 import {
   CHAIN_TIMEOUT_DEFAULT_MS,
   CHAIN_TIMEOUT_MAX_MS,
@@ -119,7 +120,8 @@ function callToolChainDescription(example: ChainExample, sharedRulesPointer?: st
   // A name the catalog really has, or no name: see `ChainExample.name`.
   const forInstance = name ? ` (e.g. \`${name}\`)` : '';
   const howToWriteOne = [
-    `Execute a short JavaScript program with direct access to every registered UTCP tool as a synchronous function. Call tools as \`${ns}.<tool>({ body: { ...args } })\` with NO \`await\` (results are already resolved), and \`return\` the final value.${worked} Every argument a tool declares REQUIRED must be present — \`tools_info\` gives the exact shapes, and for the knowledge-base tools that includes \`branch\`. The runtime is plain JavaScript (no type annotations / no TypeScript-only syntax), plus \`atob\`, \`btoa\`, \`TextEncoder\` and \`TextDecoder\` for base64 and UTF-8 bytes, as in a browser. There is no \`Buffer\`, no \`fetch\` and no \`require\`.`,
+    `Execute a short JavaScript program with direct access to every registered UTCP tool as a synchronous function, with NO \`await\` (results are already resolved), and \`return\` the final value.${worked} The runtime is plain JavaScript (no type annotations / no TypeScript-only syntax), plus \`atob\`, \`btoa\`, \`TextEncoder\` and \`TextDecoder\` for base64 and UTF-8 bytes, as in a browser. There is no \`Buffer\`, no \`fetch\` and no \`require\`.`,
+    `There is NO single calling shape: call each tool as the \`Call:\` line atop its description shows; every tool in \`${ns}\` has one. Mismatched arguments are refused before anything runs.`,
     `Discover first: \`list_tools\` lists every tool in callable form${forInstance}; \`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.`,
   ];
   if (sharedRulesPointer !== undefined) return `${howToWriteOne.join('\n\n')}${sharedRulesPointer}`;
@@ -158,7 +160,7 @@ export function codeModeMetaTools(
 ): McpTool[] {
   const example = chainExample(namespace, tools);
   const { name } = example;
-  return [
+  return withCallExamples([
     {
       name: 'list_tools',
       description: `List every UTCP tool currently registered, in TypeScript-accessible form${name ? ` (e.g. \`${name}\`)` : ''} for use inside \`call_tool_chain\`.`,
@@ -196,7 +198,20 @@ export function codeModeMetaTools(
         additionalProperties: false,
       } as McpTool['inputSchema'],
     },
-  ];
+  ]);
+}
+
+/**
+ * Each of the three with its call example ahead of its description, from the
+ * same generator every other tool's comes from — so "every description opens
+ * with its call" holds with no exception an agent has to learn.
+ *
+ * These three are called DIRECTLY over MCP rather than from inside a chain, so
+ * the example shows that shape: the tool's name and its required arguments,
+ * with no namespace in front.
+ */
+function withCallExamples(tools: McpTool[]): McpTool[] {
+  return tools.map((t) => ({ ...t, description: withCallExample(t.description, t.name, t.inputSchema) }));
 }
 
 /**
@@ -267,8 +282,18 @@ export async function dispatchMetaTool(
       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);
+        // The call example travels with the interface too: `tools_info` is
+        // where an agent writing a chain reads the shape, and reading it there
+        // without the example is how a flat tool's arguments end up in a
+        // `body`. Added to a COPY — the repository's tool is not ours to edit.
+        if (found) {
+          interfaces.push(
+            client.toolToTypeScriptInterface({
+              ...found.tool,
+              description: withCallExample(found.tool.description, found.utcpName, found.tool.inputs),
+            }),
+          );
+        } else notFound.push(n);
       }
       return toCallToolResult({ interfaces: interfaces.join('\n\n'), not_found: notFound });
     }

package/src/proxied-tool.ts

@@ -1,5 +1,7 @@
 import type { Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
 import type { JsonSchema, Tool as UtcpTool } from '@utcp/sdk';
+import { withCallExample } from './tool-interface.js';
+import { toolUiMeta, type McpAppToolUi } from './mcp-app.js';
 
 /** A tool discovered from a UTCP manual, flattened into what an MCP surface advertises. */
 export interface ProxiedTool {
@@ -10,6 +12,16 @@ export interface ProxiedTool {
   /** 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;
+  /**
+   * The MCP Apps view this tool's result renders in, when it carries one.
+   *
+   * Not part of the UTCP manual a tool is discovered from — UTCP has no place
+   * for it — so a surface attaches it by tool NAME from the deployment's app
+   * manifest (`McpAppManifest.tools`) after flattening. `toListedTool` turns
+   * it into the `_meta` an MCP client reads; a client without the extension
+   * ignores the field, so carrying it costs nothing.
+   */
+  ui?: McpAppToolUi;
 }
 
 /**
@@ -72,8 +84,18 @@ export function toListedTool(tool: ProxiedTool): McpTool | null {
   }
   return {
     name: tool.mcpName,
-    description: tool.description,
+    // Every tool an agent can see opens with the one line that shows how it is
+    // called — generated from this tool's own input schema, so the platform's
+    // tools, a deployment's and a connected server's all get one and none of
+    // them can drift from the shape the tool really takes.
+    // From the schema as it is LISTED (sanitized, local `$ref`s inlined), so
+    // the example and the interface the client is shown agree.
+    description: withCallExample(tool.description, tool.utcpName, inputSchema),
     inputSchema: inputSchema as McpTool['inputSchema'],
+    // The MCP Apps view, when this tool carries one. `_meta` is an open map
+    // every client is required to tolerate, so a client without the
+    // extension reads the tool exactly as it did before.
+    ...(tool.ui ? { _meta: toolUiMeta(tool.ui) } : {}),
   };
 }
 

package/src/results.ts

@@ -119,7 +119,7 @@ export function describeToolFailure(err: unknown): string {
       return inner;
     }
   }
-  if (typeof data === 'string' && data.length > 0) return data;
+  if (typeof data === 'string' && data.length > 0) return nonJsonFailure(err, data) ?? data;
   // Total, like `safeJsonText`: a thrown value whose own `toString` throws
   // (e.g. a null-prototype object) must still come back as a description —
   // this function runs inside catch paths, where a second throw would turn
@@ -131,6 +131,105 @@ export function describeToolFailure(err: unknown): string {
   }
 }
 
+/** The `kind` an answer that was not JSON where JSON was expected carries. */
+export const NOT_JSON_KIND = 'not-json';
+
+/** How much of a non-JSON answer reaches the agent. The rest is a web page, not information. */
+const NON_JSON_MAX = 200;
+
+/** Collapse every run of whitespace, so a page's indentation doesn't fill the budget. */
+function firstLine(text: string): string {
+  const collapsed = text.replace(/\s+/g, ' ').trim();
+  return collapsed.length > NON_JSON_MAX ? `${collapsed.slice(0, NON_JSON_MAX - 1)}…` : collapsed;
+}
+
+function looksLikeJson(text: string): boolean {
+  try {
+    JSON.parse(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A SUCCESSFUL answer that is a web page rather than JSON, cut to its first
+ * {@link NON_JSON_MAX} characters — or `undefined` when the value is not a
+ * page. Used by the call guards, which know whether the tool answers over HTTP
+ * at all; a markdown file that happens to start with a tag is not a page, and
+ * only an http-family tool's bare string body can be one.
+ */
+export function pageInsteadOfJson(value: string): string | undefined {
+  if (!/^\s*<(!doctype|html|\?xml|head|body)\b/i.test(value)) return undefined;
+  return firstLine(value);
+}
+
+/**
+ * The short form of a failure whose body was not JSON: the status, the host
+ * that answered, and the first {@link NON_JSON_MAX} characters.
+ *
+ * A service's edge answers a refused request with its own HTML page, and that
+ * page used to reach the agent whole — thousands of characters of markup in
+ * place of a reason. The status and the first line of it say everything the
+ * agent can act on. A body that IS JSON keeps today's wording: it is the
+ * service's own message, however long, and cutting it would lose the reason.
+ */
+function nonJsonFailure(err: unknown, body: string): string | undefined {
+  if (looksLikeJson(body)) return undefined;
+  const status = readNumber(err, ['response', 'status']) ?? readNumber(err, ['status']);
+  const host = failureHost(err);
+  const where = [status === undefined ? '' : String(status), host === undefined ? '' : `from ${host}`]
+    .filter((p) => p !== '')
+    .join(' ');
+  const line = firstLine(body);
+  return where === '' ? line : `${where}: ${line}`;
+}
+
+function readNumber(source: unknown, path: string[]): number | undefined {
+  let node: unknown = source;
+  for (const key of path) {
+    if (node === null || typeof node !== 'object') return undefined;
+    try {
+      node = (node as Record<string, unknown>)[key];
+    } catch {
+      return undefined;
+    }
+  }
+  return typeof node === 'number' ? node : undefined;
+}
+
+/** The host that answered, from wherever the transport left the request's URL. */
+function failureHost(err: unknown): string | undefined {
+  for (const path of [
+    ['response', 'config', 'url'],
+    ['config', 'url'],
+    ['response', 'url'],
+    ['url'],
+  ]) {
+    let node: unknown = err;
+    for (const key of path) {
+      if (node === null || typeof node !== 'object') {
+        node = undefined;
+        break;
+      }
+      try {
+        node = (node as Record<string, unknown>)[key];
+      } catch {
+        node = undefined;
+        break;
+      }
+    }
+    if (typeof node === 'string' && node.length > 0) {
+      try {
+        return new URL(node).host;
+      } catch {
+        // not an absolute URL — nothing to name, try the next place
+      }
+    }
+  }
+  return undefined;
+}
+
 /**
  * Does `message` already state `status` AS a status code?
  *
@@ -319,7 +418,19 @@ function noteText(value: unknown): string | undefined {
   return undefined;
 }
 
-export function toCallToolResult(value: unknown): CallToolResult {
+export function toCallToolResult(
+  value: unknown,
+  options?: {
+    /**
+     * Also answer a plain-object result as `structuredContent`. Asked for by
+     * a tool that carries an MCP App view: the view reads the result's fields
+     * from `structuredContent` (it has no other place to read them), while
+     * the model keeps reading the text block. Off for every other tool, so no
+     * client is handed each result twice.
+     */
+    structured?: boolean;
+  },
+): CallToolResult {
   // An image sentinel (see McpImageResult): the tool's result IS a picture.
   // Emit a native image content block so a multimodal client renders it, plus
   // the note as a text block so the transcript stays self-describing.
@@ -374,7 +485,22 @@ export function toCallToolResult(value: unknown): CallToolResult {
     return value as CallToolResult;
   }
   const text = typeof value === 'string' ? value : safeJsonText(value ?? null);
-  return { content: [{ type: 'text', text: text || '(tool produced no output)' }] };
+  const result: CallToolResult = { content: [{ type: 'text', text: text || '(tool produced no output)' }] };
+  if (options?.structured && value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    // The JSON-safe reading of the value, the same one the text block carries:
+    // the object itself may hold a BigInt, a cycle or a `toJSON` that throws,
+    // and the response serializer would fail on it where the text did not. A
+    // value with no JSON object reading carries no structured content.
+    try {
+      const structured: unknown = JSON.parse(text);
+      if (structured !== null && typeof structured === 'object' && !Array.isArray(structured)) {
+        result.structuredContent = structured as Record<string, unknown>;
+      }
+    } catch {
+      /* text was not JSON: nothing structured to attach */
+    }
+  }
+  return result;
 }
 
 /**