@fgv/ts-extras-mcp 5.1.0-34

package/lib/packlets/mcp/adapter.js

@@ -0,0 +1,125 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adaptMcpTools = adaptMcpTools;
+/**
+ * The headline adapter — discovers an MCP server's tools and adapts each into an
+ * `AiAssist.IAiClientTool`, gracefully degrading (Constraint 1) on any tool whose `inputSchema`
+ * is outside the JSON Schema subset that `JsonSchema.fromJson` supports.
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const operations_1 = require("./operations");
+/**
+ * Builds the `execute` callback for an adapted MCP tool. Args arrive already validated against
+ * the tool's `parametersSchema` by `executeClientToolTurn`; here we narrow to a `JsonObject`
+ * (MCP arguments are always an object) and forward to {@link callMcpTool}, returning the
+ * projected text content. A tool error surfaces as a `Failure` (never swallowed).
+ */
+function _makeExecute(session, name) {
+    return async (args) => {
+        const objResult = ts_json_base_1.Converters.jsonObject
+            .convert(args)
+            .withErrorFormat((msg) => `tool '${name}': arguments must be a JSON object: ${msg}`);
+        if (objResult.isFailure()) {
+            return objResult;
+        }
+        return (await (0, operations_1.callMcpTool)(session, name, objResult.value)).onSuccess((called) => (0, ts_utils_1.succeed)(called.content));
+    };
+}
+/**
+ * Adapts a single discovered tool. Returns a `skipped` outcome (never a failure) when the
+ * tool's `inputSchema` is not a JSON object or is outside the `JsonSchema.fromJson` subset.
+ */
+function _adaptOne(session, descriptor) {
+    const { name, description, inputSchema } = descriptor;
+    const skip = (reason, schema) => ({
+        kind: 'skipped',
+        skipped: { name, reason, schema }
+    });
+    const asObject = ts_json_base_1.Converters.jsonObject.convert(inputSchema);
+    if (asObject.isFailure()) {
+        return skip(`inputSchema is not a JSON object (${asObject.message})`, inputSchema);
+    }
+    const schemaResult = ts_json_base_1.JsonSchema.fromJson(asObject.value);
+    if (schemaResult.isFailure()) {
+        return skip(schemaResult.message, inputSchema);
+    }
+    const config = {
+        type: 'client_tool',
+        name,
+        description: description !== null && description !== void 0 ? description : name,
+        parametersSchema: schemaResult.value
+    };
+    return {
+        kind: 'tool',
+        tool: { config, execute: _makeExecute(session, name) }
+    };
+}
+/**
+ * Discovers an MCP server's tools and adapts each into an `AiAssist.IAiClientTool` that drops
+ * directly into `AiAssist.executeClientToolTurn`.
+ *
+ * @remarks
+ * **Constraint 1 — graceful degradation with NOISY warnings.** A tool whose `inputSchema` is
+ * outside the JSON Schema subset supported by `JsonSchema.fromJson` is NOT adapted (the model
+ * must never be offered a tool whose args we can't validate). Instead it is:
+ * 1. excluded from {@link IAdaptMcpToolsResult.tools};
+ * 2. surfaced structurally on {@link IAdaptMcpToolsResult.skipped} with the tool name, the
+ *    JSON-pointer reason, and the raw failing schema; and
+ * 3. logged as a NOISY `warning` (name + reason + raw schema) when an `options.logger` is
+ *    supplied — so pointing this at a new server immediately reveals every subset feature to
+ *    extend, with the schema in hand.
+ *
+ * The whole catalog never fails on a single bad schema; the only failure mode is an upstream
+ * `listMcpTools` error.
+ *
+ * @param session - A connected session from `connectMcpSession`.
+ * @param options - Optional logger for the NOISY skip warnings.
+ * @returns `Success` with `{ tools, skipped }`, or `Failure` only if tool discovery fails.
+ * @public
+ */
+async function adaptMcpTools(session, options) {
+    return (await (0, operations_1.listMcpTools)(session))
+        .onSuccess((descriptors) => {
+        var _a;
+        const tools = [];
+        const skipped = [];
+        for (const descriptor of descriptors) {
+            const outcome = _adaptOne(session, descriptor);
+            if (outcome.kind === 'tool') {
+                tools.push(outcome.tool);
+            }
+            else {
+                skipped.push(outcome.skipped);
+                (_a = options === null || options === void 0 ? void 0 : options.logger) === null || _a === void 0 ? void 0 : _a.warn(`mcp: skipping tool '${outcome.skipped.name}': inputSchema is outside the supported ` +
+                    `JSON Schema subset: ${outcome.skipped.reason}. ` +
+                    `Raw schema: ${JSON.stringify(outcome.skipped.schema)}`);
+            }
+        }
+        return (0, ts_utils_1.succeed)({ tools, skipped });
+    })
+        .withErrorFormat((msg) => `adaptMcpTools: ${msg}`);
+}
+//# sourceMappingURL=adapter.js.map

