@fgv/ts-extras-mcp 5.1.0-34

package/dist/packlets/mcp/sdk.js

@@ -0,0 +1,67 @@
+/*
+ * 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 single `@modelcontextprotocol/sdk` import site for the entire package.**
+ *
+ * Every other module in `@fgv/ts-extras-mcp` depends only on the minimal local projection
+ * exported here (`ISdkClient`, `ISdkTransport`, the three `make*` factories) — never on the SDK
+ * directly. This keeps the announced v2 client-package rename a one-file change and lets unit
+ * tests mock this module instead of the SDK internals (no live server required).
+ *
+ * The only `as unknown as` casts in the package live here, at the boundary where the real SDK
+ * objects are narrowed to the local projection.
+ *
+ * @internal
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+/**
+ * Constructs an MCP client. The `as unknown as` cast is the package's single SDK-type
+ * bridge — the runtime object is a real SDK `Client`.
+ * @internal
+ */
+export function makeClient(name, version) {
+    return new Client({ name, version }, { capabilities: {} });
+}
+/**
+ * Constructs a stdio transport that spawns the given command as a subprocess.
+ * @internal
+ */
+export function makeStdioTransport(params) {
+    return new StdioClientTransport({
+        command: params.command,
+        args: params.args ? [...params.args] : undefined,
+        env: params.env,
+        cwd: params.cwd
+    });
+}
+/**
+ * Constructs a Streamable-HTTP transport for the given URL, with optional static headers.
+ * @internal
+ */
+export function makeHttpTransport(url, headers) {
+    return new StreamableHTTPClientTransport(url, {
+        requestInit: headers ? { headers } : undefined
+    });
+}
+//# sourceMappingURL=sdk.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.js","sourceRoot":"","sources":["../../../src/packlets/mcp/sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AA+EnG;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,OAAe;IACtD,OAAO,IAAI,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAA0B,CAAC;AACtF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAuB;IACxD,OAAO,IAAI,oBAAoB,CAAC;QAC9B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;QAChD,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,GAAG,EAAE,MAAM,CAAC,GAAG;KAChB,CAA6B,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAQ,EAAE,OAAgC;IAC1E,OAAO,IAAI,6BAA6B,CAAC,GAAG,EAAE;QAC5C,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS;KAC/C,CAA6B,CAAC;AACjC,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 * **The single `@modelcontextprotocol/sdk` import site for the entire package.**\n *\n * Every other module in `@fgv/ts-extras-mcp` depends only on the minimal local projection\n * exported here (`ISdkClient`, `ISdkTransport`, the three `make*` factories) — never on the SDK\n * directly. This keeps the announced v2 client-package rename a one-file change and lets unit\n * tests mock this module instead of the SDK internals (no live server required).\n *\n * The only `as unknown as` casts in the package live here, at the boundary where the real SDK\n * objects are narrowed to the local projection.\n *\n * @internal\n */\n\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';\n\n/**\n * Opaque transport handle. The concrete value is an SDK `Transport`; consumers of this module\n * treat it as opaque and only ever hand it back to {@link makeClient}-produced clients.\n * @internal\n */\nexport type ISdkTransport = object;\n\n/**\n * A single content block in an MCP `CallToolResult`. Only `text` blocks carry inline content;\n * all other block types are projected to a structural summary by the operations layer.\n * @internal\n */\nexport interface ISdkContentBlock {\n  readonly type: string;\n  readonly text?: string;\n}\n\n/**\n * Projection of the SDK's `CallToolResult`.\n * @internal\n */\nexport interface ISdkCallToolResult {\n  readonly content?: ReadonlyArray<ISdkContentBlock>;\n  readonly isError?: boolean;\n}\n\n/**\n * Projection of a single tool descriptor in the SDK's `ListToolsResult`.\n * @internal\n */\nexport interface ISdkToolDescriptor {\n  readonly name: string;\n  readonly description?: string;\n  readonly inputSchema?: unknown;\n}\n\n/**\n * Projection of the SDK's `ListToolsResult` (one page).\n * @internal\n */\nexport interface ISdkListToolsResult {\n  readonly tools: ReadonlyArray<ISdkToolDescriptor>;\n  readonly nextCursor?: string;\n}\n\n/**\n * Server identity returned by the SDK's `getServerVersion()` after the initialize handshake.\n * @internal\n */\nexport interface ISdkImplementation {\n  readonly name: string;\n  readonly version: string;\n}\n\n/**\n * Minimal projection of the SDK `Client` surface the package depends on.\n * @internal\n */\nexport interface ISdkClient {\n  connect(transport: ISdkTransport): Promise<void>;\n  getServerVersion(): ISdkImplementation | undefined;\n  listTools(params?: { cursor?: string }): Promise<ISdkListToolsResult>;\n  callTool(params: { name: string; arguments?: Record<string, unknown> }): Promise<ISdkCallToolResult>;\n  close(): Promise<void>;\n}\n\n/**\n * Parameters for the stdio transport factory.\n * @internal\n */\nexport interface ISdkStdioParams {\n  readonly command: string;\n  readonly args?: ReadonlyArray<string>;\n  readonly env?: Record<string, string>;\n  readonly cwd?: string;\n}\n\n/**\n * Constructs an MCP client. The `as unknown as` cast is the package's single SDK-type\n * bridge — the runtime object is a real SDK `Client`.\n * @internal\n */\nexport function makeClient(name: string, version: string): ISdkClient {\n  return new Client({ name, version }, { capabilities: {} }) as unknown as ISdkClient;\n}\n\n/**\n * Constructs a stdio transport that spawns the given command as a subprocess.\n * @internal\n */\nexport function makeStdioTransport(params: ISdkStdioParams): ISdkTransport {\n  return new StdioClientTransport({\n    command: params.command,\n    args: params.args ? [...params.args] : undefined,\n    env: params.env,\n    cwd: params.cwd\n  }) as unknown as ISdkTransport;\n}\n\n/**\n * Constructs a Streamable-HTTP transport for the given URL, with optional static headers.\n * @internal\n */\nexport function makeHttpTransport(url: URL, headers?: Record<string, string>): ISdkTransport {\n  return new StreamableHTTPClientTransport(url, {\n    requestInit: headers ? { headers } : undefined\n  }) as unknown as ISdkTransport;\n}\n"]}

