@fgv/ts-extras-mcp 5.1.0-47 → 5.1.0-49

package/lib/test/unit/sdk.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sdk.test.d.ts","sourceRoot":"","sources":["../../../src/test/unit/sdk.test.ts"],"names":[],"mappings":""}

package/lib/test/unit/sdk.test.js

@@ -1,70 +0,0 @@
-"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 });
-// Exercises the real SDK-isolation seam (the one file that imports @modelcontextprotocol/sdk).
-// Constructing the SDK objects is side-effect-free — no process is spawned and no network call is
-// made until a transport is connected, so these factory calls are safe in a unit test.
-// eslint-disable-next-line @rushstack/packlets/mechanics
-const sdk_1 = require("../../packlets/mcp/sdk");
-describe('sdk isolation seam', () => {
-    describe('makeClient', () => {
-        test('constructs a client exposing the projected surface', () => {
-            const client = (0, sdk_1.makeClient)('test-client', '9.9.9');
-            expect(typeof client.connect).toBe('function');
-            expect(typeof client.listTools).toBe('function');
-            expect(typeof client.callTool).toBe('function');
-            expect(typeof client.close).toBe('function');
-            expect(typeof client.getServerVersion).toBe('function');
-            // Before connecting, the server identity is unknown.
-            expect(client.getServerVersion()).toBeUndefined();
-        });
-    });
-    describe('makeStdioTransport', () => {
-        test('constructs a transport with full params (args/env/cwd)', () => {
-            const transport = (0, sdk_1.makeStdioTransport)({
-                command: 'node',
-                args: ['--version'],
-                env: { FOO: 'bar' },
-                cwd: '/tmp'
-            });
-            expect(transport).toBeDefined();
-        });
-        test('constructs a transport with only a command (args omitted)', () => {
-            const transport = (0, sdk_1.makeStdioTransport)({ command: 'node' });
-            expect(transport).toBeDefined();
-        });
-    });
-    describe('makeHttpTransport', () => {
-        test('constructs a transport with headers', () => {
-            const transport = (0, sdk_1.makeHttpTransport)(new URL('http://localhost:9000/mcp'), {
-                authorization: 'Bearer x'
-            });
-            expect(transport).toBeDefined();
-        });
-        test('constructs a transport without headers', () => {
-            const transport = (0, sdk_1.makeHttpTransport)(new URL('https://example.com/mcp'));
-            expect(transport).toBeDefined();
-        });
-    });
-});
-//# sourceMappingURL=sdk.test.js.map