package/lib/packlets/mcp/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/packlets/mcp/adapter.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * The headline adapter — discovers an MCP server's tools and adapts each into an\n * `AiAssist.IAiClientTool`, gracefully degrading (Constraint 1) on any tool whose `inputSchema`\n * is outside the JSON Schema subset that `JsonSchema.fromJson` supports.\n * @packageDocumentation\n */\n\nimport { type Result, succeed } from '@fgv/ts-utils';\nimport { AiAssist } from '@fgv/ts-extras';\nimport { Converters, JsonSchema, type JsonValue } from '@fgv/ts-json-base';\n\nimport {\n  type IAdaptMcpToolsOptions,\n  type IAdaptMcpToolsResult,\n  type IMcpSession,\n  type IMcpSkippedTool,\n  type IMcpToolDescriptor\n} from './model';\nimport { callMcpTool, listMcpTools } from './operations';\n\n/**\n * Per-tool adaptation outcome: either an adapted client tool, or a structurally-surfaced skip.\n * `adaptMcpTools` never short-circuits on a skip — degradation is structural, not a failure.\n */\ntype IAdaptOutcome =\n  | { readonly kind: 'tool'; readonly tool: AiAssist.IAiClientTool }\n  | { readonly kind: 'skipped'; readonly skipped: IMcpSkippedTool };\n\n/**\n * Builds the `execute` callback for an adapted MCP tool. Args arrive already validated against\n * the tool's `parametersSchema` by `executeClientToolTurn`; here we narrow to a `JsonObject`\n * (MCP arguments are always an object) and forward to {@link callMcpTool}, returning the\n * projected text content. A tool error surfaces as a `Failure` (never swallowed).\n */\nfunction _makeExecute(session: IMcpSession, name: string): (args: unknown) => Promise<Result<unknown>> {\n  return async (args: unknown): Promise<Result<unknown>> => {\n    const objResult = Converters.jsonObject\n      .convert(args)\n      .withErrorFormat((msg) => `tool '${name}': arguments must be a JSON object: ${msg}`);\n    if (objResult.isFailure()) {\n      return objResult;\n    }\n    return (await callMcpTool(session, name, objResult.value)).onSuccess((called) => succeed(called.content));\n  };\n}\n\n/**\n * Adapts a single discovered tool. Returns a `skipped` outcome (never a failure) when the\n * tool's `inputSchema` is not a JSON object or is outside the `JsonSchema.fromJson` subset.\n */\nfunction _adaptOne(session: IMcpSession, descriptor: IMcpToolDescriptor): IAdaptOutcome {\n  const { name, description, inputSchema } = descriptor;\n\n  const skip = (reason: string, schema: JsonValue): IAdaptOutcome => ({\n    kind: 'skipped',\n    skipped: { name, reason, schema }\n  });\n\n  const asObject = Converters.jsonObject.convert(inputSchema);\n  if (asObject.isFailure()) {\n    return skip(`inputSchema is not a JSON object (${asObject.message})`, inputSchema);\n  }\n\n  const schemaResult = JsonSchema.fromJson(asObject.value);\n  if (schemaResult.isFailure()) {\n    return skip(schemaResult.message, inputSchema);\n  }\n\n  const config: AiAssist.IAiClientToolConfig = {\n    type: 'client_tool',\n    name,\n    description: description ?? name,\n    parametersSchema: schemaResult.value\n  };\n  return {\n    kind: 'tool',\n    tool: { config, execute: _makeExecute(session, name) }\n  };\n}\n\n/**\n * Discovers an MCP server's tools and adapts each into an `AiAssist.IAiClientTool` that drops\n * directly into `AiAssist.executeClientToolTurn`.\n *\n * @remarks\n * **Constraint 1 — graceful degradation with NOISY warnings.** A tool whose `inputSchema` is\n * outside the JSON Schema subset supported by `JsonSchema.fromJson` is NOT adapted (the model\n * must never be offered a tool whose args we can't validate). Instead it is:\n * 1. excluded from {@link IAdaptMcpToolsResult.tools};\n * 2. surfaced structurally on {@link IAdaptMcpToolsResult.skipped} with the tool name, the\n *    JSON-pointer reason, and the raw failing schema; and\n * 3. logged as a NOISY `warning` (name + reason + raw schema) when an `options.logger` is\n *    supplied — so pointing this at a new server immediately reveals every subset feature to\n *    extend, with the schema in hand.\n *\n * The whole catalog never fails on a single bad schema; the only failure mode is an upstream\n * `listMcpTools` error.\n *\n * @param session - A connected session from `connectMcpSession`.\n * @param options - Optional logger for the NOISY skip warnings.\n * @returns `Success` with `{ tools, skipped }`, or `Failure` only if tool discovery fails.\n * @public\n */\nexport async function adaptMcpTools(\n  session: IMcpSession,\n  options?: IAdaptMcpToolsOptions\n): Promise<Result<IAdaptMcpToolsResult>> {\n  return (await listMcpTools(session))\n    .onSuccess((descriptors) => {\n      const tools: AiAssist.IAiClientTool[] = [];\n      const skipped: IMcpSkippedTool[] = [];\n\n      for (const descriptor of descriptors) {\n        const outcome = _adaptOne(session, descriptor);\n        if (outcome.kind === 'tool') {\n          tools.push(outcome.tool);\n        } else {\n          skipped.push(outcome.skipped);\n          options?.logger?.warn(\n            `mcp: skipping tool '${outcome.skipped.name}': inputSchema is outside the supported ` +\n              `JSON Schema subset: ${outcome.skipped.reason}. ` +\n              `Raw schema: ${JSON.stringify(outcome.skipped.schema)}`\n          );\n        }\n      }\n\n      return succeed<IAdaptMcpToolsResult>({ tools, skipped });\n    })\n    .withErrorFormat((msg) => `adaptMcpTools: ${msg}`);\n}\n"]}

