@aexhq/tools-mcp 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @aexhq/tools-mcp
 
-Connect selected MCP Tools to Brain 0.22 through application `hostEnv`. The application owns the MCP connection, authentication and lifecycle. The bridge never accepts arbitrary model-selected Tool names.
+Connect selected MCP Tools to Brain through application `hostEnv`. The application owns the MCP connection, authentication and lifecycle. The bridge never accepts arbitrary model-selected Tool names.
 
 ```js
 import { hostEnv } from "@aexhq/brain";
@@ -23,11 +23,27 @@ The client SDK owns transport and protocol negotiation. `connectMcp` disables au
 
 ## Results and failures
 
-Every returned MCP result is first committed as an `mcp_result` Event with Tool provenance. Successful text, structured content and resource links are presented to the model. PNG, JPEG, GIF and WebP images use the official `aex_tool_output` version 1 convention; Pi/Codex 5.1.0 map them into Brain Tool-result media. Audio, binary embedded resources, asynchronous tasks and interactive continuations are explicitly unsupported.
+MCP images and embedded image/PDF resources require a caller-supplied
+`publishMedia({ bytes, mediaType, index }, context)` callback on `mcpTools`. Return an HTTPS URL
+reachable by the model provider. `context` supplies the session ID, invocation sequence, deadline
+and cancellation signal. The application owns upload authorization and expiry, and can bind this
+callback to Aex's attachment SDK or another store.
 
-An optional `project(output, toolName)` selects a smaller model-visible JSON representation. Its input includes `content`, optional `structuredContent`, and the committed `evidenceSequence`; raw evidence remains in the Event. Image media is carried separately. Brain's existing emitted-Event and model-input limits still apply; exceeding them is an explicit failure.
+Known binary media is published before the normalized `mcp_result` Event is committed, including
+MCP error results. The retained evidence contains URL media and the remaining MCP content;
+image/base64 and resource blobs are removed. A missing or failed publisher produces
+`mcp_media_failed` evidence and a failed Tool result. The completed MCP tool is never repeated to
+repair publication. Audio, other binary resource types, asynchronous tasks and interactive
+continuations fail explicitly.
 
-MCP `isError` becomes a failed Brain Tool result with code `mcp_tool_error`, `retryable: false` and the complete MCP result in `details`. JSON-RPC failures use `mcp_protocol_error` and retain the original numeric code and data in `details`. Known MCP SDK failures use `mcp_sdk_error`; unsupported continuations use `mcp_unsupported_result`. Protocol/transport errors also produce `mcp_failure` evidence while the invocation is active.
+Successful text, structured content and resource links are presented to the model. Published PNG,
+JPEG, GIF, WebP and PDF inputs use `aex_tool_output` version 1. Use the matching URL-media Pi/Codex
+release to map them into Brain Tool-result media. Unsupported binary fields inside arbitrary Tool
+JSON are not recursively transformed.
+
+An optional `project(output, toolName)` selects a smaller model-visible JSON representation. Its input includes `content`, optional `structuredContent`, and the committed `evidenceSequence`; normalized evidence remains in the Event. Image and PDF media is carried separately. Brain's existing emitted-Event and model-input limits still apply; exceeding them is an explicit failure.
+
+MCP `isError` becomes a failed Brain Tool result with code `mcp_tool_error`, `retryable: false` and the normalized MCP result in `details`. JSON-RPC failures use `mcp_protocol_error` and retain the original numeric code and data in `details`. Known MCP SDK failures use `mcp_sdk_error`; unsupported continuations use `mcp_unsupported_result`. Protocol/transport errors also produce `mcp_failure` evidence while the invocation is active.
 
 Invocation deadlines and MCP request timeouts produce `timeout`; explicit SDK cancellation produces `cancelled`. The bridge returns `unknown` only when an invocation may have been dispatched and no reliable terminal result is available, such as connection loss after a mutation. The terminal result has `is_error: true` and code `unknown`; its evidence Event retains the structured transport cause. Timeout and cancellation describe why waiting ended and do not promise rollback. The bridge never automatically repeats a call.
 

package/dist/index.mjs

@@ -1,3 +1,19 @@
+// ../../shared/media.mjs
+function validateMedia(item) {
+  if (!item || !(item.type === "image" && Object.keys(item).every((key) => ["type", "url"].includes(key)) || item.type === "file" && item.media_type === "application/pdf" && Object.keys(item).every((key) => ["type", "url", "media_type"].includes(key))) || typeof item.url !== "string") throw new TypeError("media must contain Brain image or PDF URL blocks");
+  const url = new URL(item.url);
+  if (url.protocol !== "https:" || url.username || url.password) throw new TypeError("media requires HTTPS without credentials");
+  return item;
+}
+async function publish(publishMedia, bytes, mediaType, index, context) {
+  if (typeof publishMedia !== "function") throw new TypeError("publishMedia is required for model media");
+  if (!["image/png", "image/jpeg", "image/gif", "image/webp", "application/pdf"].includes(mediaType)) throw new TypeError(`unsupported media type: ${mediaType}`);
+  context.signal.throwIfAborted();
+  const url = await publishMedia({ bytes, mediaType, index }, context);
+  context.signal.throwIfAborted();
+  return validateMedia(mediaType === "application/pdf" ? { type: "file", media_type: mediaType, url } : { type: "image", url });
+}
+
 // src/index.mjs
 import { Client, ProtocolError, SdkError, SdkErrorCode } from "@modelcontextprotocol/client";
 import { AjvJsonSchemaValidator } from "@modelcontextprotocol/client/validators/ajv";
@@ -10,7 +26,7 @@ function toolOutput(content, media = []) {
 }
 
 // src/index.mjs
-async function connectMcp(transport, { name = "aex-mcp", version = "0.1.0", ...options } = {}) {
+async function connectMcp(transport, { name = "aex-mcp", version = "0.3.0", ...options } = {}) {
   const client = new Client({ name, version }, { ...options, inputRequired: { autoFulfill: false } });
   try {
     await client.connect(transport);
@@ -20,7 +36,7 @@ async function connectMcp(transport, { name = "aex-mcp", version = "0.1.0", ...o
   }
   return client;
 }
-async function mcpTools({ client, names, env, prefix = "", project }) {
+async function mcpTools({ client, names, env, prefix = "", project, publishMedia }) {
   if (inspectEnvironment(env).driver.driver !== "host") throw new TypeError("MCP Tools must be placed in hostEnv");
   z.array(z.string().min(1)).min(1).parse(names);
   if (new Set(names).size !== names.length) throw new TypeError("select each MCP Tool once");
@@ -66,23 +82,32 @@ async function mcpTools({ client, names, env, prefix = "", project }) {
           });
           return outcome;
         }
-        const evidenceSequence = await context.emit("mcp_result", { tool: definition.name, result: response });
+        const media = [];
+        const content = [];
+        try {
+          for (const block of response.content ?? []) {
+            const encoded = block.type === "image" ? block.data : block.type === "resource" ? block.resource?.blob : void 0;
+            if (encoded !== void 0) {
+              const bytes = Buffer.from(encoded, "base64");
+              if (bytes.toString("base64") !== encoded) throw new TypeError("invalid MCP media base64");
+              media.push(await publish(publishMedia, bytes, block.mimeType ?? block.resource?.mimeType, media.length, context));
+            } else if (block.type === "text" || block.type === "resource_link" || block.type === "resource" && typeof block.resource?.text === "string") {
+              content.push(block);
+            } else throw new TypeError(`unsupported MCP content type: ${block.type}`);
+          }
+        } catch (error) {
+          if (context.signal.aborted) throw error;
+          await context.emit("mcp_media_failed", { tool: definition.name, published: media });
+          return failure("mcp_media_failed", String(error.message), { published: media });
+        }
+        const retained = { ...response, content, ...media.length ? { media } : {} };
+        const evidenceSequence = await context.emit("mcp_result", { tool: definition.name, result: retained });
         if (response.resultType && response.resultType !== "complete") {
-          return failure("mcp_unsupported_result", `MCP ${definition.name} requires unsupported continuation (${response.resultType}); evidence ${evidenceSequence}`, response);
+          return failure("mcp_unsupported_result", `MCP ${definition.name} requires unsupported continuation (${response.resultType}); evidence ${evidenceSequence}`, retained);
         }
         if (response.isError) {
-          const message = response.content?.filter((block) => block.type === "text").map((block) => block.text).join("\n");
-          return failure("mcp_tool_error", `MCP ${definition.name}: ${message || "Tool failed"}; evidence ${evidenceSequence}`, response);
-        }
-        const media = [];
-        const content = [];
-        for (const block of response.content ?? []) {
-          if (block.type === "image") {
-            if (!["image/png", "image/jpeg", "image/gif", "image/webp"].includes(block.mimeType)) throw new Error(`unsupported MCP image type: ${block.mimeType}`);
-            media.push({ type: "image", url: `data:${block.mimeType};base64,${block.data}` });
-          } else if (block.type === "text" || block.type === "resource_link" || block.type === "resource" && typeof block.resource?.text === "string") {
-            content.push(block);
-          } else throw new Error(`unsupported MCP content type: ${block.type}; evidence ${evidenceSequence}`);
+          const message = content.filter((block) => block.type === "text").map((block) => block.text).join("\n");
+          return failure("mcp_tool_error", `MCP ${definition.name}: ${message || "Tool failed"}; evidence ${evidenceSequence}`, retained);
         }
         const presented = { content, ...response.structuredContent === void 0 ? {} : { structuredContent: response.structuredContent }, evidenceSequence };
         return toolOutput(project ? await project(presented, definition.name) : presented, media);

package/index.d.ts

@@ -1,6 +1,7 @@
 import type { Client, ClientOptions, Transport } from "@modelcontextprotocol/client";
-import type { Environment, PlacedTool } from "@aexhq/brain";
+import type { Environment, HostToolCall, PlacedTool } from "@aexhq/brain";
 export declare function connectMcp(transport: Transport, options?: ClientOptions & { name?: string; version?: string }): Promise<Client>;
 export interface McpPresentation { content: unknown[]; structuredContent?: unknown; evidenceSequence: number }
 export declare function mcpTools(options: { client: Client; names: string[]; env: Environment; prefix?: string;
+  publishMedia?: (media: { bytes: Uint8Array; mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp" | "application/pdf"; index: number }, context: HostToolCall) => string | Promise<string>;
   project?: (output: McpPresentation, toolName: string) => unknown | Promise<unknown> }): Promise<PlacedTool[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/tools-mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Selected MCP Tools in a Brain application host",
   "license": "MIT",
   "type": "module",
@@ -10,6 +10,6 @@
   "exports": { ".": { "types": "./index.d.ts", "import": "./dist/index.mjs" }, "./package.json": "./package.json" },
   "files": ["dist", "index.d.ts", "README.md"],
   "scripts": { "build": "node ../../tools/build-environment.mjs", "test": "npm run build && node --test test/*.test.mjs", "test:journeys": "node --test test/journeys.mjs", "prepack": "npm run build" },
-  "dependencies": { "@aexhq/brain": "0.22.0", "@modelcontextprotocol/client": "2.0.0", "zod": "4.4.3" },
+  "dependencies": { "@aexhq/brain": "0.24.0", "@modelcontextprotocol/client": "2.0.0", "zod": "4.4.3" },
   "devDependencies": { "@modelcontextprotocol/server": "2.0.0" }
 }