@fgv/ts-extras-mcp 5.1.0-34

package/CHANGELOG.json

@@ -0,0 +1,4 @@
+{
+  "name": "@fgv/ts-extras-mcp",
+  "entries": []
+}

package/README.md

@@ -0,0 +1,133 @@
+# @fgv/ts-extras-mcp
+
+Result-integration boundary over [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk)
+for Node consumers. Connect to MCP (Model Context Protocol) servers, discover their tools, and
+**adapt each into an `AiAssist.IAiClientTool`** from
+[`@fgv/ts-extras`](../ts-extras) so it drops directly into `AiAssist.executeClientToolTurn`.
+
+Net effect: any MCP server's tools become callable across all four cloud providers (Anthropic,
+OpenAI, Gemini, xAI) with no per-provider work.
+
+---
+
+## What this is
+
+A thin facade that wraps `@modelcontextprotocol/sdk` calls in `Result<T>` from `@fgv/ts-utils`,
+mirroring the discipline established by
+[`@fgv/ts-extras-webauthn`](../ts-extras-webauthn) and
+[`@fgv/ts-extras-transformers`](../ts-extras-transformers): `captureAsyncResult` conversion of the
+upstream throw-based API into `Result<T>`, plus exactly one piece of glue — converting MCP tool
+descriptors into `IAiClientTool[]`. **No opinionated orchestration above the boundary.**
+
+All `@modelcontextprotocol/sdk` imports live in a single file (`src/packlets/mcp/sdk.ts`) so the
+announced SDK v2 client-package rename is a one-file change.
+
+## Explicitly NOT in scope
+
+These were considered and deferred — use `@modelcontextprotocol/sdk` directly (with
+`captureAsyncResult` for your own Result wrapping) for any of them:
+
+- **Browser sibling** (`@fgv/ts-web-extras-mcp`) — Node-only at v0.1.
+- **MCP resources / prompts / sampling** — tool discovery + invocation only.
+- **OAuth / managed auth** — static headers only (`createHttpTransport({ headers })`).
+- **Multimodal tool-result passthrough** — non-text content blocks are projected to a one-line
+  `[<type> block]` summary.
+- **Cross-server tool-name namespacing** — duplicate tool names already fail loudly in
+  `AiAssist.executeClientToolTurn`.
+- **MCP server orchestration / lifecycle management beyond a single session.**
+
+See [`docs/FUTURE.md`](../../docs/FUTURE.md) for the tracked follow-ups.
+
+## The primitives
+
+| Function | Return |
+|---|---|
+| `createStdioTransport({ command, args?, env?, cwd? })` | `Result<IMcpTransport>` |
+| `createHttpTransport({ url, headers? })` | `Result<IMcpTransport>` |
+| `connectMcpSession({ transport, clientName?, clientVersion?, logger? })` | `Promise<Result<IMcpSession>>` |
+| `closeMcpSession(session)` | `Promise<Result<true>>` |
+| `listMcpTools(session)` | `Promise<Result<ReadonlyArray<IMcpToolDescriptor>>>` |
+| `callMcpTool(session, name, args)` | `Promise<Result<IMcpToolCallResult>>` |
+| `adaptMcpTools(session, { logger? })` | `Promise<Result<IAdaptMcpToolsResult>>` |
+
+## Usage
+
+```typescript
+import {
+  createStdioTransport,
+  connectMcpSession,
+  adaptMcpTools,
+  closeMcpSession
+} from '@fgv/ts-extras-mcp';
+import { AiAssist } from '@fgv/ts-extras';
+
+// 1. Connect to an MCP server (stdio spawns a subprocess; see the security note below).
+const transport = createStdioTransport({
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-everything']
+}).orThrow();
+
+const sessionResult = await connectMcpSession({ transport });
+if (sessionResult.isFailure()) {
+  // connection / handshake failed
+  return;
+}
+const session = sessionResult.value;
+
+// 2. Adapt the server's tools into ai-assist client tools.
+const adaptResult = (await adaptMcpTools(session, { logger })).orThrow();
+
+// adaptResult.tools  → ReadonlyArray<AiAssist.IAiClientTool>, ready to hand to the model
+// adaptResult.skipped → tools whose inputSchema is outside the supported JSON Schema subset
+//                       (each carries the failing schema + a JSON-pointer reason)
+
+// 3. Drop the adapted tools straight into the client-tools turn loop.
+const turn = AiAssist.executeClientToolTurn({
+  descriptor,
+  apiKey,
+  prompt,
+  clientTools: adaptResult.tools
+}).orThrow();
+
+// ... iterate turn.events / await turn.nextTurn ...
+
+await closeMcpSession(session);
+```
+
+### Graceful degradation (load-bearing)
+
+`adaptMcpTools` **never fails the whole catalog because one tool's schema is unsupported.** When a
+discovered tool's `inputSchema` is outside the JSON Schema subset that
+[`JsonSchema.fromJson`](../ts-json-base) supports, that one tool is excluded from `tools` (the
+model is never offered a tool whose arguments we can't validate), surfaced structurally on
+`skipped` (with the tool name, the JSON-pointer reason, and the raw failing schema), and — when a
+`logger` is supplied — logged as a NOISY `warning` carrying all three. Point this at a new server
+and you immediately see every schema feature that needs additive support in `JsonSchema.fromJson`.
+
+## Compatibility probe
+
+The `samples/testbed` `mcp-probe` scenario points this package at any MCP server and prints a
+compatibility report (adapted vs. skipped tools, with the failing schema + reason for each skip).
+Run it without wiring the server into an application:
+
+```sh
+# stdio server:
+MCP_PROBE_COMMAND=npx MCP_PROBE_ARGS="-y @modelcontextprotocol/server-everything" \
+  node samples/testbed/bin/testbed.js --scenario mcp-probe
+
+# HTTP server:
+MCP_PROBE_URL=http://localhost:3001/mcp MCP_PROBE_HEADERS="authorization=Bearer xyz" \
+  node samples/testbed/bin/testbed.js --scenario mcp-probe
+```
+
+## Security — stdio transport trust boundary
+
+`createStdioTransport` spawns `command` (with `args`) as a **child process**. The command runs
+with the privileges of the host process. **Never source the command, arguments, or environment
+from untrusted input** — treat them with the same care as any shell-out. The HTTP transport
+(`createHttpTransport`) does not spawn a process; supply credentials via static `headers`.
+
+## Runtime requirements
+
+- Node.js 20 LTS or later.
+- `@modelcontextprotocol/sdk` `^1.29.0` (a direct dependency).

package/config/api-extractor.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "projectFolder": "..",
+  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
+  "bundledPackages": [],
+  "compiler": {},
+  "apiReport": {
+    "enabled": true
+  },
+  "docModel": {
+    "enabled": true
+  },
+  "dtsRollup": {
+    "enabled": true
+  },
+  "tsdocMetadata": {},
+  "messages": {
+    "compilerMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+    "extractorMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      },
+      "ae-unresolved-link": {
+        "logLevel": "none",
+        "addToApiReportFile": true
+      }
+    },
+    "tsdocMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    }
+  }
+}