package/lib/packlets/mcp/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public surface of the MCP packlet.
+ * @packageDocumentation
+ */
+export * from './model';
+export { createHttpTransport, createStdioTransport } from './transports';
+export { closeMcpSession, connectMcpSession } from './session';
+export { callMcpTool, listMcpTools } from './operations';
+export { adaptMcpTools } from './adapter';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/mcp/index.ts"],"names":[],"mappings":"AAsBA;;;GAGG;AAIH,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}

package/lib/packlets/mcp/index.js

@@ -0,0 +1,57 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adaptMcpTools = exports.listMcpTools = exports.callMcpTool = exports.connectMcpSession = exports.closeMcpSession = exports.createStdioTransport = exports.createHttpTransport = void 0;
+/**
+ * Public surface of the MCP packlet.
+ * @packageDocumentation
+ */
+// `export *` (rather than named type-only re-exports) emits a runtime re-export of the
+// types-only module so it participates in coverage as a loaded (zero-statement) module.
+__exportStar(require("./model"), exports);
+var transports_1 = require("./transports");
+Object.defineProperty(exports, "createHttpTransport", { enumerable: true, get: function () { return transports_1.createHttpTransport; } });
+Object.defineProperty(exports, "createStdioTransport", { enumerable: true, get: function () { return transports_1.createStdioTransport; } });
+var session_1 = require("./session");
+Object.defineProperty(exports, "closeMcpSession", { enumerable: true, get: function () { return session_1.closeMcpSession; } });
+Object.defineProperty(exports, "connectMcpSession", { enumerable: true, get: function () { return session_1.connectMcpSession; } });
+var operations_1 = require("./operations");
+Object.defineProperty(exports, "callMcpTool", { enumerable: true, get: function () { return operations_1.callMcpTool; } });
+Object.defineProperty(exports, "listMcpTools", { enumerable: true, get: function () { return operations_1.listMcpTools; } });
+var adapter_1 = require("./adapter");
+Object.defineProperty(exports, "adaptMcpTools", { enumerable: true, get: function () { return adapter_1.adaptMcpTools; } });
+//# sourceMappingURL=index.js.map

package/lib/packlets/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/mcp/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;AAEH;;;GAGG;AAEH,uFAAuF;AACvF,wFAAwF;AACxF,0CAAwB;AACxB,2CAAyE;AAAhE,iHAAA,mBAAmB,OAAA;AAAE,kHAAA,oBAAoB,OAAA;AAClD,qCAA+D;AAAtD,0GAAA,eAAe,OAAA;AAAE,4GAAA,iBAAiB,OAAA;AAC3C,2CAAyD;AAAhD,yGAAA,WAAW,OAAA;AAAE,0GAAA,YAAY,OAAA;AAClC,qCAA0C;AAAjC,wGAAA,aAAa,OAAA","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Public surface of the MCP packlet.\n * @packageDocumentation\n */\n\n// `export *` (rather than named type-only re-exports) emits a runtime re-export of the\n// types-only module so it participates in coverage as a loaded (zero-statement) module.\nexport * from './model';\nexport { createHttpTransport, createStdioTransport } from './transports';\nexport { closeMcpSession, connectMcpSession } from './session';\nexport { callMcpTool, listMcpTools } from './operations';\nexport { adaptMcpTools } from './adapter';\n"]}

