@fgv/ts-extras-mcp 5.1.0-34

package/src/packlets/mcp/sdk.ts

@@ -0,0 +1,148 @@
+/*
+ * 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';
+
+/**
+ * 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 function makeClient(name: string, version: string): ISdkClient {
+  return new Client({ name, version }, { capabilities: {} }) as unknown as ISdkClient;
+}
+
+/**
+ * Constructs a stdio transport that spawns the given command as a subprocess.
+ * @internal
+ */
+export function makeStdioTransport(params: ISdkStdioParams): ISdkTransport {
+  return new StdioClientTransport({
+    command: params.command,
+    args: params.args ? [...params.args] : undefined,
+    env: params.env,
+    cwd: params.cwd
+  }) as unknown as ISdkTransport;
+}
+
+/**
+ * Constructs a Streamable-HTTP transport for the given URL, with optional static headers.
+ * @internal
+ */
+export function makeHttpTransport(url: URL, headers?: Record<string, string>): ISdkTransport {
+  return new StreamableHTTPClientTransport(url, {
+    requestInit: headers ? { headers } : undefined
+  }) as unknown as ISdkTransport;
+}

package/src/packlets/mcp/session.ts

@@ -0,0 +1,137 @@
+/*
+ * 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 { type Result, captureAsyncResult, fail, succeed } from '@fgv/ts-utils';
+
+import { type IConnectMcpSessionParams, type IMcpServerInfo, type IMcpSession } from './model';
+import { type ISdkClient, makeClient } from './sdk';
+import { McpTransport } from './transports';
+
+/** Default client name advertised during the initialize handshake. */
+const DEFAULT_CLIENT_NAME: string = '@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: string = '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 implements IMcpSession {
+  public readonly clientName: string;
+  public readonly clientVersion: string;
+  public readonly serverInfo: IMcpServerInfo | undefined;
+  /** The live SDK client. */
+  public readonly client: ISdkClient;
+
+  public constructor(
+    client: ISdkClient,
+    clientName: string,
+    clientVersion: string,
+    serverInfo: IMcpServerInfo | undefined
+  ) {
+    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}.
+   */
+  public static fromHandle(handle: IMcpSession): Result<McpSession> {
+    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: IConnectMcpSessionParams): Promise<Result<IMcpSession>> {
+  const { transport, clientName, clientVersion, logger } = params;
+
+  const transportResult = McpTransport.fromHandle(transport);
+  if (transportResult.isFailure()) {
+    return fail(`connectMcpSession: ${transportResult.message}`);
+  }
+
+  const name = clientName ?? DEFAULT_CLIENT_NAME;
+  const version = clientVersion ?? DEFAULT_CLIENT_VERSION;
+  const client = makeClient(name, version);
+
+  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: IMcpServerInfo | undefined =
+        raw !== undefined ? { name: raw.name, version: raw.version } : undefined;
+      logger?.info(
+        serverInfo !== undefined
+          ? `mcp: connected to server ${serverInfo.name}@${serverInfo.version}`
+          : 'mcp: connected (server did not report identity)'
+      );
+      return succeed<IMcpSession>(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: IMcpSession): Promise<Result<true>> {
+  const sessionResult = McpSession.fromHandle(session);
+  if (sessionResult.isFailure()) {
+    return fail(`closeMcpSession: ${sessionResult.message}`);
+  }
+  return captureAsyncResult(() => sessionResult.value.client.close())
+    .onSuccess(() => succeed(true as const))
+    .withErrorFormat((msg) => `closeMcpSession: ${msg}`);
+}

package/src/packlets/mcp/transports.ts

@@ -0,0 +1,111 @@
+/*
+ * 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 { type Result, captureResult, fail, succeed } from '@fgv/ts-utils';
+
+import { type IMcpHttpTransportParams, type IMcpStdioTransportParams, type IMcpTransport } from './model';
+import { type ISdkTransport, 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 implements IMcpTransport {
+  public readonly transportKind: 'stdio' | 'http';
+  /** The wrapped SDK transport. */
+  public readonly sdkTransport: ISdkTransport;
+
+  public constructor(transportKind: 'stdio' | 'http', sdkTransport: ISdkTransport) {
+    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.
+   */
+  public static fromHandle(handle: IMcpTransport): Result<McpTransport> {
+    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: IMcpStdioTransportParams): Result<IMcpTransport> {
+  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<IMcpTransport>(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: IMcpHttpTransportParams): Result<IMcpTransport> {
+  return captureResult(() => new URL(params.url))
+    .withErrorFormat(() => `invalid url '${params.url}'`)
+    .onSuccess((url): Result<IMcpTransport> => {
+      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<IMcpTransport>(new McpTransport('http', sdkTransport))
+      );
+    })
+    .withErrorFormat((msg) => `createHttpTransport: ${msg}`);
+}

package/src/test/unit/endToEnd.test.ts

@@ -0,0 +1,254 @@
+/*
+ * 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, type Result } 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 {
+  type IMcpSession,
+  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(): Promise<{ server: Server; clientTransport: InMemoryTransport }> {
+  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: Server;
+  let session: IMcpSession;
+
+  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: Record<string, RegExp> = {
+        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?.reason).toMatch(/#\/properties\//);
+          expect(skipped?.reason).toMatch(expectedReasonFragment[tool.name]);
+          // The RAW failing schema, verbatim.
+          expect(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: ((args: unknown) => Promise<Result<unknown>>) | undefined;
+      expect(await adaptMcpTools(session)).toSucceedAndSatisfy((result) => {
+        const echo = result.tools.find((t) => t.config.name === 'echo');
+        expect(echo).toBeDefined();
+        echoExecute = echo?.execute;
+      });
+      expect(echoExecute).toBeDefined();
+      expect(await echoExecute?.({ msg: 'roundtrip' })).toSucceedWith('echo: {"msg":"roundtrip"}');
+    });
+  });
+});