@aexhq/tools-mcp 0.0.0 → 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# @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.
+
+```js
+import { hostEnv } from "@aexhq/brain";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { connectMcp, mcpTools } from "@aexhq/tools-mcp";
+
+const client = await connectMcp(new StdioClientTransport({
+  command: "node", args: ["./my-mcp-server.mjs"],
+}), { versionNegotiation: { mode: { pin: "2026-07-28" } } });
+
+const tools = await mcpTools({
+  client, env: hostEnv({ name: "app" }), names: ["search", "lookup"], prefix: "service_",
+});
+// Supply tools at session creation. Keep the client alive while these bindings are used.
+// After ending their sessions:
+// await client.close();
+```
+
+The client SDK owns transport and protocol negotiation. `connectMcp` disables automatic interactive fulfilment; specify the protocol revision your server supports. A connected client can also be supplied directly. The bridge uses a fixed discovered Tool definition on every call, so an SDK cache refresh cannot change the session's schemas or trigger the header-mismatch resend path. Discovery uses the SDK's bounded pagination. Later list changes do not add or replace placed Tools; authorize a new session for changed definitions.
+
+## 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.
+
+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.
+
+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.
+
+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.
+
+The original input JSON Schema is carried into Brain unchanged through Zod metadata. Host input parsing delegates to the MCP SDK's AJV validator without stripping properties, coercing values or inserting defaults. Conditional and dependent schemas, unevaluated properties, `$defs` and local recursive references are supported when accepted by both MCP and Brain validators. Invalid input fails as `invalid_input` before any MCP call. Unsupported dialects or unresolved references fail at construction; the bridge does not fetch external schemas. The MCP SDK validates structured output against the pinned original definition.
+
+On application restart, reconnect the MCP client and recreate the same selected Tool bindings when reattaching the Brain host. This accepts future commands and never replays a disconnected invocation. Transport credentials remain application-owned; do not put them in Tool arguments or projection metadata.
+
+## Verification
+
+`npm test --workspace @aexhq/tools-mcp` uses the real MCP v2 SDK and a separate stdio server process, including paginated discovery, cancellation, server termination after a mutation, structured results/errors, catalogue changes and images. Public-SDK journeys verify terminal outcomes, journal evidence, model presentation and original-schema validation through Brain, including that invalid calls produce no remote effects.

package/dist/index.mjs

