@fgv/ts-extras-mcp 5.1.0-34

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@fgv/ts-extras-mcp",
+  "version": "5.1.0-34",
+  "description": "Result-integration boundary over @modelcontextprotocol/sdk: connect to MCP servers, discover tools, and adapt them into @fgv/ts-extras ai-assist client tools",
+  "main": "lib/index.js",
+  "types": "dist/ts-extras-mcp.d.ts",
+  "exports": {
+    ".": {
+      "node": {
+        "import": "./lib/index.js",
+        "require": "./lib/index.js"
+      },
+      "default": {
+        "import": "./lib/index.js",
+        "require": "./lib/index.js"
+      },
+      "types": "./dist/ts-extras-mcp.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "heft build --clean",
+    "clean": "heft clean",
+    "test": "heft test --clean",
+    "test-handles": "jest --runInBand --detectOpenHandles",
+    "clean-jest": "jest --clear-cache",
+    "update-snapshot": "jest --updateSnapshot",
+    "coverage": "jest --coverage",
+    "lint": "eslint src --ext .ts",
+    "fixlint": "eslint src --ext .ts --fix"
+  },
+  "keywords": [
+    "typescript",
+    "mcp",
+    "model-context-protocol",
+    "ai-assist",
+    "client-tools",
+    "result"
+  ],
+  "author": "Erik Fortune",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ErikFortune/fgv/issues"
+  },
+  "homepage": "https://github.com/ErikFortune/fgv/tree/main/libraries/ts-extras-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ErikFortune/fgv.git"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@fgv/heft-dual-rig": "workspace:*",
+    "@fgv/ts-utils": "workspace:*",
+    "@fgv/ts-extras": "workspace:*",
+    "@fgv/ts-json-base": "workspace:*",
+    "@fgv/ts-utils-jest": "workspace:*",
+    "@microsoft/api-extractor": "^7.55.2",
+    "@rushstack/eslint-config": "4.6.4",
+    "@rushstack/heft": "1.2.7",
+    "@rushstack/heft-jest-plugin": "1.2.6",
+    "@rushstack/heft-node-rig": "2.11.27",
+    "@types/heft-jest": "1.0.6",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.14.9",
+    "@typescript-eslint/eslint-plugin": "^8.52.0",
+    "@typescript-eslint/parser": "^8.52.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-n": "^17.23.1",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-promise": "^7.2.1",
+    "eslint-plugin-tsdoc": "~0.5.2",
+    "jest": "^29.7.0",
+    "rimraf": "^6.1.2",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "@fgv/ts-utils": "workspace:*",
+    "@fgv/ts-extras": "workspace:*",
+    "@fgv/ts-json-base": "workspace:*"
+  }
+}

package/rush-logs/ts-extras-mcp.build.cache.log

@@ -0,0 +1,3 @@
+Caching build output folders: dist, lib, temp, .rush/temp/operation/build
+Successfully set cache entry.
+Cache key: 5d207610a84e494acaefe7ed13447cda74ddf7da

package/rush-logs/ts-extras-mcp.build.log

@@ -0,0 +1,9 @@
+Invoking: heft build --clean 
+ ---- build started ---- 
+[build:typescript] The TypeScript compiler version 5.9.3 is newer than the latest version that was tested with Heft (5.8); it may not work correctly.
+[build:typescript] Using TypeScript version 5.9.3
+[build:lint] Using ESLint version 9.39.4
+[build:api-extractor] Using API Extractor version 7.58.7
+[build:api-extractor] Analysis will use the bundled TypeScript version 5.9.3
+ ---- build finished (2.731s) ---- 
+-------------------- Finished (2.732s) --------------------

package/src/index.ts