package/dist/packlets/mcp/session.js

@@ -0,0 +1,109 @@
+/*
+ * 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.
+ */
+/**
+ * Session lifecycle — connect / close, converting the throwing SDK calls into `Result<T>`.
+ * @packageDocumentation
+ */
+import { captureAsyncResult, fail, succeed } from '@fgv/ts-utils';
+import { makeClient } from './sdk';
+import { McpTransport } from './transports';
+/** Default client name advertised during the initialize handshake. */
+const DEFAULT_CLIENT_NAME = '@fgv/ts-extras-mcp';
+/**
+ * Default client version advertised during the initialize handshake.
+ *
+ * @remarks
+ * Keep in sync with this package's `package.json` version on each release. It is informational
+ * only — MCP servers use it for logging/telemetry, not for behavior — so a drift is low-impact,
+ * but it should be bumped alongside the lockstep version. (Reading it from `package.json` at
+ * runtime is avoided to keep the bundle free of a JSON import / `require` of the manifest.)
+ */
+const DEFAULT_CLIENT_VERSION = '5.1.0';
+/**
+ * Concrete session handle. Packlet-internal — carries the live SDK client that the operations
+ * layer recovers via {@link McpSession.fromHandle}. Not exported from the package barrel.
+ * @internal
+ */
+export class McpSession {
+    constructor(client, clientName, clientVersion, serverInfo) {
+        this.client = client;
+        this.clientName = clientName;
+        this.clientVersion = clientVersion;
+        this.serverInfo = serverInfo;
+    }
+    /**
+     * Narrows a public {@link IMcpSession} handle back to the concrete {@link McpSession}. Fails
+     * loudly when handed a foreign object that did not originate from {@link connectMcpSession}.
+     */
+    static fromHandle(handle) {
+        if (handle instanceof McpSession) {
+            return succeed(handle);
+        }
+        return fail('invalid MCP session: expected a handle from connectMcpSession');
+    }
+}
+/**
+ * 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 async function connectMcpSession(params) {
+    const { transport, clientName, clientVersion, logger } = params;
+    const transportResult = McpTransport.fromHandle(transport);
+    if (transportResult.isFailure()) {
+        return fail(`connectMcpSession: ${transportResult.message}`);
+    }
+    const name = clientName !== null && clientName !== void 0 ? clientName : DEFAULT_CLIENT_NAME;
+    const version = clientVersion !== null && clientVersion !== void 0 ? clientVersion : DEFAULT_CLIENT_VERSION;
+    const client = makeClient(name, version);
+    logger === null || logger === void 0 ? void 0 : logger.info(`mcp: connecting (client ${name}@${version}, transport ${transportResult.value.transportKind})`);
+    return captureAsyncResult(() => client.connect(transportResult.value.sdkTransport))
+        .onSuccess(() => {
+        const raw = client.getServerVersion();
+        const serverInfo = raw !== undefined ? { name: raw.name, version: raw.version } : undefined;
+        logger === null || logger === void 0 ? void 0 : logger.info(serverInfo !== undefined
+            ? `mcp: connected to server ${serverInfo.name}@${serverInfo.version}`
+            : 'mcp: connected (server did not report identity)');
+        return succeed(new McpSession(client, name, version, serverInfo));
+    })
+        .withErrorFormat((msg) => `connectMcpSession: ${msg}`);
+}
+/**
+ * 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 async function closeMcpSession(session) {
+    const sessionResult = McpSession.fromHandle(session);
+    if (sessionResult.isFailure()) {
+        return fail(`closeMcpSession: ${sessionResult.message}`);
+    }
+    return captureAsyncResult(() => sessionResult.value.client.close())
+        .onSuccess(() => succeed(true))
+        .withErrorFormat((msg) => `closeMcpSession: ${msg}`);
+}
+//# sourceMappingURL=session.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/packlets/mcp/session.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 * Session lifecycle — connect / close, converting the throwing SDK calls into `Result<T>`.\n * @packageDocumentation\n */\n\nimport { type Result, captureAsyncResult, fail, succeed } from '@fgv/ts-utils';\n\nimport { type IConnectMcpSessionParams, type IMcpServerInfo, type IMcpSession } from './model';\nimport { type ISdkClient, makeClient } from './sdk';\nimport { McpTransport } from './transports';\n\n/** Default client name advertised during the initialize handshake. */\nconst DEFAULT_CLIENT_NAME: string = '@fgv/ts-extras-mcp';\n/**\n * Default client version advertised during the initialize handshake.\n *\n * @remarks\n * Keep in sync with this package's `package.json` version on each release. It is informational\n * only — MCP servers use it for logging/telemetry, not for behavior — so a drift is low-impact,\n * but it should be bumped alongside the lockstep version. (Reading it from `package.json` at\n * runtime is avoided to keep the bundle free of a JSON import / `require` of the manifest.)\n */\nconst DEFAULT_CLIENT_VERSION: string = '5.1.0';\n\n/**\n * Concrete session handle. Packlet-internal — carries the live SDK client that the operations\n * layer recovers via {@link McpSession.fromHandle}. Not exported from the package barrel.\n * @internal\n */\nexport class McpSession implements IMcpSession {\n  public readonly clientName: string;\n  public readonly clientVersion: string;\n  public readonly serverInfo: IMcpServerInfo | undefined;\n  /** The live SDK client. */\n  public readonly client: ISdkClient;\n\n  public constructor(\n    client: ISdkClient,\n    clientName: string,\n    clientVersion: string,\n    serverInfo: IMcpServerInfo | undefined\n  ) {\n    this.client = client;\n    this.clientName = clientName;\n    this.clientVersion = clientVersion;\n    this.serverInfo = serverInfo;\n  }\n\n  /**\n   * Narrows a public {@link IMcpSession} handle back to the concrete {@link McpSession}. Fails\n   * loudly when handed a foreign object that did not originate from {@link connectMcpSession}.\n   */\n  public static fromHandle(handle: IMcpSession): Result<McpSession> {\n    if (handle instanceof McpSession) {\n      return succeed(handle);\n    }\n    return fail('invalid MCP session: expected a handle from connectMcpSession');\n  }\n}\n\n/**\n * Connects to an MCP server over the given transport and performs the initialize handshake.\n *\n * @param params - Transport plus optional client identity and logger.\n * @returns `Success` with an opaque {@link IMcpSession}, or `Failure` if the transport handle is\n * foreign or the connection/handshake fails.\n * @public\n */\nexport async function connectMcpSession(params: IConnectMcpSessionParams): Promise<Result<IMcpSession>> {\n  const { transport, clientName, clientVersion, logger } = params;\n\n  const transportResult = McpTransport.fromHandle(transport);\n  if (transportResult.isFailure()) {\n    return fail(`connectMcpSession: ${transportResult.message}`);\n  }\n\n  const name = clientName ?? DEFAULT_CLIENT_NAME;\n  const version = clientVersion ?? DEFAULT_CLIENT_VERSION;\n  const client = makeClient(name, version);\n\n  logger?.info(\n    `mcp: connecting (client ${name}@${version}, transport ${transportResult.value.transportKind})`\n  );\n\n  return captureAsyncResult(() => client.connect(transportResult.value.sdkTransport))\n    .onSuccess(() => {\n      const raw = client.getServerVersion();\n      const serverInfo: IMcpServerInfo | undefined =\n        raw !== undefined ? { name: raw.name, version: raw.version } : undefined;\n      logger?.info(\n        serverInfo !== undefined\n          ? `mcp: connected to server ${serverInfo.name}@${serverInfo.version}`\n          : 'mcp: connected (server did not report identity)'\n      );\n      return succeed<IMcpSession>(new McpSession(client, name, version, serverInfo));\n    })\n    .withErrorFormat((msg) => `connectMcpSession: ${msg}`);\n}\n\n/**\n * Closes an MCP session, tearing down the transport (and any spawned subprocess).\n *\n * @param session - A session from {@link connectMcpSession}.\n * @returns `Success(true)`, or `Failure` if the handle is foreign or the close call throws.\n * @public\n */\nexport async function closeMcpSession(session: IMcpSession): Promise<Result<true>> {\n  const sessionResult = McpSession.fromHandle(session);\n  if (sessionResult.isFailure()) {\n    return fail(`closeMcpSession: ${sessionResult.message}`);\n  }\n  return captureAsyncResult(() => sessionResult.value.client.close())\n    .onSuccess(() => succeed(true as const))\n    .withErrorFormat((msg) => `closeMcpSession: ${msg}`);\n}\n"]}