package/config/jest.config.json

@@ -0,0 +1,13 @@
+{
+  "extends": "@rushstack/heft-node-rig/profiles/default/config/jest.config.json",
+  "coverageThreshold": {
+    "global": {
+      "branches": 100,
+      "functions": 100,
+      "lines": 100,
+      "statements": 100
+    }
+  },
+  "collectCoverage": true,
+  "coverageReporters": ["text", "lcov", "html"]
+}

package/config/rig.json

@@ -0,0 +1,6 @@
+// The "rig.json" file directs tools to look for their config files in an external package.
+// Documentation for this system: https://www.npmjs.com/package/@rushstack/rig-package
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@fgv/heft-dual-rig"
+}

package/dist/index.js

@@ -0,0 +1,49 @@
+/*
+ * 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.
+ */
+/**
+ * `@fgv/ts-extras-mcp` — a Result-integration boundary over `@modelcontextprotocol/sdk` that
+ * connects to MCP (Model Context Protocol) servers, discovers their tools, and adapts each into
+ * an `AiAssist.IAiClientTool` so it drops directly into `AiAssist.executeClientToolTurn` —
+ * making any MCP server's tools callable across all four cloud providers with no per-provider work.
+ *
+ * Mirrors the discipline of `@fgv/ts-extras-webauthn` / `@fgv/ts-extras-transformers`: thin
+ * `Result<T>` conversion over a well-maintained upstream SDK, with no opinionated orchestration
+ * above the boundary.
+ *
+ * **In scope (slice 1, Node):** transport factories (`createStdioTransport`,
+ * `createHttpTransport`), session lifecycle (`connectMcpSession`, `closeMcpSession`), tool
+ * discovery + invocation (`listMcpTools`, `callMcpTool`), and the headline adapter
+ * (`adaptMcpTools`) which gracefully degrades on tools whose `inputSchema` is outside the
+ * supported JSON Schema subset (surfacing them on `skipped` and warning NOISILY).
+ *
+ * **Explicitly NOT in scope (deferred — see README / docs/FUTURE.md):**
+ * - Browser sibling `@fgv/ts-web-extras-mcp`
+ * - MCP resources / prompts / sampling features
+ * - OAuth / managed auth (static headers only at v0.1)
+ * - Multimodal tool-result passthrough (text-block projection only)
+ * - Cross-server tool-name namespacing (duplicate names already fail loudly in
+ *   `executeClientToolTurn`)
+ *
+ * @packageDocumentation
+ */
+export * from './packlets/mcp';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,cAAc,gBAAgB,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 * `@fgv/ts-extras-mcp` — a Result-integration boundary over `@modelcontextprotocol/sdk` that\n * connects to MCP (Model Context Protocol) servers, discovers their tools, and adapts each into\n * an `AiAssist.IAiClientTool` so it drops directly into `AiAssist.executeClientToolTurn` —\n * making any MCP server's tools callable across all four cloud providers with no per-provider work.\n *\n * Mirrors the discipline of `@fgv/ts-extras-webauthn` / `@fgv/ts-extras-transformers`: thin\n * `Result<T>` conversion over a well-maintained upstream SDK, with no opinionated orchestration\n * above the boundary.\n *\n * **In scope (slice 1, Node):** transport factories (`createStdioTransport`,\n * `createHttpTransport`), session lifecycle (`connectMcpSession`, `closeMcpSession`), tool\n * discovery + invocation (`listMcpTools`, `callMcpTool`), and the headline adapter\n * (`adaptMcpTools`) which gracefully degrades on tools whose `inputSchema` is outside the\n * supported JSON Schema subset (surfacing them on `skipped` and warning NOISILY).\n *\n * **Explicitly NOT in scope (deferred — see README / docs/FUTURE.md):**\n * - Browser sibling `@fgv/ts-web-extras-mcp`\n * - MCP resources / prompts / sampling features\n * - OAuth / managed auth (static headers only at v0.1)\n * - Multimodal tool-result passthrough (text-block projection only)\n * - Cross-server tool-name namespacing (duplicate names already fail loudly in\n *   `executeClientToolTurn`)\n *\n * @packageDocumentation\n */\n\nexport * from './packlets/mcp';\n"]}