@@ -0,0 +1,50 @@
+/*
+ * 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';

package/src/packlets/mcp/adapter.ts

@@ -0,0 +1,152 @@
+/*
+ * 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 { type Result, succeed } from '@fgv/ts-utils';
+import { AiAssist } from '@fgv/ts-extras';
+import { Converters, JsonSchema, type JsonValue } from '@fgv/ts-json-base';
+
+import {
+  type IAdaptMcpToolsOptions,
+  type IAdaptMcpToolsResult,
+  type IMcpSession,
+  type IMcpSkippedTool,
+  type IMcpToolDescriptor
+} from './model';
+import { callMcpTool, listMcpTools } from './operations';
+
+/**
+ * Per-tool adaptation outcome: either an adapted client tool, or a structurally-surfaced skip.
+ * `adaptMcpTools` never short-circuits on a skip — degradation is structural, not a failure.
+ */
+type IAdaptOutcome =
+  | { readonly kind: 'tool'; readonly tool: AiAssist.IAiClientTool }
+  | { readonly kind: 'skipped'; readonly skipped: IMcpSkippedTool };
+
+/**
+ * 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: IMcpSession, name: string): (args: unknown) => Promise<Result<unknown>> {
+  return async (args: unknown): Promise<Result<unknown>> => {
+    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: IMcpSession, descriptor: IMcpToolDescriptor): IAdaptOutcome {
+  const { name, description, inputSchema } = descriptor;
+
+  const skip = (reason: string, schema: JsonValue): IAdaptOutcome => ({
+    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: AiAssist.IAiClientToolConfig = {
+    type: 'client_tool',
+    name,
+    description: 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: IMcpSession,
+  options?: IAdaptMcpToolsOptions
+): Promise<Result<IAdaptMcpToolsResult>> {
+  return (await listMcpTools(session))
+    .onSuccess((descriptors) => {
+      const tools: AiAssist.IAiClientTool[] = [];
+      const skipped: IMcpSkippedTool[] = [];
+
+      for (const descriptor of descriptors) {
+        const outcome = _adaptOne(session, descriptor);
+        if (outcome.kind === 'tool') {
+          tools.push(outcome.tool);
+        } else {
+          skipped.push(outcome.skipped);
+          options?.logger?.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<IAdaptMcpToolsResult>({ tools, skipped });
+    })
+    .withErrorFormat((msg) => `adaptMcpTools: ${msg}`);
+}

package/src/packlets/mcp/index.ts

@@ -0,0 +1,34 @@
+/*
+ * 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';

package/src/packlets/mcp/model.ts

@@ -0,0 +1,204 @@
+/*
+ * 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 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';
+
+// ============================================================================
+// Transport
+// ============================================================================
+
+/**
+ * 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';
+}
+
+// ============================================================================
+// Session
+// ============================================================================
+
+/**
+ * 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;
+}
+
+// ============================================================================
+// Tool discovery + invocation
+// ============================================================================
+
+/**
+ * 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;
+}
+
+// ============================================================================
+// Adapter (Constraint 1)
+// ============================================================================
+
+/**
+ * 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>;
+}

package/src/packlets/mcp/operations.ts

@@ -0,0 +1,138 @@
+/*
+ * 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 { type Result, captureAsyncResult, fail, succeed } from '@fgv/ts-utils';
+import { Converters, type JsonObject } from '@fgv/ts-json-base';
+
+import { type IMcpSession, type IMcpToolCallResult, type IMcpToolDescriptor } from './model';
+import { type ISdkContentBlock, type ISdkToolDescriptor } from './sdk';
+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: ISdkToolDescriptor): IMcpToolDescriptor {
+  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: ReadonlyArray<ISdkContentBlock> | undefined): string {
+  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: IMcpSession): Promise<Result<ReadonlyArray<IMcpToolDescriptor>>> {
+  const sessionResult = McpSession.fromHandle(session);
+  if (sessionResult.isFailure()) {
+    return fail(`listMcpTools: ${sessionResult.message}`);
+  }
+  const { client } = sessionResult.value;
+
+  const all: IMcpToolDescriptor[] = [];
+  let cursor: string | undefined;
+
+  // 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: IMcpSession,
+  name: string,
+  args: JsonObject
+): Promise<Result<IMcpToolCallResult>> {
+  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): Result<IMcpToolCallResult> => {
+      const content = _projectContent(raw.content);
+      if (raw.isError === true) {
+        return fail(content.length > 0 ? content : `tool '${name}' reported an error`);
+      }
+      return succeed({ content });
+    });
+}