package/lib/test/unit/sdk.test.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"sdk.test.js","sourceRoot":"","sources":["../../../src/test/unit/sdk.test.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AAEH,+FAA+F;AAC/F,kGAAkG;AAClG,uFAAuF;AACvF,yDAAyD;AACzD,gDAA2F;AAE3F,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;QAC1B,IAAI,CAAC,oDAAoD,EAAE,GAAG,EAAE;YAC9D,MAAM,MAAM,GAAG,IAAA,gBAAU,EAAC,aAAa,EAAE,OAAO,CAAC,CAAC;YAClD,MAAM,CAAC,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/C,MAAM,CAAC,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACjD,MAAM,CAAC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAChD,MAAM,CAAC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC7C,MAAM,CAAC,OAAO,MAAM,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACxD,qDAAqD;YACrD,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC,CAAC,aAAa,EAAE,CAAC;QACpD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;QAClC,IAAI,CAAC,wDAAwD,EAAE,GAAG,EAAE;YAClE,MAAM,SAAS,GAAG,IAAA,wBAAkB,EAAC;gBACnC,OAAO,EAAE,MAAM;gBACf,IAAI,EAAE,CAAC,WAAW,CAAC;gBACnB,GAAG,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE;gBACnB,GAAG,EAAE,MAAM;aACZ,CAAC,CAAC;YACH,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;QAClC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,2DAA2D,EAAE,GAAG,EAAE;YACrE,MAAM,SAAS,GAAG,IAAA,wBAAkB,EAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAC1D,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;QAClC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;QACjC,IAAI,CAAC,qCAAqC,EAAE,GAAG,EAAE;YAC/C,MAAM,SAAS,GAAG,IAAA,uBAAiB,EAAC,IAAI,GAAG,CAAC,2BAA2B,CAAC,EAAE;gBACxE,aAAa,EAAE,UAAU;aAC1B,CAAC,CAAC;YACH,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;QAClC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,wCAAwC,EAAE,GAAG,EAAE;YAClD,MAAM,SAAS,GAAG,IAAA,uBAAiB,EAAC,IAAI,GAAG,CAAC,yBAAyB,CAAC,CAAC,CAAC;YACxE,MAAM,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;QAClC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,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// Exercises the real SDK-isolation seam (the one file that imports @modelcontextprotocol/sdk).\n// Constructing the SDK objects is side-effect-free — no process is spawned and no network call is\n// made until a transport is connected, so these factory calls are safe in a unit test.\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport { makeClient, makeHttpTransport, makeStdioTransport } from '../../packlets/mcp/sdk';\n\ndescribe('sdk isolation seam', () => {\n  describe('makeClient', () => {\n    test('constructs a client exposing the projected surface', () => {\n      const client = makeClient('test-client', '9.9.9');\n      expect(typeof client.connect).toBe('function');\n      expect(typeof client.listTools).toBe('function');\n      expect(typeof client.callTool).toBe('function');\n      expect(typeof client.close).toBe('function');\n      expect(typeof client.getServerVersion).toBe('function');\n      // Before connecting, the server identity is unknown.\n      expect(client.getServerVersion()).toBeUndefined();\n    });\n  });\n\n  describe('makeStdioTransport', () => {\n    test('constructs a transport with full params (args/env/cwd)', () => {\n      const transport = makeStdioTransport({\n        command: 'node',\n        args: ['--version'],\n        env: { FOO: 'bar' },\n        cwd: '/tmp'\n      });\n      expect(transport).toBeDefined();\n    });\n\n    test('constructs a transport with only a command (args omitted)', () => {\n      const transport = makeStdioTransport({ command: 'node' });\n      expect(transport).toBeDefined();\n    });\n  });\n\n  describe('makeHttpTransport', () => {\n    test('constructs a transport with headers', () => {\n      const transport = makeHttpTransport(new URL('http://localhost:9000/mcp'), {\n        authorization: 'Bearer x'\n      });\n      expect(transport).toBeDefined();\n    });\n\n    test('constructs a transport without headers', () => {\n      const transport = makeHttpTransport(new URL('https://example.com/mcp'));\n      expect(transport).toBeDefined();\n    });\n  });\n});\n"]}

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

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

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

@@ -1,9 +0,0 @@
-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.5
-[build:api-extractor] Using API Extractor version 7.58.9
-[build:api-extractor] Analysis will use the bundled TypeScript version 5.9.3
- ---- build finished (8.943s) ---- 
--------------------- Finished (8.957s) --------------------

package/src/index.ts

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

@@ -1,155 +0,0 @@
-/*
- * 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, annotations } = 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,
-    // IMcpToolAnnotations maps 1:1 onto AiAssist.IAiToolAnnotations. Only set the field when the
-    // server provided usable annotations, so a tool without them stays exactly as before.
-    ...(annotations !== undefined ? { annotations } : {})
-  };
-  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

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

@@ -1,235 +0,0 @@
-/*
- * 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
-// ============================================================================
-
-/**
- * Normalized MCP `Tool.annotations` — the five known host-advisory behavior hints.
- *
- * @remarks
- * Field names mirror MCP's `ToolAnnotations` 1:1 (and map straight onto
- * `AiAssist.IAiToolAnnotations`). Per the MCP spec these are hints only, and per the
- * untrusted-server warning they are validated/normalized (known fields kept, malformed
- * or unknown fields dropped) before they reach {@link IMcpToolDescriptor} — the raw
- * server blob is never propagated.
- *
- * @public
- */
-export interface IMcpToolAnnotations {
-  /** Optional human-readable display title for the tool. */
-  readonly title?: string;
-  /** Hint: the tool does not modify its environment (read-only). */
-  readonly readOnlyHint?: boolean;
-  /** Hint: the tool may perform destructive updates (only meaningful when not read-only). */
-  readonly destructiveHint?: boolean;
-  /** Hint: repeated calls with the same arguments have no additional effect. */
-  readonly idempotentHint?: boolean;
-  /** Hint: the tool interacts with an open world of external entities. */
-  readonly openWorldHint?: boolean;
-}
-
-/**
- * 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;
-  /**
-   * The tool's normalized behavior annotations, when the server provided any usable ones.
-   * Absent when the server declared no annotations (or only malformed/unknown fields).
-   * See {@link IMcpToolAnnotations}.
-   */
-  readonly annotations?: IMcpToolAnnotations;
-}
-
-/**
- * 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>;
-}