package/lib/packlets/mcp/model.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Public types for the MCP → ai-assist client-tools boundary.
+ * @packageDocumentation
+ */
+import { type Logging } from '@fgv/ts-utils';
+import { type AiAssist } from '@fgv/ts-extras';
+import { type JsonValue } from '@fgv/ts-json-base';
+/**
+ * Parameters for {@link createStdioTransport}. The transport spawns `command` as a
+ * subprocess and speaks MCP over its stdin/stdout.
+ *
+ * @remarks
+ * **Security:** stdio transport executes a consumer-supplied command. Treat `command`/`args`
+ * as a trust boundary — never source them from untrusted input. See the package README.
+ *
+ * @public
+ */
+export interface IMcpStdioTransportParams {
+    /** Executable to spawn (e.g. `'npx'`, `'node'`, an absolute path). */
+    readonly command: string;
+    /** Arguments passed to the command. */
+    readonly args?: ReadonlyArray<string>;
+    /** Environment variables for the spawned process. When omitted, the SDK's safe default set is used. */
+    readonly env?: Record<string, string>;
+    /** Working directory for the spawned process. */
+    readonly cwd?: string;
+}
+/**
+ * Parameters for {@link createHttpTransport}. The transport connects to a Streamable-HTTP MCP
+ * endpoint.
+ * @public
+ */
+export interface IMcpHttpTransportParams {
+    /** Absolute `http`/`https` URL of the MCP server endpoint. */
+    readonly url: string;
+    /** Optional static headers (e.g. an `Authorization` bearer token). OAuth/managed auth is out of scope at v0.1. */
+    readonly headers?: Record<string, string>;
+}
+/**
+ * Opaque handle to an MCP transport produced by {@link createStdioTransport} or
+ * {@link createHttpTransport}. Hand it to {@link connectMcpSession}; do not construct directly.
+ * @public
+ */
+export interface IMcpTransport {
+    /** Which transport kind this handle wraps. */
+    readonly transportKind: 'stdio' | 'http';
+}
+/**
+ * Parameters for {@link connectMcpSession}.
+ * @public
+ */
+export interface IConnectMcpSessionParams {
+    /** A transport produced by {@link createStdioTransport} / {@link createHttpTransport}. */
+    readonly transport: IMcpTransport;
+    /** Client name advertised to the server during the initialize handshake. Default `'@fgv/ts-extras-mcp'`. */
+    readonly clientName?: string;
+    /** Client version advertised to the server. Default the package version. */
+    readonly clientVersion?: string;
+    /** Optional logger for connection diagnostics. */
+    readonly logger?: Logging.ILogger;
+}
+/**
+ * Server identity reported during the MCP initialize handshake.
+ * @public
+ */
+export interface IMcpServerInfo {
+    /** Server-advertised name. */
+    readonly name: string;
+    /** Server-advertised version. */
+    readonly version: string;
+}
+/**
+ * Opaque handle to a connected MCP session. Pass it to {@link listMcpTools},
+ * {@link callMcpTool}, {@link adaptMcpTools}, and {@link closeMcpSession}.
+ * @public
+ */
+export interface IMcpSession {
+    /** Client name advertised during the handshake. */
+    readonly clientName: string;
+    /** Client version advertised during the handshake. */
+    readonly clientVersion: string;
+    /** Server identity reported by the handshake, when the server provided one. */
+    readonly serverInfo: IMcpServerInfo | undefined;
+}
+/**
+ * A tool descriptor discovered from an MCP server via {@link listMcpTools}.
+ * @public
+ */
+export interface IMcpToolDescriptor {
+    /** Tool name (unique within a server). */
+    readonly name: string;
+    /** Human-readable description, when the server provided one. */
+    readonly description: string | undefined;
+    /**
+     * The tool's declared input schema as raw JSON. Per the MCP spec this is normally a JSON
+     * Schema object; carried verbatim so {@link adaptMcpTools} can run it through
+     * `JsonSchema.fromJson` (and surface it on {@link IMcpSkippedTool} when it is outside the
+     * supported subset).
+     */
+    readonly inputSchema: JsonValue;
+}
+/**
+ * Successful projection of an MCP `CallToolResult` produced by {@link callMcpTool}.
+ *
+ * @remarks
+ * `content` is the text concatenation of the result's `text` blocks; non-text blocks
+ * (image / audio / resource) are projected to a one-line `[<type> block]` summary
+ * (multimodal passthrough is out of scope at v0.1). A result with `isError: true` is mapped
+ * to `Result.fail(content)` rather than returned here, so it is never silently swallowed.
+ *
+ * @public
+ */
+export interface IMcpToolCallResult {
+    /** The projected text content of the tool result. */
+    readonly content: string;
+}
+/**
+ * A tool that was discovered but could NOT be adapted into an `AiAssist.IAiClientTool`,
+ * because its `inputSchema` is outside the JSON Schema subset supported by
+ * `JsonSchema.fromJson`. Surfaced structurally so callers/the probe can enumerate exactly which
+ * subset features a server needs (with the raw schema in hand to extend `fromJson` later).
+ * @public
+ */
+export interface IMcpSkippedTool {
+    /** The tool's name. */
+    readonly name: string;
+    /** Why the tool was skipped — the JSON-pointer reason from `JsonSchema.fromJson`, or a structural reason. */
+    readonly reason: string;
+    /** The raw failing input schema, verbatim, in hand for additively widening `JsonSchema.fromJson`. */
+    readonly schema: JsonValue;
+}
+/**
+ * Options for {@link adaptMcpTools}.
+ * @public
+ */
+export interface IAdaptMcpToolsOptions {
+    /**
+     * Logger for the NOISY per-tool skip warnings. When a tool is skipped, a `warning` is emitted
+     * including the tool name, the JSON-pointer reason, and the raw failing schema. When omitted,
+     * skips are still surfaced structurally on {@link IAdaptMcpToolsResult.skipped}.
+     */
+    readonly logger?: Logging.ILogger;
+}
+/**
+ * The result of {@link adaptMcpTools}: cleanly-adapted client tools plus the structurally-surfaced
+ * set of tools that could not be adapted (graceful degradation, Constraint 1).
+ * @public
+ */
+export interface IAdaptMcpToolsResult {
+    /** Tools adapted into `IAiClientTool` — safe to hand to `AiAssist.executeClientToolTurn`. */
+    readonly tools: ReadonlyArray<AiAssist.IAiClientTool>;
+    /** Tools excluded because their `inputSchema` is outside the supported JSON Schema subset. */
+    readonly skipped: ReadonlyArray<IMcpSkippedTool>;
+}
+//# sourceMappingURL=model.d.ts.map

package/lib/packlets/mcp/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/packlets/mcp/model.ts"],"names":[],"mappings":"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"}

package/lib/packlets/mcp/model.js