package/dist/packlets/mcp/transports.js

@@ -0,0 +1,96 @@
+/*
+ * 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.
+ */
+/**
+ * Transport factories — convert the throwing SDK transport constructors into `Result<T>`.
+ * @packageDocumentation
+ */
+import { captureResult, fail, succeed } from '@fgv/ts-utils';
+import { makeHttpTransport, makeStdioTransport } from './sdk';
+/**
+ * Concrete transport handle. Packlet-internal — carries the SDK transport that
+ * {@link McpTransport.fromHandle} recovers inside {@link connectMcpSession}. Not exported from
+ * the package barrel, so it does not appear in the public API surface.
+ * @internal
+ */
+export class McpTransport {
+    constructor(transportKind, sdkTransport) {
+        this.transportKind = transportKind;
+        this.sdkTransport = sdkTransport;
+    }
+    /**
+     * Narrows a public {@link IMcpTransport} handle back to the concrete {@link McpTransport}.
+     * Fails loudly when handed a foreign object that did not originate from one of this
+     * package's transport factories.
+     */
+    static fromHandle(handle) {
+        if (handle instanceof McpTransport) {
+            return succeed(handle);
+        }
+        return fail('invalid MCP transport: expected a handle from createStdioTransport / createHttpTransport');
+    }
+}
+/**
+ * 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 function createStdioTransport(params) {
+    if (params.command.trim().length === 0) {
+        return fail('createStdioTransport: command must be a non-empty string');
+    }
+    return captureResult(() => makeStdioTransport({
+        command: params.command,
+        args: params.args,
+        env: params.env,
+        cwd: params.cwd
+    }))
+        .onSuccess((sdkTransport) => succeed(new McpTransport('stdio', sdkTransport)))
+        .withErrorFormat((msg) => `createStdioTransport: ${msg}`);
+}
+/**
+ * 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 function createHttpTransport(params) {
+    return captureResult(() => new URL(params.url))
+        .withErrorFormat(() => `invalid url '${params.url}'`)
+        .onSuccess((url) => {
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            return fail(`url must use http or https protocol (got '${url.protocol}')`);
+        }
+        return captureResult(() => makeHttpTransport(url, params.headers)).onSuccess((sdkTransport) => succeed(new McpTransport('http', sdkTransport)));
+    })
+        .withErrorFormat((msg) => `createHttpTransport: ${msg}`);
+}
+//# sourceMappingURL=transports.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transports.js","sourceRoot":"","sources":["../../../src/packlets/mcp/transports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;GAGG;AAEH,OAAO,EAAe,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG1E,OAAO,EAAsB,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAElF;;;;;GAKG;AACH,MAAM,OAAO,YAAY;IAKvB,YAAmB,aAA+B,EAAE,YAA2B;QAC7E,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,UAAU,CAAC,MAAqB;QAC5C,IAAI,MAAM,YAAY,YAAY,EAAE,CAAC;YACnC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,IAAI,CAAC,0FAA0F,CAAC,CAAC;IAC1G,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAgC;IACnE,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvC,OAAO,IAAI,CAAC,0DAA0D,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,aAAa,CAAC,GAAG,EAAE,CACxB,kBAAkB,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,GAAG,EAAE,MAAM,CAAC,GAAG;KAChB,CAAC,CACH;SACE,SAAS,CAAC,CAAC,YAAY,EAAE,EAAE,CAAC,OAAO,CAAgB,IAAI,YAAY,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;SAC5F,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,yBAAyB,GAAG,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA+B;IACjE,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;SAC5C,eAAe,CAAC,GAAG,EAAE,CAAC,gBAAgB,MAAM,CAAC,GAAG,GAAG,CAAC;SACpD,SAAS,CAAC,CAAC,GAAG,EAAyB,EAAE;QACxC,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC1D,OAAO,IAAI,CAAC,6CAA6C,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC;QAC7E,CAAC;QACD,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,YAAY,EAAE,EAAE,CAC5F,OAAO,CAAgB,IAAI,YAAY,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAC/D,CAAC;IACJ,CAAC,CAAC;SACD,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,wBAAwB,GAAG,EAAE,CAAC,CAAC;AAC7D,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 * Transport factories — convert the throwing SDK transport constructors into `Result<T>`.\n * @packageDocumentation\n */\n\nimport { type Result, captureResult, fail, succeed } from '@fgv/ts-utils';\n\nimport { type IMcpHttpTransportParams, type IMcpStdioTransportParams, type IMcpTransport } from './model';\nimport { type ISdkTransport, makeHttpTransport, makeStdioTransport } from './sdk';\n\n/**\n * Concrete transport handle. Packlet-internal — carries the SDK transport that\n * {@link McpTransport.fromHandle} recovers inside {@link connectMcpSession}. Not exported from\n * the package barrel, so it does not appear in the public API surface.\n * @internal\n */\nexport class McpTransport implements IMcpTransport {\n  public readonly transportKind: 'stdio' | 'http';\n  /** The wrapped SDK transport. */\n  public readonly sdkTransport: ISdkTransport;\n\n  public constructor(transportKind: 'stdio' | 'http', sdkTransport: ISdkTransport) {\n    this.transportKind = transportKind;\n    this.sdkTransport = sdkTransport;\n  }\n\n  /**\n   * Narrows a public {@link IMcpTransport} handle back to the concrete {@link McpTransport}.\n   * Fails loudly when handed a foreign object that did not originate from one of this\n   * package's transport factories.\n   */\n  public static fromHandle(handle: IMcpTransport): Result<McpTransport> {\n    if (handle instanceof McpTransport) {\n      return succeed(handle);\n    }\n    return fail('invalid MCP transport: expected a handle from createStdioTransport / createHttpTransport');\n  }\n}\n\n/**\n * Creates a stdio MCP transport that speaks MCP over the stdin/stdout of a spawned subprocess.\n *\n * @remarks\n * **Security — trust boundary.** The transport spawns `params.command` (with `params.args`) as a\n * child process. Never source the command or arguments from untrusted input; treat them with the\n * same care as any shell-out. See the package README's security note.\n *\n * @param params - The command, arguments, environment, and working directory.\n * @returns `Success` with an opaque transport handle, or `Failure` if the SDK constructor throws\n * (e.g. an empty command).\n * @public\n */\nexport function createStdioTransport(params: IMcpStdioTransportParams): Result<IMcpTransport> {\n  if (params.command.trim().length === 0) {\n    return fail('createStdioTransport: command must be a non-empty string');\n  }\n  return captureResult(() =>\n    makeStdioTransport({\n      command: params.command,\n      args: params.args,\n      env: params.env,\n      cwd: params.cwd\n    })\n  )\n    .onSuccess((sdkTransport) => succeed<IMcpTransport>(new McpTransport('stdio', sdkTransport)))\n    .withErrorFormat((msg) => `createStdioTransport: ${msg}`);\n}\n\n/**\n * Creates a Streamable-HTTP MCP transport for the given endpoint URL.\n *\n * @param params - The endpoint URL and optional static headers.\n * @returns `Success` with an opaque transport handle, or `Failure` if the URL is invalid or the\n * SDK constructor throws.\n * @public\n */\nexport function createHttpTransport(params: IMcpHttpTransportParams): Result<IMcpTransport> {\n  return captureResult(() => new URL(params.url))\n    .withErrorFormat(() => `invalid url '${params.url}'`)\n    .onSuccess((url): Result<IMcpTransport> => {\n      if (url.protocol !== 'http:' && url.protocol !== 'https:') {\n        return fail(`url must use http or https protocol (got '${url.protocol}')`);\n      }\n      return captureResult(() => makeHttpTransport(url, params.headers)).onSuccess((sdkTransport) =>\n        succeed<IMcpTransport>(new McpTransport('http', sdkTransport))\n      );\n    })\n    .withErrorFormat((msg) => `createHttpTransport: ${msg}`);\n}\n"]}