@@ -0,0 +1,102 @@
+// src/index.mjs
+import { Client, ProtocolError, SdkError, SdkErrorCode } from "@modelcontextprotocol/client";
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/client/validators/ajv";
+import { inspectEnvironment, tool } from "@aexhq/brain";
+import { z } from "zod";
+
+// ../../shared/tool-output.mjs
+function toolOutput(content, media = []) {
+  return { type: "aex_tool_output", version: 1, content, media };
+}
+
+// src/index.mjs
+async function connectMcp(transport, { name = "aex-mcp", version = "0.1.0", ...options } = {}) {
+  const client = new Client({ name, version }, { ...options, inputRequired: { autoFulfill: false } });
+  try {
+    await client.connect(transport);
+  } catch (error) {
+    await client.close();
+    throw error;
+  }
+  return client;
+}
+async function mcpTools({ client, names, env, prefix = "", project }) {
+  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");
+  const discovered = await client.listTools(void 0, { cacheMode: "refresh" });
+  const selected = names.map((name) => {
+    const matches = discovered.tools.filter((definition2) => definition2.name === name);
+    if (matches.length !== 1) throw new Error(`expected one MCP definition for ${name}, received ${matches.length}`);
+    const definition = structuredClone(matches[0]);
+    if (definition.execution?.taskSupport === "required") throw new Error(`${name} requires unsupported MCP task execution`);
+    return definition;
+  });
+  return selected.map((definition) => {
+    const validate = new AjvJsonSchemaValidator().getValidator(definition.inputSchema);
+    const input = z.unknown().superRefine((value, context) => {
+      const result = validate(value);
+      if (!result.valid) context.addIssue({ code: "custom", message: result.errorMessage });
+    }).meta(definition.inputSchema);
+    return tool({
+      name: `${prefix}${definition.name}`,
+      description: definition.description || definition.name,
+      input,
+      run: async (arguments_, context) => {
+        context.signal.throwIfAborted();
+        let response;
+        try {
+          response = await client.callTool({ name: definition.name, arguments: arguments_ }, {
+            signal: context.signal,
+            timeout: Math.max(1, context.deadline.getTime() - Date.now()),
+            toolDefinition: definition,
+            allowInputRequired: true
+          });
+        } catch (error) {
+          if (context.signal.aborted) throw error;
+          const message = String(error.message ?? error);
+          const details = { code: error.code ?? null, data: error.data ?? null };
+          const outcome = error instanceof SdkError && error.code === SdkErrorCode.RequestTimeout ? { status: "timeout" } : error instanceof ProtocolError ? failure("mcp_protocol_error", message, details) : error instanceof SdkError && ![SdkErrorCode.ConnectionClosed, SdkErrorCode.SendFailed].includes(error.code) ? failure("mcp_sdk_error", message, details) : { status: "unknown", message: `MCP ${definition.name}: outcome unknown; ${message}` };
+          await context.emit("mcp_failure", {
+            tool: definition.name,
+            outcome: outcome.status,
+            code: details.code,
+            message,
+            details: details.data
+          });
+          return outcome;
+        }
+        const evidenceSequence = await context.emit("mcp_result", { tool: definition.name, result: response });
+        if (response.resultType && response.resultType !== "complete") {
+          return failure("mcp_unsupported_result", `MCP ${definition.name} requires unsupported continuation (${response.resultType}); evidence ${evidenceSequence}`, response);
+        }
+        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 presented = { content, ...response.structuredContent === void 0 ? {} : { structuredContent: response.structuredContent }, evidenceSequence };
+        return toolOutput(project ? await project(presented, definition.name) : presented, media);
+      }
+    })({ env });
+  });
+}
+var failure = (code, message, details) => ({ status: "error", error: {
+  code,
+  message: message.slice(0, 4096),
+  retryable: false,
+  details
+} });
+export {
+  connectMcp,
+  mcpTools
+};

package/index.d.ts

@@ -0,0 +1,6 @@
+import type { Client, ClientOptions, Transport } from "@modelcontextprotocol/client";
+import type { Environment, 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;
+  project?: (output: McpPresentation, toolName: string) => unknown | Promise<unknown> }): Promise<PlacedTool[]>;

package/package.json

@@ -1,19 +1,15 @@
 {
   "name": "@aexhq/tools-mcp",
-  "version": "0.0.0",
-  "description": "Reserved package name; no stable release is available.",
-  "license": "Apache-2.0",
+  "version": "0.1.0",
+  "description": "Selected MCP Tools in a Brain application host",
+  "license": "MIT",
   "type": "module",
-  "exports": "./index.js",
-  "files": [
-    "index.js"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/aexhq/extensions.git"
-  },
-  "aexHoldPlaceholder": {
-    "stagedVersion": "0.1.0",
-    "source": "4b36218cbe13166f8fcb5db3af8a34f13c99233a"
-  }
+  "engines": { "node": ">=22.0.0" },
+  "repository": { "type": "git", "url": "git+https://github.com/aexhq/extensions.git", "directory": "packages/tools-mcp" },
+  "publishConfig": { "access": "public", "provenance": true, "tag": "next" },
+  "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" },
+  "devDependencies": { "@modelcontextprotocol/server": "2.0.0" }
 }

package/index.js

@@ -1 +0,0 @@
-throw new Error("@aexhq/tools-mcp has no stable release; install @aexhq/tools-mcp@next or an exact version");