@fgv/ts-extras-mcp 5.1.0-34

package/dist/ts-extras-mcp.d.ts

@@ -0,0 +1,290 @@
+/**
+ * `@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
+ */
+
+import { AiAssist } from '@fgv/ts-extras';
+import { JsonObject } from '@fgv/ts-json-base';
+import { JsonValue } from '@fgv/ts-json-base';
+import { Logging } from '@fgv/ts-utils';
+import { Result } from '@fgv/ts-utils';
+
+/**
+ * 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 declare function adaptMcpTools(session: IMcpSession, options?: IAdaptMcpToolsOptions): Promise<Result<IAdaptMcpToolsResult>>;
+
+/**
+ * Calls a named tool on a connected MCP server.
+ *
+ * @remarks
+ * The SDK `CallToolResult` is projected to {@link IMcpToolCallResult} (text-block concatenation;
+ * non-text blocks summarized). A result flagged `isError: true` is mapped to `Result.fail` with
+ * the projected content — it is never swallowed, so `executeClientToolTurn` routes it back to the
+ * model as a provider-native error tool-result.
+ *
+ * @param session - A session from `connectMcpSession`.
+ * @param name - The tool name to invoke.
+ * @param args - The tool arguments (a JSON object).
+ * @returns `Success` with the projected content, or `Failure` on tool error / transport error /
+ * foreign handle.
+ * @public
+ */
+export declare function callMcpTool(session: IMcpSession, name: string, args: JsonObject): Promise<Result<IMcpToolCallResult>>;
+
+/**
+ * Closes an MCP session, tearing down the transport (and any spawned subprocess).
+ *
+ * @param session - A session from {@link connectMcpSession}.
+ * @returns `Success(true)`, or `Failure` if the handle is foreign or the close call throws.
+ * @public
+ */
+export declare function closeMcpSession(session: IMcpSession): Promise<Result<true>>;
+
+/**
+ * Connects to an MCP server over the given transport and performs the initialize handshake.
+ *
+ * @param params - Transport plus optional client identity and logger.
+ * @returns `Success` with an opaque {@link IMcpSession}, or `Failure` if the transport handle is
+ * foreign or the connection/handshake fails.
+ * @public
+ */
+export declare function connectMcpSession(params: IConnectMcpSessionParams): Promise<Result<IMcpSession>>;
+
+/**
+ * Creates a Streamable-HTTP MCP transport for the given endpoint URL.
+ *
+ * @param params - The endpoint URL and optional static headers.
+ * @returns `Success` with an opaque transport handle, or `Failure` if the URL is invalid or the
+ * SDK constructor throws.
+ * @public
+ */
+export declare function createHttpTransport(params: IMcpHttpTransportParams): Result<IMcpTransport>;
+
+/**
+ * Creates a stdio MCP transport that speaks MCP over the stdin/stdout of a spawned subprocess.
+ *
+ * @remarks
+ * **Security — trust boundary.** The transport spawns `params.command` (with `params.args`) as a
+ * child process. Never source the command or arguments from untrusted input; treat them with the
+ * same care as any shell-out. See the package README's security note.
+ *
+ * @param params - The command, arguments, environment, and working directory.
+ * @returns `Success` with an opaque transport handle, or `Failure` if the SDK constructor throws
+ * (e.g. an empty command).
+ * @public
+ */
+export declare function createStdioTransport(params: IMcpStdioTransportParams): Result<IMcpTransport>;
+
+/**
+ * Options for {@link adaptMcpTools}.
+ * @public
+ */
+export declare 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 declare 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>;
+}
+
+/**
+ * Parameters for {@link connectMcpSession}.
+ * @public
+ */
+export declare 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;
+}
+
+/**
+ * Parameters for {@link createHttpTransport}. The transport connects to a Streamable-HTTP MCP
+ * endpoint.
+ * @public
+ */
+export declare 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>;
+}
+
+/**
+ * Server identity reported during the MCP initialize handshake.
+ * @public
+ */
+export declare 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 declare interface IMcpSession {
+    /** Client name advertised during the handshake. */
+    readonly clientName: string;
+    /** Client version advertised during the handshake. */
+    readonly clientVersion: string;
+    /** Server identity reported by the handshake, when the server provided one. */
+    readonly serverInfo: IMcpServerInfo | undefined;
+}
+
+/**
+ * A tool 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 declare 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;
+}
+
+/**
+ * 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 declare 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;
+}
+
+/**
+ * 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 declare interface IMcpToolCallResult {
+    /** The projected text content of the tool result. */
+    readonly content: string;
+}
+
+/**
+ * A tool descriptor discovered from an MCP server via {@link listMcpTools}.
+ * @public
+ */
+export declare 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;
+}
+
+/**
+ * Opaque handle to an MCP transport produced by {@link createStdioTransport} or
+ * {@link createHttpTransport}. Hand it to {@link connectMcpSession}; do not construct directly.
+ * @public
+ */
+export declare interface IMcpTransport {
+    /** Which transport kind this handle wraps. */
+    readonly transportKind: 'stdio' | 'http';
+}
+
+/**
+ * Lists every tool a connected MCP server advertises, following the SDK's `nextCursor`
+ * pagination until the full catalog is accumulated.
+ *
+ * @param session - A session from `connectMcpSession`.
+ * @returns `Success` with the full tool catalog, or `Failure` on a foreign handle or a
+ * transport/protocol error.
+ * @public
+ */
+export declare function listMcpTools(session: IMcpSession): Promise<Result<ReadonlyArray<IMcpToolDescriptor>>>;
+
+export { }

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.7"
+    }
+  ]
+}