package/dist/test/unit/endToEnd.test.js

@@ -0,0 +1,220 @@
+/*
+ * 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.
+ */
+/**
+ * End-to-end verification against a REAL in-memory MCP server (the SDK's `Server` +
+ * `InMemoryTransport.createLinkedPair()`) — NOT a mocked SDK. This is the durable proof that the
+ * brief's two load-bearing constraints actually flow through the full stack: the real SDK `Client`,
+ * the real initialize handshake, the real `listTools`/`callTool` round-trips, the `sdk.ts`
+ * projection casts, and `adaptMcpTools`' `JsonSchema.fromJson` gate. It is the class of gap that
+ * 100%-line-coverage of a mocked seam cannot catch (e.g. a projection-shape mismatch in `sdk.ts`).
+ *
+ * The fixture server advertises a MIX of tools: two adaptable, and one for each JSON Schema feature
+ * `JsonSchema.fromJson` rejects ($ref, oneOf, anyOf, pattern, union `type[]`).
+ */
+import '@fgv/ts-utils-jest';
+import { Logging } from '@fgv/ts-utils';
+// Real MCP SDK server side — exercised over an in-process linked transport pair. Subpath imports
+// resolve via the tsconfig `paths` mapping (the same seam the package's sdk.ts uses).
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { adaptMcpTools, callMcpTool, closeMcpSession, connectMcpSession, listMcpTools } from '../../packlets/mcp';
+// Internal: the opaque-handle class. The package exposes only stdio/http transport factories, so a
+// real in-process e2e (which must inject the SDK's InMemoryTransport) wraps it here. Tests may
+// import internal modules directly (TESTING_GUIDELINES § Testing Internal Code).
+// eslint-disable-next-line @rushstack/packlets/mechanics
+import { McpTransport } from '../../packlets/mcp/transports';
+// ---------------------------------------------------------------------------
+// Fixture server — a real SDK Server advertising a mix of adaptable + un-adaptable tools.
+// ---------------------------------------------------------------------------
+/** The two adaptable tools (in the supported JSON Schema subset). */
+const ADAPTABLE_TOOLS = [
+    {
+        name: 'echo',
+        description: 'Echoes the supplied message back.',
+        inputSchema: {
+            type: 'object',
+            properties: { msg: { type: 'string', description: 'message to echo' } },
+            required: ['msg']
+        }
+    },
+    {
+        name: 'ping',
+        description: 'Health check with no required args.',
+        inputSchema: { type: 'object', properties: {} }
+    }
+];
+/**
+ * One tool per JSON Schema feature `JsonSchema.fromJson` rejects. Each carries the forbidden
+ * keyword NESTED inside a property (the real-world shape: the top-level inputSchema is a valid
+ * `type: 'object'`, so the MCP SDK's own result validation lets it through, and the rejection
+ * happens in `adaptMcpTools` exactly as a real server would surface it).
+ */
+const UNADAPTABLE_TOOLS = [
+    {
+        name: 'ref_tool',
+        inputSchema: { type: 'object', properties: { x: { $ref: '#/$defs/Foo' } } }
+    },
+    {
+        name: 'oneof_tool',
+        inputSchema: { type: 'object', properties: { x: { oneOf: [{ type: 'string' }, { type: 'number' }] } } }
+    },
+    {
+        name: 'anyof_tool',
+        inputSchema: { type: 'object', properties: { x: { anyOf: [{ type: 'string' }, { type: 'number' }] } } }
+    },
+    {
+        name: 'pattern_tool',
+        inputSchema: { type: 'object', properties: { code: { type: 'string', pattern: '^[A-Z]+$' } } }
+    },
+    {
+        name: 'union_tool',
+        inputSchema: { type: 'object', properties: { x: { type: ['string', 'null'] } } }
+    }
+];
+const ALL_TOOLS = [...ADAPTABLE_TOOLS, ...UNADAPTABLE_TOOLS];
+/** Builds and connects a real in-memory MCP server; returns its server-side handle for teardown. */
+async function startFixtureServer() {
+    const server = new Server({ name: 'fixture-mcp-server', version: '0.0.1' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: ALL_TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (name === 'echo') {
+            return { content: [{ type: 'text', text: `echo: ${JSON.stringify(args)}` }] };
+        }
+        if (name === 'ping') {
+            return { content: [{ type: 'text', text: 'pong' }] };
+        }
+        return { content: [{ type: 'text', text: `unknown tool: ${name}` }], isError: true };
+    });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await server.connect(serverTransport);
+    return { server, clientTransport };
+}
+// ---------------------------------------------------------------------------
+// End-to-end suite
+// ---------------------------------------------------------------------------
+describe('@fgv/ts-extras-mcp end-to-end against a real in-memory MCP server', () => {
+    let server;
+    let session;
+    beforeEach(async () => {
+        const fixture = await startFixtureServer();
+        server = fixture.server;
+        // Wrap the SDK in-memory client transport in the package's opaque handle, then connect through
+        // the PUBLIC connectMcpSession (real Client + real initialize handshake). On a connect failure,
+        // tear the fixture server down before throwing so a failed handshake can't leak open handles.
+        const transport = new McpTransport('http', fixture.clientTransport);
+        const connectResult = await connectMcpSession({ transport, clientName: 'e2e', clientVersion: '0.0.0' });
+        if (connectResult.isFailure()) {
+            await server.close();
+            throw new Error(`fixture connect failed: ${connectResult.message}`);
+        }
+        session = connectResult.value;
+    });
+    afterEach(async () => {
+        // Assert teardown succeeds — a regression in close/transport would otherwise pass silently.
+        // `server.close()` runs in `finally` so the fixture is always torn down even if the assertion
+        // throws (otherwise a failed close would leak handles and make later tests flaky).
+        try {
+            expect(await closeMcpSession(session)).toSucceedWith(true);
+        }
+        finally {
+            await server.close();
+        }
+    });
+    test('the initialize handshake reports the real server identity', () => {
+        expect(session.serverInfo).toEqual({ name: 'fixture-mcp-server', version: '0.0.1' });
+    });
+    test('listMcpTools returns the full catalog over the real transport', async () => {
+        expect(await listMcpTools(session)).toSucceedAndSatisfy((tools) => {
+            expect(tools.map((t) => t.name).sort()).toEqual(['anyof_tool', 'echo', 'oneof_tool', 'pattern_tool', 'ping', 'ref_tool', 'union_tool'].sort());
+        });
+    });
+    test('callMcpTool round-trips a real tool result, and maps isError to Failure', async () => {
+        expect(await callMcpTool(session, 'echo', { msg: 'hi' })).toSucceedWith({
+            content: 'echo: {"msg":"hi"}'
+        });
+        expect(await callMcpTool(session, 'nope', {})).toFailWith(/unknown tool: nope/);
+    });
+    // =========================================================================
+    // CONSTRAINT 1 — graceful degradation with NOISY, schema-bearing warnings.
+    // =========================================================================
+    describe('Constraint 1 — adaptMcpTools graceful + NOISY degradation', () => {
+        test('excludes EVERY un-adaptable tool from `tools`, surfaces each on `skipped`, warns with the raw schema', async () => {
+            const logger = new Logging.InMemoryLogger('all');
+            const expectedReasonFragment = {
+                ref_tool: /\$ref/,
+                oneof_tool: /oneOf/,
+                anyof_tool: /anyOf/,
+                pattern_tool: /pattern/,
+                union_tool: /union 'type'/
+            };
+            expect(await adaptMcpTools(session, { logger })).toSucceedAndSatisfy((result) => {
+                // (a) Only the adaptable tools are offered to the model; none of the rejected ones leak.
+                expect(result.tools.map((t) => t.config.name).sort()).toEqual(['echo', 'ping']);
+                const offeredNames = new Set(result.tools.map((t) => t.config.name));
+                for (const t of UNADAPTABLE_TOOLS) {
+                    expect(offeredNames.has(t.name)).toBe(false);
+                }
+                // (b) Each un-adaptable tool is surfaced structurally with name + JSON-pointer reason + the
+                //     RAW failing schema (verbatim, so the subset can be widened later).
+                expect(result.skipped).toHaveLength(UNADAPTABLE_TOOLS.length);
+                const skippedByName = new Map(result.skipped.map((s) => [s.name, s]));
+                for (const tool of UNADAPTABLE_TOOLS) {
+                    const skipped = skippedByName.get(tool.name);
+                    expect(skipped).toBeDefined();
+                    // JSON-pointer path into the offending node.
+                    expect(skipped === null || skipped === void 0 ? void 0 : skipped.reason).toMatch(/#\/properties\//);
+                    expect(skipped === null || skipped === void 0 ? void 0 : skipped.reason).toMatch(expectedReasonFragment[tool.name]);
+                    // The RAW failing schema, verbatim.
+                    expect(skipped === null || skipped === void 0 ? void 0 : skipped.schema).toEqual(tool.inputSchema);
+                }
+            });
+            // (c) A NOISY warning per skip that INCLUDES the raw failing schema text + the reason. The
+            //     schema-in-the-warning is the whole "so we can extend fromJson later" requirement — a
+            //     warn WITHOUT the schema would fail this assertion.
+            const warned = logger.logged.join('\n');
+            for (const tool of UNADAPTABLE_TOOLS) {
+                expect(warned).toContain(`skipping tool '${tool.name}'`);
+                // The raw schema, serialized exactly as adaptMcpTools emits it, must appear in the warn.
+                expect(warned).toContain(JSON.stringify(tool.inputSchema));
+            }
+            // And the reason fragments are present in the warnings too.
+            expect(warned).toMatch(/\$ref/);
+            expect(warned).toMatch(/union 'type'/);
+        });
+        test('an adapted tool executes end-to-end against the real server', async () => {
+            // Result-matcher-driven: extract the adapted `echo` tool inside the success satisfier (where
+            // its presence is asserted), then drive its execute callback — which round-trips through
+            // callMcpTool to the real server — with another matcher.
+            let echoExecute;
+            expect(await adaptMcpTools(session)).toSucceedAndSatisfy((result) => {
+                const echo = result.tools.find((t) => t.config.name === 'echo');
+                expect(echo).toBeDefined();
+                echoExecute = echo === null || echo === void 0 ? void 0 : echo.execute;
+            });
+            expect(echoExecute).toBeDefined();
+            expect(await (echoExecute === null || echoExecute === void 0 ? void 0 : echoExecute({ msg: 'roundtrip' }))).toSucceedWith('echo: {"msg":"roundtrip"}');
+        });
+    });
+});
+//# sourceMappingURL=endToEnd.test.js.map

package/dist/test/unit/endToEnd.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endToEnd.test.js","sourceRoot":"","sources":["../../../src/test/unit/endToEnd.test.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 * End-to-end verification against a REAL in-memory MCP server (the SDK's `Server` +\n * `InMemoryTransport.createLinkedPair()`) — NOT a mocked SDK. This is the durable proof that the\n * brief's two load-bearing constraints actually flow through the full stack: the real SDK `Client`,\n * the real initialize handshake, the real `listTools`/`callTool` round-trips, the `sdk.ts`\n * projection casts, and `adaptMcpTools`' `JsonSchema.fromJson` gate. It is the class of gap that\n * 100%-line-coverage of a mocked seam cannot catch (e.g. a projection-shape mismatch in `sdk.ts`).\n *\n * The fixture server advertises a MIX of tools: two adaptable, and one for each JSON Schema feature\n * `JsonSchema.fromJson` rejects ($ref, oneOf, anyOf, pattern, union `type[]`).\n */\n\nimport '@fgv/ts-utils-jest';\nimport { Logging, type Result } from '@fgv/ts-utils';\n\n// Real MCP SDK server side — exercised over an in-process linked transport pair. Subpath imports\n// resolve via the tsconfig `paths` mapping (the same seam the package's sdk.ts uses).\nimport { Server } from '@modelcontextprotocol/sdk/server/index.js';\nimport { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';\nimport { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';\n\nimport {\n  type IMcpSession,\n  adaptMcpTools,\n  callMcpTool,\n  closeMcpSession,\n  connectMcpSession,\n  listMcpTools\n} from '../../packlets/mcp';\n// Internal: the opaque-handle class. The package exposes only stdio/http transport factories, so a\n// real in-process e2e (which must inject the SDK's InMemoryTransport) wraps it here. Tests may\n// import internal modules directly (TESTING_GUIDELINES § Testing Internal Code).\n// eslint-disable-next-line @rushstack/packlets/mechanics\nimport { McpTransport } from '../../packlets/mcp/transports';\n\n// ---------------------------------------------------------------------------\n// Fixture server — a real SDK Server advertising a mix of adaptable + un-adaptable tools.\n// ---------------------------------------------------------------------------\n\n/** The two adaptable tools (in the supported JSON Schema subset). */\nconst ADAPTABLE_TOOLS = [\n  {\n    name: 'echo',\n    description: 'Echoes the supplied message back.',\n    inputSchema: {\n      type: 'object',\n      properties: { msg: { type: 'string', description: 'message to echo' } },\n      required: ['msg']\n    }\n  },\n  {\n    name: 'ping',\n    description: 'Health check with no required args.',\n    inputSchema: { type: 'object', properties: {} }\n  }\n];\n\n/**\n * One tool per JSON Schema feature `JsonSchema.fromJson` rejects. Each carries the forbidden\n * keyword NESTED inside a property (the real-world shape: the top-level inputSchema is a valid\n * `type: 'object'`, so the MCP SDK's own result validation lets it through, and the rejection\n * happens in `adaptMcpTools` exactly as a real server would surface it).\n */\nconst UNADAPTABLE_TOOLS = [\n  {\n    name: 'ref_tool',\n    inputSchema: { type: 'object', properties: { x: { $ref: '#/$defs/Foo' } } }\n  },\n  {\n    name: 'oneof_tool',\n    inputSchema: { type: 'object', properties: { x: { oneOf: [{ type: 'string' }, { type: 'number' }] } } }\n  },\n  {\n    name: 'anyof_tool',\n    inputSchema: { type: 'object', properties: { x: { anyOf: [{ type: 'string' }, { type: 'number' }] } } }\n  },\n  {\n    name: 'pattern_tool',\n    inputSchema: { type: 'object', properties: { code: { type: 'string', pattern: '^[A-Z]+$' } } }\n  },\n  {\n    name: 'union_tool',\n    inputSchema: { type: 'object', properties: { x: { type: ['string', 'null'] } } }\n  }\n];\n\nconst ALL_TOOLS = [...ADAPTABLE_TOOLS, ...UNADAPTABLE_TOOLS];\n\n/** Builds and connects a real in-memory MCP server; returns its server-side handle for teardown. */\nasync function startFixtureServer(): Promise<{ server: Server; clientTransport: InMemoryTransport }> {\n  const server = new Server(\n    { name: 'fixture-mcp-server', version: '0.0.1' },\n    { capabilities: { tools: {} } }\n  );\n\n  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: ALL_TOOLS }));\n\n  server.setRequestHandler(CallToolRequestSchema, async (request) => {\n    const { name, arguments: args } = request.params;\n    if (name === 'echo') {\n      return { content: [{ type: 'text', text: `echo: ${JSON.stringify(args)}` }] };\n    }\n    if (name === 'ping') {\n      return { content: [{ type: 'text', text: 'pong' }] };\n    }\n    return { content: [{ type: 'text', text: `unknown tool: ${name}` }], isError: true };\n  });\n\n  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();\n  await server.connect(serverTransport);\n  return { server, clientTransport };\n}\n\n// ---------------------------------------------------------------------------\n// End-to-end suite\n// ---------------------------------------------------------------------------\n\ndescribe('@fgv/ts-extras-mcp end-to-end against a real in-memory MCP server', () => {\n  let server: Server;\n  let session: IMcpSession;\n\n  beforeEach(async () => {\n    const fixture = await startFixtureServer();\n    server = fixture.server;\n    // Wrap the SDK in-memory client transport in the package's opaque handle, then connect through\n    // the PUBLIC connectMcpSession (real Client + real initialize handshake). On a connect failure,\n    // tear the fixture server down before throwing so a failed handshake can't leak open handles.\n    const transport = new McpTransport('http', fixture.clientTransport);\n    const connectResult = await connectMcpSession({ transport, clientName: 'e2e', clientVersion: '0.0.0' });\n    if (connectResult.isFailure()) {\n      await server.close();\n      throw new Error(`fixture connect failed: ${connectResult.message}`);\n    }\n    session = connectResult.value;\n  });\n\n  afterEach(async () => {\n    // Assert teardown succeeds — a regression in close/transport would otherwise pass silently.\n    // `server.close()` runs in `finally` so the fixture is always torn down even if the assertion\n    // throws (otherwise a failed close would leak handles and make later tests flaky).\n    try {\n      expect(await closeMcpSession(session)).toSucceedWith(true);\n    } finally {\n      await server.close();\n    }\n  });\n\n  test('the initialize handshake reports the real server identity', () => {\n    expect(session.serverInfo).toEqual({ name: 'fixture-mcp-server', version: '0.0.1' });\n  });\n\n  test('listMcpTools returns the full catalog over the real transport', async () => {\n    expect(await listMcpTools(session)).toSucceedAndSatisfy((tools) => {\n      expect(tools.map((t) => t.name).sort()).toEqual(\n        ['anyof_tool', 'echo', 'oneof_tool', 'pattern_tool', 'ping', 'ref_tool', 'union_tool'].sort()\n      );\n    });\n  });\n\n  test('callMcpTool round-trips a real tool result, and maps isError to Failure', async () => {\n    expect(await callMcpTool(session, 'echo', { msg: 'hi' })).toSucceedWith({\n      content: 'echo: {\"msg\":\"hi\"}'\n    });\n    expect(await callMcpTool(session, 'nope', {})).toFailWith(/unknown tool: nope/);\n  });\n\n  // =========================================================================\n  // CONSTRAINT 1 — graceful degradation with NOISY, schema-bearing warnings.\n  // =========================================================================\n  describe('Constraint 1 — adaptMcpTools graceful + NOISY degradation', () => {\n    test('excludes EVERY un-adaptable tool from `tools`, surfaces each on `skipped`, warns with the raw schema', async () => {\n      const logger = new Logging.InMemoryLogger('all');\n      const expectedReasonFragment: Record<string, RegExp> = {\n        ref_tool: /\\$ref/,\n        oneof_tool: /oneOf/,\n        anyof_tool: /anyOf/,\n        pattern_tool: /pattern/,\n        union_tool: /union 'type'/\n      };\n\n      expect(await adaptMcpTools(session, { logger })).toSucceedAndSatisfy((result) => {\n        // (a) Only the adaptable tools are offered to the model; none of the rejected ones leak.\n        expect(result.tools.map((t) => t.config.name).sort()).toEqual(['echo', 'ping']);\n        const offeredNames = new Set(result.tools.map((t) => t.config.name));\n        for (const t of UNADAPTABLE_TOOLS) {\n          expect(offeredNames.has(t.name)).toBe(false);\n        }\n\n        // (b) Each un-adaptable tool is surfaced structurally with name + JSON-pointer reason + the\n        //     RAW failing schema (verbatim, so the subset can be widened later).\n        expect(result.skipped).toHaveLength(UNADAPTABLE_TOOLS.length);\n        const skippedByName = new Map(result.skipped.map((s) => [s.name, s]));\n        for (const tool of UNADAPTABLE_TOOLS) {\n          const skipped = skippedByName.get(tool.name);\n          expect(skipped).toBeDefined();\n          // JSON-pointer path into the offending node.\n          expect(skipped?.reason).toMatch(/#\\/properties\\//);\n          expect(skipped?.reason).toMatch(expectedReasonFragment[tool.name]);\n          // The RAW failing schema, verbatim.\n          expect(skipped?.schema).toEqual(tool.inputSchema);\n        }\n      });\n\n      // (c) A NOISY warning per skip that INCLUDES the raw failing schema text + the reason. The\n      //     schema-in-the-warning is the whole \"so we can extend fromJson later\" requirement — a\n      //     warn WITHOUT the schema would fail this assertion.\n      const warned = logger.logged.join('\\n');\n      for (const tool of UNADAPTABLE_TOOLS) {\n        expect(warned).toContain(`skipping tool '${tool.name}'`);\n        // The raw schema, serialized exactly as adaptMcpTools emits it, must appear in the warn.\n        expect(warned).toContain(JSON.stringify(tool.inputSchema));\n      }\n      // And the reason fragments are present in the warnings too.\n      expect(warned).toMatch(/\\$ref/);\n      expect(warned).toMatch(/union 'type'/);\n    });\n\n    test('an adapted tool executes end-to-end against the real server', async () => {\n      // Result-matcher-driven: extract the adapted `echo` tool inside the success satisfier (where\n      // its presence is asserted), then drive its execute callback — which round-trips through\n      // callMcpTool to the real server — with another matcher.\n      let echoExecute: ((args: unknown) => Promise<Result<unknown>>) | undefined;\n      expect(await adaptMcpTools(session)).toSucceedAndSatisfy((result) => {\n        const echo = result.tools.find((t) => t.config.name === 'echo');\n        expect(echo).toBeDefined();\n        echoExecute = echo?.execute;\n      });\n      expect(echoExecute).toBeDefined();\n      expect(await echoExecute?.({ msg: 'roundtrip' })).toSucceedWith('echo: {\"msg\":\"roundtrip\"}');\n    });\n  });\n});\n"]}

package/dist/test/unit/index.test.js

@@ -0,0 +1,41 @@
+/*
+ * 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.
+ */
+import '@fgv/ts-utils-jest';
+import * as mcp from '../../index';
+describe('@fgv/ts-extras-mcp package barrel', () => {
+    test('re-exports the public boundary primitives', () => {
+        expect(typeof mcp.createStdioTransport).toBe('function');
+        expect(typeof mcp.createHttpTransport).toBe('function');
+        expect(typeof mcp.connectMcpSession).toBe('function');
+        expect(typeof mcp.closeMcpSession).toBe('function');
+        expect(typeof mcp.listMcpTools).toBe('function');
+        expect(typeof mcp.callMcpTool).toBe('function');
+        expect(typeof mcp.adaptMcpTools).toBe('function');
+    });
+    test('the re-exported transport factories are the real (behaving) implementations', () => {
+        // Behavioral signal beyond `typeof`: a renamed-but-still-a-function export would not behave
+        // this way. (The synchronous transport factories validate without touching the SDK/network.)
+        expect(mcp.createStdioTransport({ command: '' })).toFailWith(/command must be a non-empty string/);
+        expect(mcp.createHttpTransport({ url: 'not a url' })).toFailWith(/invalid url/);
+    });
+});
+//# sourceMappingURL=index.test.js.map