@fgv/ts-extras-mcp 5.1.0-34

package/lib/packlets/mcp/sdk.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Opaque transport handle. The concrete value is an SDK `Transport`; consumers of this module
+ * treat it as opaque and only ever hand it back to {@link makeClient}-produced clients.
+ * @internal
+ */
+export type ISdkTransport = object;
+/**
+ * A single content block in an MCP `CallToolResult`. Only `text` blocks carry inline content;
+ * all other block types are projected to a structural summary by the operations layer.
+ * @internal
+ */
+export interface ISdkContentBlock {
+    readonly type: string;
+    readonly text?: string;
+}
+/**
+ * Projection of the SDK's `CallToolResult`.
+ * @internal
+ */
+export interface ISdkCallToolResult {
+    readonly content?: ReadonlyArray<ISdkContentBlock>;
+    readonly isError?: boolean;
+}
+/**
+ * Projection of a single tool descriptor in the SDK's `ListToolsResult`.
+ * @internal
+ */
+export interface ISdkToolDescriptor {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema?: unknown;
+}
+/**
+ * Projection of the SDK's `ListToolsResult` (one page).
+ * @internal
+ */
+export interface ISdkListToolsResult {
+    readonly tools: ReadonlyArray<ISdkToolDescriptor>;
+    readonly nextCursor?: string;
+}
+/**
+ * Server identity returned by the SDK's `getServerVersion()` after the initialize handshake.
+ * @internal
+ */
+export interface ISdkImplementation {
+    readonly name: string;
+    readonly version: string;
+}
+/**
+ * Minimal projection of the SDK `Client` surface the package depends on.
+ * @internal
+ */
+export interface ISdkClient {
+    connect(transport: ISdkTransport): Promise<void>;
+    getServerVersion(): ISdkImplementation | undefined;
+    listTools(params?: {
+        cursor?: string;
+    }): Promise<ISdkListToolsResult>;
+    callTool(params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }): Promise<ISdkCallToolResult>;
+    close(): Promise<void>;
+}
+/**
+ * Parameters for the stdio transport factory.
+ * @internal
+ */
+export interface ISdkStdioParams {
+    readonly command: string;
+    readonly args?: ReadonlyArray<string>;
+    readonly env?: Record<string, string>;
+    readonly cwd?: string;
+}
+/**
+ * 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 declare function makeClient(name: string, version: string): ISdkClient;
+/**
+ * Constructs a stdio transport that spawns the given command as a subprocess.
+ * @internal
+ */
+export declare function makeStdioTransport(params: ISdkStdioParams): ISdkTransport;
+/**
+ * Constructs a Streamable-HTTP transport for the given URL, with optional static headers.
+ * @internal
+ */
+export declare function makeHttpTransport(url: URL, headers?: Record<string, string>): ISdkTransport;
+//# sourceMappingURL=sdk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../../src/packlets/mcp/sdk.ts"],"names":[],"mappings":"AAwCA;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,gBAAgB,IAAI,kBAAkB,GAAG,SAAS,CAAC;IACnD,SAAS,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACtE,QAAQ,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAEpE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAOzE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,aAAa,CAI3F"}

package/lib/packlets/mcp/sdk.js