package/dist/packlets/mcp/adapter.js

@@ -0,0 +1,122 @@
+/*
+ * 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.
+ */
+/**
+ * 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
+ */
+import { succeed } from '@fgv/ts-utils';
+import { Converters, JsonSchema } from '@fgv/ts-json-base';
+import { callMcpTool, listMcpTools } from './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 = Converters.jsonObject
+            .convert(args)
+            .withErrorFormat((msg) => `tool '${name}': arguments must be a JSON object: ${msg}`);
+        if (objResult.isFailure()) {
+            return objResult;
+        }
+        return (await callMcpTool(session, name, objResult.value)).onSuccess((called) => 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 = Converters.jsonObject.convert(inputSchema);
+    if (asObject.isFailure()) {
+        return skip(`inputSchema is not a JSON object (${asObject.message})`, inputSchema);
+    }
+    const schemaResult = 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
+ */
+export async function adaptMcpTools(session, options) {
+    return (await 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 succeed({ tools, skipped });
+    })
+        .withErrorFormat((msg) => `adaptMcpTools: ${msg}`);
+}
+//# sourceMappingURL=adapter.js.map

package/dist/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/dist/packlets/mcp/index.js

@@ -0,0 +1,33 @@
+/*
+ * 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.
+ */
+/**
+ * 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.
+export * from './model';
+export { createHttpTransport, createStdioTransport } from './transports';
+export { closeMcpSession, connectMcpSession } from './session';
+export { callMcpTool, listMcpTools } from './operations';
+export { adaptMcpTools } from './adapter';
+//# sourceMappingURL=index.js.map

package/dist/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,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","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/dist/packlets/mcp/model.js

@@ -0,0 +1,23 @@
+/*
+ * 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.
+ */
+export {};
+//# sourceMappingURL=model.js.map

package/dist/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/dist/packlets/mcp/operations.js

@@ -0,0 +1,119 @@
+/*
+ * 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.
+ */
+/**
+ * Tool discovery (`listMcpTools`, paginated) and invocation (`callMcpTool`, with `CallToolResult`
+ * projection), converting the throwing SDK calls into `Result<T>`.
+ * @packageDocumentation
+ */
+import { captureAsyncResult, fail, succeed } from '@fgv/ts-utils';
+import { Converters } from '@fgv/ts-json-base';
+import { McpSession } from './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: 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
+ */
+export async function listMcpTools(session) {
+    const sessionResult = McpSession.fromHandle(session);
+    if (sessionResult.isFailure()) {
+        return 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 captureAsyncResult(() => client.listTools(cursor !== undefined ? { cursor } : undefined)).withErrorFormat((msg) => `listMcpTools: ${msg}`);
+        if (pageResult.isFailure()) {
+            return fail(pageResult.message);
+        }
+        for (const tool of pageResult.value.tools) {
+            all.push(_toDescriptor(tool));
+        }
+        cursor = pageResult.value.nextCursor;
+    } while (cursor !== undefined);
+    return 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
+ */
+export async function callMcpTool(session, name, args) {
+    const sessionResult = McpSession.fromHandle(session);
+    if (sessionResult.isFailure()) {
+        return 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 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 fail(content.length > 0 ? content : `tool '${name}' reported an error`);
+        }
+        return succeed({ content });
+    });
+}
+//# sourceMappingURL=operations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../src/packlets/mcp/operations.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 * 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"]}