package/eslint.config.js

@@ -0,0 +1,15 @@
+// ESLint 9 flat config
+const nodeProfile = require('@rushstack/eslint-config/flat/profile/node');
+const packletsPlugin = require('@rushstack/eslint-config/flat/mixins/packlets');
+const tsdocPlugin = require('@rushstack/eslint-config/flat/mixins/tsdoc');
+
+module.exports = [
+  ...nodeProfile,
+  packletsPlugin,
+  ...tsdocPlugin,
+  {
+    rules: {
+      '@rushstack/packlets/mechanics': 'warn'
+    }
+  }
+];

package/etc/ts-extras-mcp.api.md

@@ -0,0 +1,104 @@
+## API Report File for "@fgv/ts-extras-mcp"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { AiAssist } from '@fgv/ts-extras';
+import { JsonObject } from '@fgv/ts-json-base';
+import { JsonValue } from '@fgv/ts-json-base';
+import { Logging } from '@fgv/ts-utils';
+import { Result } from '@fgv/ts-utils';
+
+// @public
+export function adaptMcpTools(session: IMcpSession, options?: IAdaptMcpToolsOptions): Promise<Result<IAdaptMcpToolsResult>>;
+
+// @public
+export function callMcpTool(session: IMcpSession, name: string, args: JsonObject): Promise<Result<IMcpToolCallResult>>;
+
+// @public
+export function closeMcpSession(session: IMcpSession): Promise<Result<true>>;
+
+// @public
+export function connectMcpSession(params: IConnectMcpSessionParams): Promise<Result<IMcpSession>>;
+
+// @public
+export function createHttpTransport(params: IMcpHttpTransportParams): Result<IMcpTransport>;
+
+// @public
+export function createStdioTransport(params: IMcpStdioTransportParams): Result<IMcpTransport>;
+
+// @public
+export interface IAdaptMcpToolsOptions {
+    readonly logger?: Logging.ILogger;
+}
+
+// @public
+export interface IAdaptMcpToolsResult {
+    readonly skipped: ReadonlyArray<IMcpSkippedTool>;
+    readonly tools: ReadonlyArray<AiAssist.IAiClientTool>;
+}
+
+// @public
+export interface IConnectMcpSessionParams {
+    readonly clientName?: string;
+    readonly clientVersion?: string;
+    readonly logger?: Logging.ILogger;
+    readonly transport: IMcpTransport;
+}
+
+// @public
+export interface IMcpHttpTransportParams {
+    readonly headers?: Record<string, string>;
+    readonly url: string;
+}
+
+// @public
+export interface IMcpServerInfo {
+    readonly name: string;
+    readonly version: string;
+}
+
+// @public
+export interface IMcpSession {
+    readonly clientName: string;
+    readonly clientVersion: string;
+    readonly serverInfo: IMcpServerInfo | undefined;
+}
+
+// @public
+export interface IMcpSkippedTool {
+    readonly name: string;
+    readonly reason: string;
+    readonly schema: JsonValue;
+}
+
+// @public
+export interface IMcpStdioTransportParams {
+    readonly args?: ReadonlyArray<string>;
+    readonly command: string;
+    readonly cwd?: string;
+    readonly env?: Record<string, string>;
+}
+
+// @public
+export interface IMcpToolCallResult {
+    readonly content: string;
+}
+
+// @public
+export interface IMcpToolDescriptor {
+    readonly description: string | undefined;
+    readonly inputSchema: JsonValue;
+    readonly name: string;
+}
+
+// @public
+export interface IMcpTransport {
+    readonly transportKind: 'stdio' | 'http';
+}
+
+// @public
+export function listMcpTools(session: IMcpSession): Promise<Result<ReadonlyArray<IMcpToolDescriptor>>>;
+
+```

package/lib/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@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.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,cAAc,gBAAgB,CAAC"}

package/lib/index.js

@@ -0,0 +1,65 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `@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
+ */
+__exportStar(require("./packlets/mcp"), exports);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,iDAA+B","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/lib/packlets/mcp/adapter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 } from '@fgv/ts-utils';
+import { type IAdaptMcpToolsOptions, type IAdaptMcpToolsResult, type IMcpSession } from './model';
+/**
+ * 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 declare function adaptMcpTools(session: IMcpSession, options?: IAdaptMcpToolsOptions): Promise<Result<IAdaptMcpToolsResult>>;
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/packlets/mcp/adapter.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAW,MAAM,eAAe,CAAC;AAIrD,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAGjB,MAAM,SAAS,CAAC;AA+DjB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAuBvC"}