@@ -0,0 +1,24 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=model.js.map

package/lib/packlets/mcp/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/packlets/mcp/model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Public types for the MCP → ai-assist client-tools boundary.\n * @packageDocumentation\n */\n\nimport { type Logging } from '@fgv/ts-utils';\nimport { type AiAssist } from '@fgv/ts-extras';\nimport { type JsonValue } from '@fgv/ts-json-base';\n\n// ============================================================================\n// Transport\n// ============================================================================\n\n/**\n * Parameters for {@link createStdioTransport}. The transport spawns `command` as a\n * subprocess and speaks MCP over its stdin/stdout.\n *\n * @remarks\n * **Security:** stdio transport executes a consumer-supplied command. Treat `command`/`args`\n * as a trust boundary — never source them from untrusted input. See the package README.\n *\n * @public\n */\nexport interface IMcpStdioTransportParams {\n  /** Executable to spawn (e.g. `'npx'`, `'node'`, an absolute path). */\n  readonly command: string;\n  /** Arguments passed to the command. */\n  readonly args?: ReadonlyArray<string>;\n  /** Environment variables for the spawned process. When omitted, the SDK's safe default set is used. */\n  readonly env?: Record<string, string>;\n  /** Working directory for the spawned process. */\n  readonly cwd?: string;\n}\n\n/**\n * Parameters for {@link createHttpTransport}. The transport connects to a Streamable-HTTP MCP\n * endpoint.\n * @public\n */\nexport interface IMcpHttpTransportParams {\n  /** Absolute `http`/`https` URL of the MCP server endpoint. */\n  readonly url: string;\n  /** Optional static headers (e.g. an `Authorization` bearer token). OAuth/managed auth is out of scope at v0.1. */\n  readonly headers?: Record<string, string>;\n}\n\n/**\n * Opaque handle to an MCP transport produced by {@link createStdioTransport} or\n * {@link createHttpTransport}. Hand it to {@link connectMcpSession}; do not construct directly.\n * @public\n */\nexport interface IMcpTransport {\n  /** Which transport kind this handle wraps. */\n  readonly transportKind: 'stdio' | 'http';\n}\n\n// ============================================================================\n// Session\n// ============================================================================\n\n/**\n * Parameters for {@link connectMcpSession}.\n * @public\n */\nexport interface IConnectMcpSessionParams {\n  /** A transport produced by {@link createStdioTransport} / {@link createHttpTransport}. */\n  readonly transport: IMcpTransport;\n  /** Client name advertised to the server during the initialize handshake. Default `'@fgv/ts-extras-mcp'`. */\n  readonly clientName?: string;\n  /** Client version advertised to the server. Default the package version. */\n  readonly clientVersion?: string;\n  /** Optional logger for connection diagnostics. */\n  readonly logger?: Logging.ILogger;\n}\n\n/**\n * Server identity reported during the MCP initialize handshake.\n * @public\n */\nexport interface IMcpServerInfo {\n  /** Server-advertised name. */\n  readonly name: string;\n  /** Server-advertised version. */\n  readonly version: string;\n}\n\n/**\n * Opaque handle to a connected MCP session. Pass it to {@link listMcpTools},\n * {@link callMcpTool}, {@link adaptMcpTools}, and {@link closeMcpSession}.\n * @public\n */\nexport interface IMcpSession {\n  /** Client name advertised during the handshake. */\n  readonly clientName: string;\n  /** Client version advertised during the handshake. */\n  readonly clientVersion: string;\n  /** Server identity reported by the handshake, when the server provided one. */\n  readonly serverInfo: IMcpServerInfo | undefined;\n}\n\n// ============================================================================\n// Tool discovery + invocation\n// ============================================================================\n\n/**\n * A tool descriptor discovered from an MCP server via {@link listMcpTools}.\n * @public\n */\nexport interface IMcpToolDescriptor {\n  /** Tool name (unique within a server). */\n  readonly name: string;\n  /** Human-readable description, when the server provided one. */\n  readonly description: string | undefined;\n  /**\n   * The tool's declared input schema as raw JSON. Per the MCP spec this is normally a JSON\n   * Schema object; carried verbatim so {@link adaptMcpTools} can run it through\n   * `JsonSchema.fromJson` (and surface it on {@link IMcpSkippedTool} when it is outside the\n   * supported subset).\n   */\n  readonly inputSchema: JsonValue;\n}\n\n/**\n * Successful projection of an MCP `CallToolResult` produced by {@link callMcpTool}.\n *\n * @remarks\n * `content` is the text concatenation of the result's `text` blocks; non-text blocks\n * (image / audio / resource) are projected to a one-line `[<type> block]` summary\n * (multimodal passthrough is out of scope at v0.1). A result with `isError: true` is mapped\n * to `Result.fail(content)` rather than returned here, so it is never silently swallowed.\n *\n * @public\n */\nexport interface IMcpToolCallResult {\n  /** The projected text content of the tool result. */\n  readonly content: string;\n}\n\n// ============================================================================\n// Adapter (Constraint 1)\n// ============================================================================\n\n/**\n * A tool that was discovered but could NOT be adapted into an `AiAssist.IAiClientTool`,\n * because its `inputSchema` is outside the JSON Schema subset supported by\n * `JsonSchema.fromJson`. Surfaced structurally so callers/the probe can enumerate exactly which\n * subset features a server needs (with the raw schema in hand to extend `fromJson` later).\n * @public\n */\nexport interface IMcpSkippedTool {\n  /** The tool's name. */\n  readonly name: string;\n  /** Why the tool was skipped — the JSON-pointer reason from `JsonSchema.fromJson`, or a structural reason. */\n  readonly reason: string;\n  /** The raw failing input schema, verbatim, in hand for additively widening `JsonSchema.fromJson`. */\n  readonly schema: JsonValue;\n}\n\n/**\n * Options for {@link adaptMcpTools}.\n * @public\n */\nexport interface IAdaptMcpToolsOptions {\n  /**\n   * Logger for the NOISY per-tool skip warnings. When a tool is skipped, a `warning` is emitted\n   * including the tool name, the JSON-pointer reason, and the raw failing schema. When omitted,\n   * skips are still surfaced structurally on {@link IAdaptMcpToolsResult.skipped}.\n   */\n  readonly logger?: Logging.ILogger;\n}\n\n/**\n * The result of {@link adaptMcpTools}: cleanly-adapted client tools plus the structurally-surfaced\n * set of tools that could not be adapted (graceful degradation, Constraint 1).\n * @public\n */\nexport interface IAdaptMcpToolsResult {\n  /** Tools adapted into `IAiClientTool` — safe to hand to `AiAssist.executeClientToolTurn`. */\n  readonly tools: ReadonlyArray<AiAssist.IAiClientTool>;\n  /** Tools excluded because their `inputSchema` is outside the supported JSON Schema subset. */\n  readonly skipped: ReadonlyArray<IMcpSkippedTool>;\n}\n"]}