@@ -0,0 +1,72 @@
+"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 });
+exports.makeClient = makeClient;
+exports.makeStdioTransport = makeStdioTransport;
+exports.makeHttpTransport = makeHttpTransport;
+/**
+ * **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
+ */
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/client/stdio.js");
+const streamableHttp_js_1 = require("@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
+ */
+function makeClient(name, version) {
+    return new index_js_1.Client({ name, version }, { capabilities: {} });
+}
+/**
+ * Constructs a stdio transport that spawns the given command as a subprocess.
+ * @internal
+ */
+function makeStdioTransport(params) {
+    return new stdio_js_1.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
+ */
+function makeHttpTransport(url, headers) {
+    return new streamableHttp_js_1.StreamableHTTPClientTransport(url, {
+        requestInit: headers ? { headers } : undefined
+    });
+}
+//# sourceMappingURL=sdk.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.js","sourceRoot":"","sources":["../../../src/packlets/mcp/sdk.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AAsGH,gCAEC;AAMD,gDAOC;AAMD,8CAIC;AA7HD;;;;;;;;;;;;GAYG;AAEH,wEAAmE;AACnE,wEAAiF;AACjF,0FAAmG;AA+EnG;;;;GAIG;AACH,SAAgB,UAAU,CAAC,IAAY,EAAE,OAAe;IACtD,OAAO,IAAI,iBAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAA0B,CAAC;AACtF,CAAC;AAED;;;GAGG;AACH,SAAgB,kBAAkB,CAAC,MAAuB;IACxD,OAAO,IAAI,+BAAoB,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,SAAgB,iBAAiB,CAAC,GAAQ,EAAE,OAAgC;IAC1E,OAAO,IAAI,iDAA6B,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/lib/packlets/mcp/session.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Session lifecycle — connect / close, converting the throwing SDK calls into `Result<T>`.
+ * @packageDocumentation
+ */
+import { type Result } from '@fgv/ts-utils';
+import { type IConnectMcpSessionParams, type IMcpServerInfo, type IMcpSession } from './model';
+import { type ISdkClient } from './sdk';
+/**
+ * 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 declare class McpSession implements IMcpSession {
+    readonly clientName: string;
+    readonly clientVersion: string;
+    readonly serverInfo: IMcpServerInfo | undefined;
+    /** The live SDK client. */
+    readonly client: ISdkClient;
+    constructor(client: ISdkClient, clientName: string, clientVersion: string, serverInfo: IMcpServerInfo | undefined);
+    /**
+     * 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: IMcpSession): Result<McpSession>;
+}
+/**
+ * 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>>;
+/**
+ * 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>>;
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/packlets/mcp/session.ts"],"names":[],"mappings":"AAsBA;;;GAGG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAqC,MAAM,eAAe,CAAC;AAE/E,OAAO,EAAE,KAAK,wBAAwB,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAC/F,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,OAAO,CAAC;AAgBpD;;;;GAIG;AACH,qBAAa,UAAW,YAAW,WAAW;IAC5C,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,SAAgB,UAAU,EAAE,cAAc,GAAG,SAAS,CAAC;IACvD,2BAA2B;IAC3B,SAAgB,MAAM,EAAE,UAAU,CAAC;gBAGjC,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,cAAc,GAAG,SAAS;IAQxC;;;OAGG;WACW,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC;CAMlE;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CA6BtG;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAQjF"}

package/lib/packlets/mcp/session.js

@@ -0,0 +1,115 @@
+"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 });
+exports.McpSession = void 0;
+exports.connectMcpSession = connectMcpSession;
+exports.closeMcpSession = closeMcpSession;
+/**
+ * Session lifecycle — connect / close, converting the throwing SDK calls into `Result<T>`.
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const sdk_1 = require("./sdk");
+const transports_1 = require("./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
+ */
+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 (0, ts_utils_1.succeed)(handle);
+        }
+        return (0, ts_utils_1.fail)('invalid MCP session: expected a handle from connectMcpSession');
+    }
+}
+exports.McpSession = McpSession;
+/**
+ * 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
+ */
+async function connectMcpSession(params) {
+    const { transport, clientName, clientVersion, logger } = params;
+    const transportResult = transports_1.McpTransport.fromHandle(transport);
+    if (transportResult.isFailure()) {
+        return (0, ts_utils_1.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 = (0, sdk_1.makeClient)(name, version);
+    logger === null || logger === void 0 ? void 0 : logger.info(`mcp: connecting (client ${name}@${version}, transport ${transportResult.value.transportKind})`);
+    return (0, ts_utils_1.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 (0, ts_utils_1.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
+ */
+async function closeMcpSession(session) {
+    const sessionResult = McpSession.fromHandle(session);
+    if (sessionResult.isFailure()) {
+        return (0, ts_utils_1.fail)(`closeMcpSession: ${sessionResult.message}`);
+    }
+    return (0, ts_utils_1.captureAsyncResult)(() => sessionResult.value.client.close())
+        .onSuccess(() => (0, ts_utils_1.succeed)(true))
+        .withErrorFormat((msg) => `closeMcpSession: ${msg}`);
+}
+//# sourceMappingURL=session.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/packlets/mcp/session.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAsEH,8CA6BC;AASD,0CAQC;AAlHD;;;GAGG;AAEH,4CAA+E;AAG/E,+BAAoD;AACpD,6CAA4C;AAE5C,sEAAsE;AACtE,MAAM,mBAAmB,GAAW,oBAAoB,CAAC;AACzD;;;;;;;;GAQG;AACH,MAAM,sBAAsB,GAAW,OAAO,CAAC;AAE/C;;;;GAIG;AACH,MAAa,UAAU;IAOrB,YACE,MAAkB,EAClB,UAAkB,EAClB,aAAqB,EACrB,UAAsC;QAEtC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,UAAU,CAAC,MAAmB;QAC1C,IAAI,MAAM,YAAY,UAAU,EAAE,CAAC;YACjC,OAAO,IAAA,kBAAO,EAAC,MAAM,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,IAAA,eAAI,EAAC,+DAA+D,CAAC,CAAC;IAC/E,CAAC;CACF;AA7BD,gCA6BC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,iBAAiB,CAAC,MAAgC;IACtE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAEhE,MAAM,eAAe,GAAG,yBAAY,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IAC3D,IAAI,eAAe,CAAC,SAAS,EAAE,EAAE,CAAC;QAChC,OAAO,IAAA,eAAI,EAAC,sBAAsB,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,MAAM,IAAI,GAAG,UAAU,aAAV,UAAU,cAAV,UAAU,GAAI,mBAAmB,CAAC;IAC/C,MAAM,OAAO,GAAG,aAAa,aAAb,aAAa,cAAb,aAAa,GAAI,sBAAsB,CAAC;IACxD,MAAM,MAAM,GAAG,IAAA,gBAAU,EAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAEzC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,CACV,2BAA2B,IAAI,IAAI,OAAO,eAAe,eAAe,CAAC,KAAK,CAAC,aAAa,GAAG,CAChG,CAAC;IAEF,OAAO,IAAA,6BAAkB,EAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;SAChF,SAAS,CAAC,GAAG,EAAE;QACd,MAAM,GAAG,GAAG,MAAM,CAAC,gBAAgB,EAAE,CAAC;QACtC,MAAM,UAAU,GACd,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3E,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,CACV,UAAU,KAAK,SAAS;YACtB,CAAC,CAAC,4BAA4B,UAAU,CAAC,IAAI,IAAI,UAAU,CAAC,OAAO,EAAE;YACrE,CAAC,CAAC,iDAAiD,CACtD,CAAC;QACF,OAAO,IAAA,kBAAO,EAAc,IAAI,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;IACjF,CAAC,CAAC;SACD,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,sBAAsB,GAAG,EAAE,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,eAAe,CAAC,OAAoB;IACxD,MAAM,aAAa,GAAG,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,aAAa,CAAC,SAAS,EAAE,EAAE,CAAC;QAC9B,OAAO,IAAA,eAAI,EAAC,oBAAoB,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,IAAA,6BAAkB,EAAC,GAAG,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;SAChE,SAAS,CAAC,GAAG,EAAE,CAAC,IAAA,kBAAO,EAAC,IAAa,CAAC,CAAC;SACvC,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,oBAAoB,GAAG,EAAE,CAAC,CAAC;AACzD,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 * 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/lib/packlets/mcp/transports.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Transport factories — convert the throwing SDK transport constructors into `Result<T>`.
+ * @packageDocumentation
+ */
+import { type Result } from '@fgv/ts-utils';
+import { type IMcpHttpTransportParams, type IMcpStdioTransportParams, type IMcpTransport } from './model';
+import { type ISdkTransport } 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 declare class McpTransport implements IMcpTransport {
+    readonly transportKind: 'stdio' | 'http';
+    /** The wrapped SDK transport. */
+    readonly sdkTransport: ISdkTransport;
+    constructor(transportKind: 'stdio' | 'http', sdkTransport: ISdkTransport);
+    /**
+     * 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: IMcpTransport): Result<McpTransport>;
+}
+/**
+ * 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>;
+/**
+ * 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>;
+//# sourceMappingURL=transports.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transports.d.ts","sourceRoot":"","sources":["../../../src/packlets/mcp/transports.ts"],"names":[],"mappings":"AAsBA;;;GAGG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAgC,MAAM,eAAe,CAAC;AAE1E,OAAO,EAAE,KAAK,uBAAuB,EAAE,KAAK,wBAAwB,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAC1G,OAAO,EAAE,KAAK,aAAa,EAAyC,MAAM,OAAO,CAAC;AAElF;;;;;GAKG;AACH,qBAAa,YAAa,YAAW,aAAa;IAChD,SAAgB,aAAa,EAAE,OAAO,GAAG,MAAM,CAAC;IAChD,iCAAiC;IACjC,SAAgB,YAAY,EAAE,aAAa,CAAC;gBAEzB,aAAa,EAAE,OAAO,GAAG,MAAM,EAAE,YAAY,EAAE,aAAa;IAK/E;;;;OAIG;WACW,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC,YAAY,CAAC;CAMtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,wBAAwB,GAAG,MAAM,CAAC,aAAa,CAAC,CAc5F;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,uBAAuB,GAAG,MAAM,CAAC,aAAa,CAAC,CAY1F"}

package/lib/packlets/mcp/transports.js

@@ -0,0 +1,102 @@
+"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 });
+exports.McpTransport = void 0;
+exports.createStdioTransport = createStdioTransport;
+exports.createHttpTransport = createHttpTransport;
+/**
+ * Transport factories — convert the throwing SDK transport constructors into `Result<T>`.
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const sdk_1 = require("./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
+ */
+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 (0, ts_utils_1.succeed)(handle);
+        }
+        return (0, ts_utils_1.fail)('invalid MCP transport: expected a handle from createStdioTransport / createHttpTransport');
+    }
+}
+exports.McpTransport = McpTransport;
+/**
+ * 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
+ */
+function createStdioTransport(params) {
+    if (params.command.trim().length === 0) {
+        return (0, ts_utils_1.fail)('createStdioTransport: command must be a non-empty string');
+    }
+    return (0, ts_utils_1.captureResult)(() => (0, sdk_1.makeStdioTransport)({
+        command: params.command,
+        args: params.args,
+        env: params.env,
+        cwd: params.cwd
+    }))
+        .onSuccess((sdkTransport) => (0, ts_utils_1.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
+ */
+function createHttpTransport(params) {
+    return (0, ts_utils_1.captureResult)(() => new URL(params.url))
+        .withErrorFormat(() => `invalid url '${params.url}'`)
+        .onSuccess((url) => {
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            return (0, ts_utils_1.fail)(`url must use http or https protocol (got '${url.protocol}')`);
+        }
+        return (0, ts_utils_1.captureResult)(() => (0, sdk_1.makeHttpTransport)(url, params.headers)).onSuccess((sdkTransport) => (0, ts_utils_1.succeed)(new McpTransport('http', sdkTransport)));
+    })
+        .withErrorFormat((msg) => `createHttpTransport: ${msg}`);
+}
+//# sourceMappingURL=transports.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transports.js","sourceRoot":"","sources":["../../../src/packlets/mcp/transports.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAsDH,oDAcC;AAUD,kDAYC;AAxFD;;;GAGG;AAEH,4CAA0E;AAG1E,+BAAkF;AAElF;;;;;GAKG;AACH,MAAa,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,IAAA,kBAAO,EAAC,MAAM,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,IAAA,eAAI,EAAC,0FAA0F,CAAC,CAAC;IAC1G,CAAC;CACF;AArBD,oCAqBC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,oBAAoB,CAAC,MAAgC;IACnE,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvC,OAAO,IAAA,eAAI,EAAC,0DAA0D,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,IAAA,wBAAa,EAAC,GAAG,EAAE,CACxB,IAAA,wBAAkB,EAAC;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,IAAA,kBAAO,EAAgB,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,SAAgB,mBAAmB,CAAC,MAA+B;IACjE,OAAO,IAAA,wBAAa,EAAC,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,IAAA,eAAI,EAAC,6CAA6C,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC;QAC7E,CAAC;QACD,OAAO,IAAA,wBAAa,EAAC,GAAG,EAAE,CAAC,IAAA,uBAAiB,EAAC,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,YAAY,EAAE,EAAE,CAC5F,IAAA,kBAAO,EAAgB,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/lib/test/unit/endToEnd.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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';
+//# sourceMappingURL=endToEnd.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"endToEnd.test.d.ts","sourceRoot":"","sources":["../../../src/test/unit/endToEnd.test.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;GAUG;AAEH,OAAO,oBAAoB,CAAC"}