@sriramadari/mcp-devkit 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,409 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * types.ts — shared types for mcp-devkit.
+ *
+ * We intentionally keep our public surface decoupled from the exact shapes the
+ * MCP SDK exports (those move between minor versions). Where we touch SDK data
+ * we describe only the fields we read, structurally — so the kit keeps working
+ * across a range of `@modelcontextprotocol/sdk` versions.
+ */
+
+/** A single content block returned by a tool / prompt / resource read. */
+interface ContentBlock {
+    type: string;
+    /** Present on `type: "text"` blocks. */
+    text?: string;
+    /** Present on `type: "image"` / `"audio"` blocks. */
+    data?: string;
+    mimeType?: string;
+    [k: string]: unknown;
+}
+/** The result of a `tools/call`, narrowed to the fields we read. */
+interface ToolResult {
+    content: ContentBlock[];
+    /** `true` when the tool reported a (non-protocol) execution error. */
+    isError?: boolean;
+    /** Structured payload, when the tool declares an `outputSchema`. */
+    structuredContent?: unknown;
+    [k: string]: unknown;
+}
+/** A tool descriptor as returned by `tools/list`. */
+interface ToolInfo {
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+    outputSchema?: JsonSchema;
+    annotations?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+/** A resource descriptor as returned by `resources/list`. */
+interface ResourceInfo {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+    [k: string]: unknown;
+}
+/** A prompt descriptor as returned by `prompts/list`. */
+interface PromptInfo {
+    name: string;
+    description?: string;
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+    [k: string]: unknown;
+}
+/**
+ * The minimal subset of JSON Schema we understand for input validation.
+ * Tools in the wild use far more, but this covers the cases worth checking
+ * before a call leaves your test.
+ */
+interface JsonSchema {
+    type?: JsonSchemaType | JsonSchemaType[];
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema | JsonSchema[];
+    required?: string[];
+    enum?: unknown[];
+    const?: unknown;
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    additionalProperties?: boolean | JsonSchema;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    [k: string]: unknown;
+}
+type JsonSchemaType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+/**
+ * What to connect a test client to. Exactly one of `server` | `command` must
+ * be provided.
+ *
+ * - `server`: an already-constructed `McpServer` (or a factory returning one).
+ *   Wired up over an in-process transport — fast, no child process, ideal for
+ *   unit tests of your own server.
+ * - `command` + `args`: a stdio MCP server launched as a child process — what
+ *   you reach for in an end-to-end test or when inspecting a third-party
+ *   server you don't import.
+ */
+type ConnectTarget = {
+    server: McpServer | (() => McpServer | Promise<McpServer>);
+    command?: never;
+} | {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    server?: never;
+};
+interface ConnectOptions {
+    /** Client identity sent in the `initialize` handshake. */
+    clientName?: string;
+    clientVersion?: string;
+    /** Per-request timeout in milliseconds (default 10_000). */
+    timeoutMs?: number;
+}
+
+/**
+ * client.ts — the TestClient: an ergonomic wrapper over the raw SDK Client.
+ *
+ * Everything a test reaches for, with the protocol boilerplate removed:
+ *   - cached `tools()` / `resources()` / `prompts()` listings
+ *   - `hasTool()`, `tool()` lookups
+ *   - `call()` that optionally validates args against the tool's declared
+ *     `inputSchema` *before* sending, so a bad call fails loudly in your test
+ *     instead of silently in the server
+ *   - `readResource()` / `getPrompt()` passthroughs
+ *
+ * Construct one with `createTestClient(target, options)`.
+ */
+
+interface CallOptions {
+    /**
+     * Validate `args` against the tool's `inputSchema` before sending.
+     * Default `true`. Throws a descriptive error if the args don't match.
+     */
+    validate?: boolean;
+    /** Per-call timeout in ms (overrides the connection default). */
+    timeoutMs?: number;
+}
+declare class TestClient {
+    /** The underlying SDK client — escape hatch for anything not wrapped here. */
+    readonly raw: Client;
+    private readonly _close;
+    private readonly defaultTimeoutMs;
+    private _tools?;
+    private _resources?;
+    private _prompts?;
+    /** @internal — use {@link createTestClient}. */
+    constructor(raw: Client, close: () => Promise<void>, defaultTimeoutMs: number);
+    serverInfo(): {
+        name: string;
+        version: string;
+    } | undefined;
+    capabilities(): Record<string, unknown> | undefined;
+    /** List the server's tools (cached after the first call — see {@link refresh}). */
+    tools(): Promise<ToolInfo[]>;
+    toolNames(): Promise<string[]>;
+    hasTool(name: string): Promise<boolean>;
+    tool(name: string): Promise<ToolInfo | undefined>;
+    /**
+     * Call a tool. By default the args are validated against the tool's declared
+     * `inputSchema` first; set `{ validate: false }` to send them as-is (e.g. to
+     * test how the server handles bad input).
+     */
+    call(name: string, args?: Record<string, unknown>, options?: CallOptions): Promise<ToolResult>;
+    resources(): Promise<ResourceInfo[]>;
+    readResource(uri: string): Promise<{
+        contents: Array<{
+            uri: string;
+            text?: string;
+            blob?: string;
+            mimeType?: string;
+        }>;
+    }>;
+    prompts(): Promise<PromptInfo[]>;
+    getPrompt(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    /** Drop cached listings so the next `tools()`/`resources()`/`prompts()` re-fetches. */
+    refresh(): void;
+    /** Liveness check — resolves if the server answers a ping. */
+    ping(): Promise<void>;
+    /** Tear down the connection (and any spawned child process). Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Open a connection to an MCP server and return a ready-to-use {@link TestClient}.
+ *
+ * @example In-process (your own server):
+ * ```ts
+ * const client = await createTestClient({ server: buildMyServer() });
+ * const res = await client.call("search", { q: "mcp" });
+ * await client.close();
+ * ```
+ *
+ * @example Over stdio (any server binary):
+ * ```ts
+ * const client = await createTestClient({ command: "node", args: ["dist/server.js"] });
+ * ```
+ */
+declare function createTestClient(target: ConnectTarget, options?: ConnectOptions): Promise<TestClient>;
+/**
+ * Run `fn` with a connected client and guarantee it's closed afterwards, even
+ * if the test throws. Returns whatever `fn` returns.
+ *
+ * @example
+ * ```ts
+ * await withTestClient({ server }, async (client) => {
+ *   expectToolResult(await client.call("ping")).toSucceed();
+ * });
+ * ```
+ */
+declare function withTestClient<T>(target: ConnectTarget, fn: (client: TestClient) => Promise<T>, options?: ConnectOptions): Promise<T>;
+
+/**
+ * connect.ts — establish a live MCP client connection to a target.
+ *
+ * Two transports, one entry point:
+ *   - in-process (`InMemoryTransport.createLinkedPair`) for an `McpServer` you
+ *     constructed in the same test, and
+ *   - stdio (`StdioClientTransport`) for a server you launch as a child process.
+ */
+
+interface Connection {
+    client: Client;
+    /** Tears down the client, the transport, and any spawned child process. */
+    close: () => Promise<void>;
+}
+declare function openConnection(target: ConnectTarget, options?: ConnectOptions): Promise<Connection>;
+
+/**
+ * expect.ts — fluent, framework-agnostic assertions for MCP tool results.
+ *
+ * These throw a plain `Error` on failure (no dependency on vitest/jest/node:test),
+ * so they slot into any runner. Every matcher returns `this`, so they chain:
+ *
+ * ```ts
+ * expectToolResult(res)
+ *   .toSucceed()
+ *   .toHaveText(/found 3 results/)
+ *   .toMatchStructured({ count: 3 });
+ * ```
+ */
+
+declare class ToolResultAssertion {
+    private readonly result;
+    constructor(result: ToolResult);
+    /** The text of all `type: "text"` content blocks, joined by newlines. */
+    text(): string;
+    /** Parse the joined text content as JSON. Throws if it isn't valid JSON. */
+    json<T = unknown>(): T;
+    /** The raw result, for assertions the matchers don't cover. */
+    raw(): ToolResult;
+    /** Asserts the tool did NOT report an error (`isError` is not true). */
+    toSucceed(): this;
+    /** Asserts the tool reported an error (`isError === true`). */
+    toError(): this;
+    /** Alias for {@link toError}. */
+    toFail(): this;
+    /** Asserts the joined text content contains a substring, or matches a RegExp. */
+    toHaveText(expected: string | RegExp): this;
+    /** Asserts there is at least one content block of the given type. */
+    toHaveContentType(type: string): this;
+    /** Asserts the number of content blocks. */
+    toHaveContentCount(n: number): this;
+    /** Asserts at least one content block satisfies the predicate. */
+    toSatisfy(predicate: (block: ContentBlock) => boolean, message?: string): this;
+    /**
+     * Asserts `structuredContent` deep-contains the given partial object.
+     * (Recursive subset match — extra keys on the actual value are fine.)
+     */
+    toMatchStructured(expected: Record<string, unknown>): this;
+    /** Asserts `structuredContent` validates against a JSON Schema. */
+    toMatchSchema(schema: JsonSchema): this;
+}
+/** Wrap a tool result in a chainable assertion. */
+declare function expectToolResult(result: ToolResult): ToolResultAssertion;
+
+/**
+ * conformance.ts — an automated best-practices checker for MCP servers.
+ *
+ * Point it at a connected {@link TestClient} and it runs a battery of checks
+ * that catch the mistakes that make a server hard for an LLM to use well or
+ * brittle in production: missing tool descriptions, malformed input schemas,
+ * duplicate or illegally-named tools, a server that crashes on an unknown
+ * tool, missing server identity, and so on.
+ *
+ * Each check yields a {@link CheckResult}; the rolled-up {@link ConformanceReport}
+ * tells you pass/fail at a glance and is what the CLI's `check` command prints.
+ */
+
+type Severity = "error" | "warning" | "info";
+type CheckStatus = "pass" | "fail" | "skip";
+interface CheckResult {
+    id: string;
+    title: string;
+    severity: Severity;
+    status: CheckStatus;
+    /** Present when status is `fail` or `skip` — why. */
+    detail?: string;
+    /** Per-item findings (e.g. which tools are missing a description). */
+    findings?: string[];
+}
+interface ConformanceReport {
+    ok: boolean;
+    checks: CheckResult[];
+    summary: {
+        passed: number;
+        failed: number;
+        warnings: number;
+        skipped: number;
+    };
+}
+interface ConformanceOptions {
+    /** Check ids to skip entirely. */
+    skip?: string[];
+    /**
+     * Whether to actually *call* a non-existent tool to verify graceful error
+     * handling. Default `true`. Disable if your tools have side effects you'd
+     * rather not risk (this only ever calls a random non-existent name, but the
+     * escape hatch is here regardless).
+     */
+    probeUnknownTool?: boolean;
+}
+/** Run the full conformance battery against a connected client. */
+declare function conformanceCheck(client: TestClient, options?: ConformanceOptions): Promise<ConformanceReport>;
+/** The list of checks the kit runs, for documentation/UIs. */
+declare function listChecks(): Array<{
+    id: string;
+    title: string;
+    severity: Severity;
+}>;
+
+/**
+ * schema.ts — a tiny, dependency-free JSON Schema validator.
+ *
+ * This is NOT a spec-complete validator (use ajv for that). It covers the
+ * subset MCP tool `inputSchema`s actually use in practice — types, required
+ * properties, enums, nested objects/arrays, basic numeric/string bounds, and
+ * the combinators — so a test can catch "I'm calling this tool with the wrong
+ * args" before the call ever leaves the process.
+ */
+
+interface ValidationError {
+    /** JSON-pointer-ish path to the offending value, e.g. `/items/0/name`. */
+    path: string;
+    message: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/**
+ * Validate `value` against `schema`. Returns every error found, not just the
+ * first — handy for surfacing all the problems with a tool call at once.
+ */
+declare function validateAgainstSchema(value: unknown, schema: JsonSchema): ValidationResult;
+
+/**
+ * mock.ts — build throwaway `McpServer` fixtures for tests.
+ *
+ * `createTestClient({ server })` needs *a* server to talk to. Often that's the
+ * real one you're testing — but when you're testing the kit itself, or want a
+ * controlled server to assert client behaviour against, `mockServer()` spins
+ * one up in a few lines.
+ *
+ * Tool handlers return either a string (wrapped as a single text block) or a
+ * partial tool result. Input schemas are passed straight through to the SDK's
+ * `registerTool`, so they accept a Zod raw-shape (e.g. `{ q: z.string() }`) —
+ * we never import Zod ourselves, keeping the kit dependency-free at runtime.
+ */
+
+type MockToolReturn = string | {
+    content?: ContentBlock[];
+    isError?: boolean;
+    structuredContent?: unknown;
+};
+interface MockToolSpec {
+    name: string;
+    description?: string;
+    title?: string;
+    /**
+     * A Zod raw-shape describing the arguments, e.g. `{ q: z.string() }`.
+     * Passed verbatim to `McpServer.registerTool`. Omit for a zero-arg tool.
+     */
+    inputSchema?: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+    /** Runs when the tool is called. May be async. */
+    handler: (args: Record<string, unknown>) => MockToolReturn | Promise<MockToolReturn>;
+}
+interface MockServerSpec {
+    name?: string;
+    version?: string;
+    tools?: MockToolSpec[];
+}
+/**
+ * Build an `McpServer` from a compact spec — ready to hand to
+ * `createTestClient({ server })`.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * const server = mockServer({
+ *   name: "demo",
+ *   tools: [{
+ *     name: "echo",
+ *     description: "Echo the message back",
+ *     inputSchema: { message: z.string() },
+ *     handler: ({ message }) => `you said: ${message}`,
+ *   }],
+ * });
+ * ```
+ */
+declare function mockServer(spec?: MockServerSpec): McpServer;
+
+export { type CallOptions, type CheckResult, type CheckStatus, type ConformanceOptions, type ConformanceReport, type ConnectOptions, type ConnectTarget, type Connection, type ContentBlock, type JsonSchema, type JsonSchemaType, type MockServerSpec, type MockToolReturn, type MockToolSpec, type PromptInfo, type ResourceInfo, type Severity, TestClient, type ToolInfo, type ToolResult, ToolResultAssertion, type ValidationError, type ValidationResult, conformanceCheck, createTestClient, expectToolResult, listChecks, mockServer, openConnection, validateAgainstSchema, withTestClient };

package/dist/index.js

@@ -0,0 +1,181 @@
+import { validateAgainstSchema } from './chunk-EANYYOGZ.js';
+export { TestClient, conformanceCheck, createTestClient, listChecks, openConnection, validateAgainstSchema, withTestClient } from './chunk-EANYYOGZ.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+// src/expect.ts
+var ToolResultAssertion = class {
+  constructor(result) {
+    this.result = result;
+    if (!result || !Array.isArray(result.content)) {
+      throw new Error(
+        "expectToolResult: value is not an MCP tool result (missing `content` array)"
+      );
+    }
+  }
+  result;
+  /** The text of all `type: "text"` content blocks, joined by newlines. */
+  text() {
+    return this.result.content.filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("\n");
+  }
+  /** Parse the joined text content as JSON. Throws if it isn't valid JSON. */
+  json() {
+    const text = this.text();
+    try {
+      return JSON.parse(text);
+    } catch (e) {
+      throw new Error(`expected tool result text to be JSON, but parsing failed: ${e.message}
+--- text ---
+${text}`);
+    }
+  }
+  /** The raw result, for assertions the matchers don't cover. */
+  raw() {
+    return this.result;
+  }
+  // ── success / failure ───────────────────────────────────────────────────────
+  /** Asserts the tool did NOT report an error (`isError` is not true). */
+  toSucceed() {
+    if (this.result.isError === true) {
+      throw new Error(`expected tool result to succeed, but isError=true
+--- content ---
+${this.text()}`);
+    }
+    return this;
+  }
+  /** Asserts the tool reported an error (`isError === true`). */
+  toError() {
+    if (this.result.isError !== true) {
+      throw new Error(`expected tool result to be an error (isError=true), but it succeeded
+--- content ---
+${this.text()}`);
+    }
+    return this;
+  }
+  /** Alias for {@link toError}. */
+  toFail() {
+    return this.toError();
+  }
+  // ── content ─────────────────────────────────────────────────────────────────
+  /** Asserts the joined text content contains a substring, or matches a RegExp. */
+  toHaveText(expected) {
+    const text = this.text();
+    const ok = typeof expected === "string" ? text.includes(expected) : expected.test(text);
+    if (!ok) {
+      throw new Error(`expected tool text to ${typeof expected === "string" ? `contain "${expected}"` : `match ${expected}`}, got:
+${text}`);
+    }
+    return this;
+  }
+  /** Asserts there is at least one content block of the given type. */
+  toHaveContentType(type) {
+    if (!this.result.content.some((b) => b.type === type)) {
+      const seen = [...new Set(this.result.content.map((b) => b.type))].join(", ") || "(none)";
+      throw new Error(`expected a content block of type "${type}", but saw: ${seen}`);
+    }
+    return this;
+  }
+  /** Asserts the number of content blocks. */
+  toHaveContentCount(n) {
+    if (this.result.content.length !== n) {
+      throw new Error(`expected ${n} content block(s), got ${this.result.content.length}`);
+    }
+    return this;
+  }
+  /** Asserts at least one content block satisfies the predicate. */
+  toSatisfy(predicate, message = "predicate") {
+    if (!this.result.content.some(predicate)) {
+      throw new Error(`expected at least one content block to satisfy ${message}`);
+    }
+    return this;
+  }
+  // ── structured content ──────────────────────────────────────────────────────
+  /**
+   * Asserts `structuredContent` deep-contains the given partial object.
+   * (Recursive subset match — extra keys on the actual value are fine.)
+   */
+  toMatchStructured(expected) {
+    const actual = this.result.structuredContent;
+    const miss = subsetMismatch(actual, expected, "");
+    if (miss) {
+      throw new Error(`structuredContent mismatch at ${miss.path}: ${miss.message}
+--- actual ---
+${JSON.stringify(actual, null, 2)}`);
+    }
+    return this;
+  }
+  /** Asserts `structuredContent` validates against a JSON Schema. */
+  toMatchSchema(schema) {
+    const { valid, errors } = validateAgainstSchema(this.result.structuredContent, schema);
+    if (!valid) {
+      const detail = errors.map((e) => `  ${e.path} ${e.message}`).join("\n");
+      throw new Error(`structuredContent does not match schema:
+${detail}`);
+    }
+    return this;
+  }
+};
+function subsetMismatch(actual, expected, path) {
+  if (expected !== null && typeof expected === "object" && !Array.isArray(expected)) {
+    if (actual === null || typeof actual !== "object" || Array.isArray(actual)) {
+      return { path: path || "/", message: `expected an object, got ${actual === null ? "null" : Array.isArray(actual) ? "array" : typeof actual}` };
+    }
+    for (const [k, v] of Object.entries(expected)) {
+      const sub = subsetMismatch(actual[k], v, `${path}/${k}`);
+      if (sub) return sub;
+    }
+    return null;
+  }
+  if (Array.isArray(expected)) {
+    if (!Array.isArray(actual)) return { path: path || "/", message: `expected an array, got ${typeof actual}` };
+    if (actual.length !== expected.length) return { path: path || "/", message: `expected length ${expected.length}, got ${actual.length}` };
+    for (let i = 0; i < expected.length; i++) {
+      const sub = subsetMismatch(actual[i], expected[i], `${path}/${i}`);
+      if (sub) return sub;
+    }
+    return null;
+  }
+  if (actual !== expected) {
+    return { path: path || "/", message: `expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}` };
+  }
+  return null;
+}
+function expectToolResult(result) {
+  return new ToolResultAssertion(result);
+}
+function normalize(ret) {
+  if (typeof ret === "string") {
+    return { content: [{ type: "text", text: ret }] };
+  }
+  return {
+    content: ret.content ?? [{ type: "text", text: "" }],
+    isError: ret.isError,
+    structuredContent: ret.structuredContent
+  };
+}
+function mockServer(spec = {}) {
+  const server = new McpServer(
+    { name: spec.name ?? "mock-server", version: spec.version ?? "0.0.0" },
+    { capabilities: { tools: {} } }
+  );
+  for (const tool of spec.tools ?? []) {
+    const config = {};
+    if (tool.description) config.description = tool.description;
+    if (tool.title) config.title = tool.title;
+    if (tool.inputSchema) config.inputSchema = tool.inputSchema;
+    if (tool.annotations) config.annotations = tool.annotations;
+    const cb = async (argsOrExtra) => {
+      const args = (tool.inputSchema ? argsOrExtra : {}) ?? {};
+      return normalize(await tool.handler(args));
+    };
+    server.registerTool(
+      tool.name,
+      config,
+      cb
+    );
+  }
+  return server;
+}
+
+export { ToolResultAssertion, expectToolResult, mockServer };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/expect.ts","../src/mock.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * expect.ts — fluent, framework-agnostic assertions for MCP tool results.\n *\n * These throw a plain `Error` on failure (no dependency on vitest/jest/node:test),\n * so they slot into any runner. Every matcher returns `this`, so they chain:\n *\n * ```ts\n * expectToolResult(res)\n *   .toSucceed()\n *   .toHaveText(/found 3 results/)\n *   .toMatchStructured({ count: 3 });\n * ```\n */\n\nimport { validateAgainstSchema } from \"./schema\";\nimport type { ContentBlock, JsonSchema, ToolResult } from \"./types\";\n\nexport class ToolResultAssertion {\n  constructor(private readonly result: ToolResult) {\n    if (!result || !Array.isArray(result.content)) {\n      throw new Error(\n        \"expectToolResult: value is not an MCP tool result (missing `content` array)\",\n      );\n    }\n  }\n\n  /** The text of all `type: \"text\"` content blocks, joined by newlines. */\n  text(): string {\n    return this.result.content\n      .filter((b): b is ContentBlock & { text: string } => b.type === \"text\" && typeof b.text === \"string\")\n      .map((b) => b.text)\n      .join(\"\\n\");\n  }\n\n  /** Parse the joined text content as JSON. Throws if it isn't valid JSON. */\n  json<T = unknown>(): T {\n    const text = this.text();\n    try {\n      return JSON.parse(text) as T;\n    } catch (e) {\n      throw new Error(`expected tool result text to be JSON, but parsing failed: ${(e as Error).message}\\n--- text ---\\n${text}`);\n    }\n  }\n\n  /** The raw result, for assertions the matchers don't cover. */\n  raw(): ToolResult {\n    return this.result;\n  }\n\n  // ── success / failure ───────────────────────────────────────────────────────\n\n  /** Asserts the tool did NOT report an error (`isError` is not true). */\n  toSucceed(): this {\n    if (this.result.isError === true) {\n      throw new Error(`expected tool result to succeed, but isError=true\\n--- content ---\\n${this.text()}`);\n    }\n    return this;\n  }\n\n  /** Asserts the tool reported an error (`isError === true`). */\n  toError(): this {\n    if (this.result.isError !== true) {\n      throw new Error(`expected tool result to be an error (isError=true), but it succeeded\\n--- content ---\\n${this.text()}`);\n    }\n    return this;\n  }\n\n  /** Alias for {@link toError}. */\n  toFail(): this {\n    return this.toError();\n  }\n\n  // ── content ─────────────────────────────────────────────────────────────────\n\n  /** Asserts the joined text content contains a substring, or matches a RegExp. */\n  toHaveText(expected: string | RegExp): this {\n    const text = this.text();\n    const ok = typeof expected === \"string\" ? text.includes(expected) : expected.test(text);\n    if (!ok) {\n      throw new Error(`expected tool text to ${typeof expected === \"string\" ? `contain \"${expected}\"` : `match ${expected}`}, got:\\n${text}`);\n    }\n    return this;\n  }\n\n  /** Asserts there is at least one content block of the given type. */\n  toHaveContentType(type: string): this {\n    if (!this.result.content.some((b) => b.type === type)) {\n      const seen = [...new Set(this.result.content.map((b) => b.type))].join(\", \") || \"(none)\";\n      throw new Error(`expected a content block of type \"${type}\", but saw: ${seen}`);\n    }\n    return this;\n  }\n\n  /** Asserts the number of content blocks. */\n  toHaveContentCount(n: number): this {\n    if (this.result.content.length !== n) {\n      throw new Error(`expected ${n} content block(s), got ${this.result.content.length}`);\n    }\n    return this;\n  }\n\n  /** Asserts at least one content block satisfies the predicate. */\n  toSatisfy(predicate: (block: ContentBlock) => boolean, message = \"predicate\"): this {\n    if (!this.result.content.some(predicate)) {\n      throw new Error(`expected at least one content block to satisfy ${message}`);\n    }\n    return this;\n  }\n\n  // ── structured content ──────────────────────────────────────────────────────\n\n  /**\n   * Asserts `structuredContent` deep-contains the given partial object.\n   * (Recursive subset match — extra keys on the actual value are fine.)\n   */\n  toMatchStructured(expected: Record<string, unknown>): this {\n    const actual = this.result.structuredContent;\n    const miss = subsetMismatch(actual, expected, \"\");\n    if (miss) {\n      throw new Error(`structuredContent mismatch at ${miss.path}: ${miss.message}\\n--- actual ---\\n${JSON.stringify(actual, null, 2)}`);\n    }\n    return this;\n  }\n\n  /** Asserts `structuredContent` validates against a JSON Schema. */\n  toMatchSchema(schema: JsonSchema): this {\n    const { valid, errors } = validateAgainstSchema(this.result.structuredContent, schema);\n    if (!valid) {\n      const detail = errors.map((e) => `  ${e.path} ${e.message}`).join(\"\\n\");\n      throw new Error(`structuredContent does not match schema:\\n${detail}`);\n    }\n    return this;\n  }\n}\n\nfunction subsetMismatch(actual: unknown, expected: unknown, path: string): { path: string; message: string } | null {\n  if (expected !== null && typeof expected === \"object\" && !Array.isArray(expected)) {\n    if (actual === null || typeof actual !== \"object\" || Array.isArray(actual)) {\n      return { path: path || \"/\", message: `expected an object, got ${actual === null ? \"null\" : Array.isArray(actual) ? \"array\" : typeof actual}` };\n    }\n    for (const [k, v] of Object.entries(expected)) {\n      const sub = subsetMismatch((actual as Record<string, unknown>)[k], v, `${path}/${k}`);\n      if (sub) return sub;\n    }\n    return null;\n  }\n  if (Array.isArray(expected)) {\n    if (!Array.isArray(actual)) return { path: path || \"/\", message: `expected an array, got ${typeof actual}` };\n    if (actual.length !== expected.length) return { path: path || \"/\", message: `expected length ${expected.length}, got ${actual.length}` };\n    for (let i = 0; i < expected.length; i++) {\n      const sub = subsetMismatch(actual[i], expected[i], `${path}/${i}`);\n      if (sub) return sub;\n    }\n    return null;\n  }\n  if (actual !== expected) {\n    return { path: path || \"/\", message: `expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}` };\n  }\n  return null;\n}\n\n/** Wrap a tool result in a chainable assertion. */\nexport function expectToolResult(result: ToolResult): ToolResultAssertion {\n  return new ToolResultAssertion(result);\n}\n","/**\n * mock.ts — build throwaway `McpServer` fixtures for tests.\n *\n * `createTestClient({ server })` needs *a* server to talk to. Often that's the\n * real one you're testing — but when you're testing the kit itself, or want a\n * controlled server to assert client behaviour against, `mockServer()` spins\n * one up in a few lines.\n *\n * Tool handlers return either a string (wrapped as a single text block) or a\n * partial tool result. Input schemas are passed straight through to the SDK's\n * `registerTool`, so they accept a Zod raw-shape (e.g. `{ q: z.string() }`) —\n * we never import Zod ourselves, keeping the kit dependency-free at runtime.\n */\n\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { ContentBlock } from \"./types\";\n\nexport type MockToolReturn =\n  | string\n  | {\n      content?: ContentBlock[];\n      isError?: boolean;\n      structuredContent?: unknown;\n    };\n\nexport interface MockToolSpec {\n  name: string;\n  description?: string;\n  title?: string;\n  /**\n   * A Zod raw-shape describing the arguments, e.g. `{ q: z.string() }`.\n   * Passed verbatim to `McpServer.registerTool`. Omit for a zero-arg tool.\n   */\n  inputSchema?: Record<string, unknown>;\n  annotations?: Record<string, unknown>;\n  /** Runs when the tool is called. May be async. */\n  handler: (args: Record<string, unknown>) => MockToolReturn | Promise<MockToolReturn>;\n}\n\nexport interface MockServerSpec {\n  name?: string;\n  version?: string;\n  tools?: MockToolSpec[];\n}\n\nfunction normalize(ret: MockToolReturn): { content: ContentBlock[]; isError?: boolean; structuredContent?: unknown } {\n  if (typeof ret === \"string\") {\n    return { content: [{ type: \"text\", text: ret }] };\n  }\n  return {\n    content: ret.content ?? [{ type: \"text\", text: \"\" }],\n    isError: ret.isError,\n    structuredContent: ret.structuredContent,\n  };\n}\n\n/**\n * Build an `McpServer` from a compact spec — ready to hand to\n * `createTestClient({ server })`.\n *\n * @example\n * ```ts\n * import { z } from \"zod\";\n * const server = mockServer({\n *   name: \"demo\",\n *   tools: [{\n *     name: \"echo\",\n *     description: \"Echo the message back\",\n *     inputSchema: { message: z.string() },\n *     handler: ({ message }) => `you said: ${message}`,\n *   }],\n * });\n * ```\n */\nexport function mockServer(spec: MockServerSpec = {}): McpServer {\n  const server = new McpServer(\n    { name: spec.name ?? \"mock-server\", version: spec.version ?? \"0.0.0\" },\n    { capabilities: { tools: {} } },\n  );\n\n  for (const tool of spec.tools ?? []) {\n    const config: Record<string, unknown> = {};\n    if (tool.description) config.description = tool.description;\n    if (tool.title) config.title = tool.title;\n    if (tool.inputSchema) config.inputSchema = tool.inputSchema;\n    if (tool.annotations) config.annotations = tool.annotations;\n\n    // The SDK's callback receives parsed args (when inputSchema is set) plus an\n    // `extra` we don't need here. We funnel both arg-shapes into our handler.\n    const cb = async (argsOrExtra: unknown) => {\n      const args = (tool.inputSchema ? (argsOrExtra as Record<string, unknown>) : {}) ?? {};\n      return normalize(await tool.handler(args));\n    };\n\n    // registerTool's overloads are tighter than our pass-through types; the\n    // cast is intentional and safe — the SDK validates the config at runtime.\n    (server.registerTool as unknown as (n: string, c: unknown, cb: unknown) => unknown)(\n      tool.name,\n      config,\n      cb,\n    );\n  }\n\n  return server;\n}\n"]}