package/lib/packlets/mcp/operations.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tool discovery (`listMcpTools`, paginated) and invocation (`callMcpTool`, with `CallToolResult`
+ * projection), converting the throwing SDK calls into `Result<T>`.
+ * @packageDocumentation
+ */
+import { type Result } from '@fgv/ts-utils';
+import { type JsonObject } from '@fgv/ts-json-base';
+import { type IMcpSession, type IMcpToolCallResult, type IMcpToolDescriptor } from './model';
+/**
+ * Lists every tool a connected MCP server advertises, following the SDK's `nextCursor`
+ * pagination until the full catalog is accumulated.
+ *
+ * @param session - A session from `connectMcpSession`.
+ * @returns `Success` with the full tool catalog, or `Failure` on a foreign handle or a
+ * transport/protocol error.
+ * @public
+ */
+export declare function listMcpTools(session: IMcpSession): Promise<Result<ReadonlyArray<IMcpToolDescriptor>>>;
+/**
+ * Calls a named tool on a connected MCP server.
+ *
+ * @remarks
+ * The SDK `CallToolResult` is projected to {@link IMcpToolCallResult} (text-block concatenation;
+ * non-text blocks summarized). A result flagged `isError: true` is mapped to `Result.fail` with
+ * the projected content — it is never swallowed, so `executeClientToolTurn` routes it back to the
+ * model as a provider-native error tool-result.
+ *
+ * @param session - A session from `connectMcpSession`.
+ * @param name - The tool name to invoke.
+ * @param args - The tool arguments (a JSON object).
+ * @returns `Success` with the projected content, or `Failure` on tool error / transport error /
+ * foreign handle.
+ * @public
+ */
+export declare function callMcpTool(session: IMcpSession, name: string, args: JsonObject): Promise<Result<IMcpToolCallResult>>;
+//# sourceMappingURL=operations.d.ts.map

package/lib/packlets/mcp/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../../src/packlets/mcp/operations.ts"],"names":[],"mappings":"AAsBA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAqC,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAgC7F;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAyB3G;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAkBrC"}

package/lib/packlets/mcp/operations.js

@@ -0,0 +1,123 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listMcpTools = listMcpTools;
+exports.callMcpTool = callMcpTool;
+/**
+ * Tool discovery (`listMcpTools`, paginated) and invocation (`callMcpTool`, with `CallToolResult`
+ * projection), converting the throwing SDK calls into `Result<T>`.
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const session_1 = require("./session");
+/**
+ * Projects a single SDK tool descriptor into a public {@link IMcpToolDescriptor}. The
+ * `inputSchema` field is validated as a `JsonValue`; an absent/non-JSON schema becomes `null`
+ * (which {@link adaptMcpTools} then reports as un-adaptable rather than offering it to the model).
+ */
+function _toDescriptor(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: ts_json_base_1.Converters.jsonValue.convert(tool.inputSchema).orDefault(null)
+    };
+}
+/**
+ * Projects the SDK `CallToolResult` content blocks to a single string: `text` blocks are
+ * concatenated; every other block type becomes a one-line `[<type> block]` summary.
+ */
+function _projectContent(blocks) {
+    if (blocks === undefined || blocks.length === 0) {
+        return '';
+    }
+    return blocks
+        .map((block) => block.type === 'text' && block.text !== undefined ? block.text : `[${block.type} block]`)
+        .join('\n');
+}
+/**
+ * Lists every tool a connected MCP server advertises, following the SDK's `nextCursor`
+ * pagination until the full catalog is accumulated.
+ *
+ * @param session - A session from `connectMcpSession`.
+ * @returns `Success` with the full tool catalog, or `Failure` on a foreign handle or a
+ * transport/protocol error.
+ * @public
+ */
+async function listMcpTools(session) {
+    const sessionResult = session_1.McpSession.fromHandle(session);
+    if (sessionResult.isFailure()) {
+        return (0, ts_utils_1.fail)(`listMcpTools: ${sessionResult.message}`);
+    }
+    const { client } = sessionResult.value;
+    const all = [];
+    let cursor;
+    // Cursor-paginated loop: fetch each page, accumulate, advance until nextCursor is absent.
+    do {
+        const pageResult = await (0, ts_utils_1.captureAsyncResult)(() => client.listTools(cursor !== undefined ? { cursor } : undefined)).withErrorFormat((msg) => `listMcpTools: ${msg}`);
+        if (pageResult.isFailure()) {
+            return (0, ts_utils_1.fail)(pageResult.message);
+        }
+        for (const tool of pageResult.value.tools) {
+            all.push(_toDescriptor(tool));
+        }
+        cursor = pageResult.value.nextCursor;
+    } while (cursor !== undefined);
+    return (0, ts_utils_1.succeed)(all);
+}
+/**
+ * Calls a named tool on a connected MCP server.
+ *
+ * @remarks
+ * The SDK `CallToolResult` is projected to {@link IMcpToolCallResult} (text-block concatenation;
+ * non-text blocks summarized). A result flagged `isError: true` is mapped to `Result.fail` with
+ * the projected content — it is never swallowed, so `executeClientToolTurn` routes it back to the
+ * model as a provider-native error tool-result.
+ *
+ * @param session - A session from `connectMcpSession`.
+ * @param name - The tool name to invoke.
+ * @param args - The tool arguments (a JSON object).
+ * @returns `Success` with the projected content, or `Failure` on tool error / transport error /
+ * foreign handle.
+ * @public
+ */
+async function callMcpTool(session, name, args) {
+    const sessionResult = session_1.McpSession.fromHandle(session);
+    if (sessionResult.isFailure()) {
+        return (0, ts_utils_1.fail)(`callMcpTool: ${sessionResult.message}`);
+    }
+    // The `withErrorFormat` wraps only transport/throw failures (it transforms the failure flowing
+    // out of `captureAsyncResult`); the `isError` failure created in the later `onSuccess` is
+    // downstream and stays clean, so the model-facing tool-error text is the server's verbatim
+    // content rather than a doubly-prefixed message.
+    return (0, ts_utils_1.captureAsyncResult)(() => sessionResult.value.client.callTool({ name, arguments: args }))
+        .withErrorFormat((msg) => `callMcpTool '${name}': ${msg}`)
+        .onSuccess((raw) => {
+        const content = _projectContent(raw.content);
+        if (raw.isError === true) {
+            return (0, ts_utils_1.fail)(content.length > 0 ? content : `tool '${name}' reported an error`);
+        }
+        return (0, ts_utils_1.succeed)({ content });
+    });
+}
+//# sourceMappingURL=operations.js.map

package/lib/packlets/mcp/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../src/packlets/mcp/operations.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AAoDH,oCAyBC;AAkBD,kCAsBC;AAnHD;;;;GAIG;AAEH,4CAA+E;AAC/E,oDAAgE;AAIhE,uCAAuC;AAEvC;;;;GAIG;AACH,SAAS,aAAa,CAAC,IAAwB;IAC7C,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,yBAAU,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC;KAC5E,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,MAAmD;IAC1E,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,MAAM;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACb,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,SAAS,CACzF;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,YAAY,CAAC,OAAoB;IACrD,MAAM,aAAa,GAAG,oBAAU,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,aAAa,CAAC,SAAS,EAAE,EAAE,CAAC;QAC9B,OAAO,IAAA,eAAI,EAAC,iBAAiB,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC;IAEvC,MAAM,GAAG,GAAyB,EAAE,CAAC;IACrC,IAAI,MAA0B,CAAC;IAE/B,0FAA0F;IAC1F,GAAG,CAAC;QACF,MAAM,UAAU,GAAG,MAAM,IAAA,6BAAkB,EAAC,GAAG,EAAE,CAC/C,MAAM,CAAC,SAAS,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAChE,CAAC,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAC;QACnD,IAAI,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC;YAC3B,OAAO,IAAA,eAAI,EAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YAC1C,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;QAChC,CAAC;QACD,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC;IACvC,CAAC,QAAQ,MAAM,KAAK,SAAS,EAAE;IAE/B,OAAO,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACI,KAAK,UAAU,WAAW,CAC/B,OAAoB,EACpB,IAAY,EACZ,IAAgB;IAEhB,MAAM,aAAa,GAAG,oBAAU,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,aAAa,CAAC,SAAS,EAAE,EAAE,CAAC;QAC9B,OAAO,IAAA,eAAI,EAAC,gBAAgB,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,+FAA+F;IAC/F,0FAA0F;IAC1F,2FAA2F;IAC3F,iDAAiD;IACjD,OAAO,IAAA,6BAAkB,EAAC,GAAG,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;SAC5F,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,gBAAgB,IAAI,MAAM,GAAG,EAAE,CAAC;SACzD,SAAS,CAAC,CAAC,GAAG,EAA8B,EAAE;QAC7C,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO,IAAA,eAAI,EAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,IAAI,qBAAqB,CAAC,CAAC;QACjF,CAAC;QACD,OAAO,IAAA,kBAAO,EAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;AACP,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Tool discovery (`listMcpTools`, paginated) and invocation (`callMcpTool`, with `CallToolResult`\n * projection), converting the throwing SDK calls into `Result<T>`.\n * @packageDocumentation\n */\n\nimport { type Result, captureAsyncResult, fail, succeed } from '@fgv/ts-utils';\nimport { Converters, type JsonObject } from '@fgv/ts-json-base';\n\nimport { type IMcpSession, type IMcpToolCallResult, type IMcpToolDescriptor } from './model';\nimport { type ISdkContentBlock, type ISdkToolDescriptor } from './sdk';\nimport { McpSession } from './session';\n\n/**\n * Projects a single SDK tool descriptor into a public {@link IMcpToolDescriptor}. The\n * `inputSchema` field is validated as a `JsonValue`; an absent/non-JSON schema becomes `null`\n * (which {@link adaptMcpTools} then reports as un-adaptable rather than offering it to the model).\n */\nfunction _toDescriptor(tool: ISdkToolDescriptor): IMcpToolDescriptor {\n  return {\n    name: tool.name,\n    description: tool.description,\n    inputSchema: Converters.jsonValue.convert(tool.inputSchema).orDefault(null)\n  };\n}\n\n/**\n * Projects the SDK `CallToolResult` content blocks to a single string: `text` blocks are\n * concatenated; every other block type becomes a one-line `[<type> block]` summary.\n */\nfunction _projectContent(blocks: ReadonlyArray<ISdkContentBlock> | undefined): string {\n  if (blocks === undefined || blocks.length === 0) {\n    return '';\n  }\n  return blocks\n    .map((block) =>\n      block.type === 'text' && block.text !== undefined ? block.text : `[${block.type} block]`\n    )\n    .join('\\n');\n}\n\n/**\n * Lists every tool a connected MCP server advertises, following the SDK's `nextCursor`\n * pagination until the full catalog is accumulated.\n *\n * @param session - A session from `connectMcpSession`.\n * @returns `Success` with the full tool catalog, or `Failure` on a foreign handle or a\n * transport/protocol error.\n * @public\n */\nexport async function listMcpTools(session: IMcpSession): Promise<Result<ReadonlyArray<IMcpToolDescriptor>>> {\n  const sessionResult = McpSession.fromHandle(session);\n  if (sessionResult.isFailure()) {\n    return fail(`listMcpTools: ${sessionResult.message}`);\n  }\n  const { client } = sessionResult.value;\n\n  const all: IMcpToolDescriptor[] = [];\n  let cursor: string | undefined;\n\n  // Cursor-paginated loop: fetch each page, accumulate, advance until nextCursor is absent.\n  do {\n    const pageResult = await captureAsyncResult(() =>\n      client.listTools(cursor !== undefined ? { cursor } : undefined)\n    ).withErrorFormat((msg) => `listMcpTools: ${msg}`);\n    if (pageResult.isFailure()) {\n      return fail(pageResult.message);\n    }\n    for (const tool of pageResult.value.tools) {\n      all.push(_toDescriptor(tool));\n    }\n    cursor = pageResult.value.nextCursor;\n  } while (cursor !== undefined);\n\n  return succeed(all);\n}\n\n/**\n * Calls a named tool on a connected MCP server.\n *\n * @remarks\n * The SDK `CallToolResult` is projected to {@link IMcpToolCallResult} (text-block concatenation;\n * non-text blocks summarized). A result flagged `isError: true` is mapped to `Result.fail` with\n * the projected content — it is never swallowed, so `executeClientToolTurn` routes it back to the\n * model as a provider-native error tool-result.\n *\n * @param session - A session from `connectMcpSession`.\n * @param name - The tool name to invoke.\n * @param args - The tool arguments (a JSON object).\n * @returns `Success` with the projected content, or `Failure` on tool error / transport error /\n * foreign handle.\n * @public\n */\nexport async function callMcpTool(\n  session: IMcpSession,\n  name: string,\n  args: JsonObject\n): Promise<Result<IMcpToolCallResult>> {\n  const sessionResult = McpSession.fromHandle(session);\n  if (sessionResult.isFailure()) {\n    return fail(`callMcpTool: ${sessionResult.message}`);\n  }\n  // The `withErrorFormat` wraps only transport/throw failures (it transforms the failure flowing\n  // out of `captureAsyncResult`); the `isError` failure created in the later `onSuccess` is\n  // downstream and stays clean, so the model-facing tool-error text is the server's verbatim\n  // content rather than a doubly-prefixed message.\n  return captureAsyncResult(() => sessionResult.value.client.callTool({ name, arguments: args }))\n    .withErrorFormat((msg) => `callMcpTool '${name}': ${msg}`)\n    .onSuccess((raw): Result<IMcpToolCallResult> => {\n      const content = _projectContent(raw.content);\n      if (raw.isError === true) {\n        return fail(content.length > 0 ? content : `tool '${name}' reported an error`);\n      }\n      return succeed({ content });\n    });\n}\n"]}