@mcpkit-dev/testing 1.0.0

package/README.md

@@ -0,0 +1,343 @@
+# @mcpkit-dev/testing
+
+Testing utilities for MCPKit MCP servers. Provides mock clients, in-memory transports, and helpers for writing comprehensive tests.
+
+## Installation
+
+```bash
+npm install -D @mcpkit-dev/testing
+```
+
+## Features
+
+- **MockMcpClient** - Full-featured mock MCP client for testing servers
+- **InMemoryTransport** - Zero-latency transport for unit tests
+- **Test helpers** - Utilities for common testing patterns
+
+## Quick Start
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { MockMcpClient } from '@mcpkit-dev/testing';
+import { listen } from '@mcpkit-dev/core';
+import { MyServer } from './my-server';
+
+describe('MyServer', () => {
+  let client: MockMcpClient;
+  let cleanup: () => Promise<void>;
+
+  beforeEach(async () => {
+    const { client: mockClient, serverTransport } = MockMcpClient.create();
+    client = mockClient;
+
+    const server = await listen(MyServer);
+    await server.server.connect(serverTransport);
+    await client.connect();
+
+    cleanup = async () => {
+      await client.close();
+      await server.close();
+    };
+  });
+
+  afterEach(async () => {
+    await cleanup();
+  });
+
+  it('should list available tools', async () => {
+    const result = await client.listTools();
+    expect(result.tools).toHaveLength(1);
+    expect(result.tools[0].name).toBe('greet');
+  });
+
+  it('should call a tool', async () => {
+    const result = await client.callTool('greet', { name: 'World' });
+    expect(result.content[0].text).toBe('Hello, World!');
+  });
+});
+```
+
+## API Reference
+
+### MockMcpClient
+
+A mock MCP client that communicates with servers over in-memory transports.
+
+#### Creating a Client
+
+```typescript
+import { MockMcpClient } from '@mcpkit-dev/testing';
+
+// Create with default options
+const { client, serverTransport } = MockMcpClient.create();
+
+// Create with custom options
+const { client, serverTransport } = MockMcpClient.create({
+  name: 'test-client',
+  version: '1.0.0',
+});
+```
+
+#### Methods
+
+##### `connect(): Promise<void>`
+
+Connect the client to the server.
+
+```typescript
+await client.connect();
+```
+
+##### `close(): Promise<void>`
+
+Close the client connection.
+
+```typescript
+await client.close();
+```
+
+##### `listTools(): Promise<ListToolsResult>`
+
+List all available tools from the server.
+
+```typescript
+const { tools } = await client.listTools();
+console.log(tools); // [{ name: 'greet', description: '...' }]
+```
+
+##### `callTool(name: string, args?: Record<string, unknown>)`
+
+Call a tool by name with optional arguments.
+
+```typescript
+const result = await client.callTool('greet', { name: 'Alice' });
+console.log(result.content[0].text); // 'Hello, Alice!'
+```
+
+##### `listResources(): Promise<ListResourcesResult>`
+
+List all available resources.
+
+```typescript
+const { resources } = await client.listResources();
+```
+
+##### `readResource(uri: string): Promise<ReadResourceResult>`
+
+Read a resource by URI.
+
+```typescript
+const result = await client.readResource('config://settings');
+console.log(result.contents[0].text);
+```
+
+##### `listPrompts(): Promise<ListPromptsResult>`
+
+List all available prompts.
+
+```typescript
+const { prompts } = await client.listPrompts();
+```
+
+##### `getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult>`
+
+Get a prompt by name with optional arguments.
+
+```typescript
+const result = await client.getPrompt('greeting', { name: 'Bob' });
+console.log(result.messages);
+```
+
+##### `rawClient: Client`
+
+Access the underlying MCP SDK client for advanced operations.
+
+```typescript
+const sdkClient = client.rawClient;
+```
+
+### InMemoryTransport
+
+A transport implementation that allows direct communication between client and server without network overhead.
+
+#### Creating a Transport Pair
+
+```typescript
+import { InMemoryTransport } from '@mcpkit-dev/testing';
+
+const { clientTransport, serverTransport } = InMemoryTransport.createPair();
+
+// Connect to server
+await server.connect(serverTransport);
+
+// Connect client
+await client.connect(clientTransport);
+```
+
+#### Methods
+
+##### `start(): Promise<void>`
+
+Start the transport and process any queued messages.
+
+##### `send(message: JSONRPCMessage): Promise<void>`
+
+Send a message to the peer transport.
+
+##### `close(): Promise<void>`
+
+Close the transport and its peer.
+
+##### `deliverMessage(message: JSONRPCMessage): void`
+
+Directly deliver a message (for testing edge cases).
+
+### Helper Functions
+
+#### `createTestClient(options?)`
+
+Convenience function to create a mock client.
+
+```typescript
+import { createTestClient } from '@mcpkit-dev/testing';
+
+const { client, serverTransport } = createTestClient({
+  name: 'my-test-client',
+});
+```
+
+#### `waitForCondition(condition, options?)`
+
+Wait for a condition to be true with timeout.
+
+```typescript
+import { waitForCondition } from '@mcpkit-dev/testing';
+
+// Wait up to 5 seconds for server to be ready
+await waitForCondition(() => server.isReady, {
+  timeout: 5000,
+  interval: 100,
+});
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeout` | `number` | `5000` | Maximum time to wait (ms) |
+| `interval` | `number` | `50` | Check interval (ms) |
+
+#### `createTestServer(ServerClass, listenFn)`
+
+Create a complete test environment with server and connected client.
+
+```typescript
+import { createTestServer } from '@mcpkit-dev/testing';
+import { listen } from '@mcpkit-dev/core';
+
+const { client, server, instance, cleanup } = await createTestServer(
+  MyServer,
+  listen
+);
+
+// Run tests...
+const tools = await client.listTools();
+
+// Clean up
+await cleanup();
+```
+
+## Testing Patterns
+
+### Testing Tools
+
+```typescript
+it('should handle tool errors gracefully', async () => {
+  const result = await client.callTool('divide', { a: 10, b: 0 });
+  expect(result.isError).toBe(true);
+  expect(result.content[0].text).toContain('Cannot divide by zero');
+});
+
+it('should validate tool parameters', async () => {
+  await expect(
+    client.callTool('greet', { invalidParam: 'value' })
+  ).rejects.toThrow();
+});
+```
+
+### Testing Resources
+
+```typescript
+it('should read dynamic resources', async () => {
+  const result = await client.readResource('users://123');
+  const user = JSON.parse(result.contents[0].text);
+  expect(user.id).toBe('123');
+});
+
+it('should list resource templates', async () => {
+  const { resources } = await client.listResources();
+  const template = resources.find(r => r.uri.includes('{'));
+  expect(template).toBeDefined();
+});
+```
+
+### Testing Prompts
+
+```typescript
+it('should generate prompt with arguments', async () => {
+  const result = await client.getPrompt('code-review', {
+    language: 'typescript',
+    focus: 'security',
+  });
+
+  expect(result.messages[0].content.text).toContain('typescript');
+  expect(result.messages[0].content.text).toContain('security');
+});
+```
+
+### Testing with Mocked Dependencies
+
+```typescript
+import { vi } from 'vitest';
+
+// Mock external service
+vi.mock('./weather-api', () => ({
+  getWeather: vi.fn().mockResolvedValue({ temp: 22, condition: 'sunny' }),
+}));
+
+it('should use mocked weather data', async () => {
+  const result = await client.callTool('getWeather', { city: 'London' });
+  expect(result.content[0].text).toContain('22');
+});
+```
+
+## Integration with Test Frameworks
+
+### Vitest
+
+```typescript
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+
+describe('MCP Server Integration', () => {
+  // ... setup and tests
+});
+```
+
+### Jest
+
+```typescript
+import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
+
+describe('MCP Server Integration', () => {
+  // ... setup and tests
+});
+```
+
+## Related Packages
+
+- [@mcpkit-dev/core](https://www.npmjs.com/package/@mcpkit-dev/core) - Core decorators and server framework
+- [@mcpkit-dev/cli](https://www.npmjs.com/package/@mcpkit-dev/cli) - CLI tool for project scaffolding
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,504 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Options for creating a mock MCP client
+ */
+interface MockClientOptions {
+    /** Client name */
+    name?: string;
+    /** Client version */
+    version?: string;
+}
+/**
+ * Result from creating a mock client
+ */
+interface MockClientResult {
+    /** The MCP client instance */
+    client: MockMcpClient;
+    /** Transport for connecting to a server */
+    serverTransport: Transport;
+}
+/**
+ * Mock MCP client for testing servers
+ *
+ * Provides a simple interface for testing MCP server implementations
+ * without needing actual network connections.
+ *
+ * @example
+ * ```typescript
+ * const { client, serverTransport } = MockMcpClient.create();
+ *
+ * // Connect your server to serverTransport
+ * const server = await listen(MyServer);
+ * await server.server.connect(serverTransport);
+ *
+ * // Use the client to test your server
+ * const tools = await client.listTools();
+ * const result = await client.callTool('myTool', { param: 'value' });
+ * ```
+ */
+declare class MockMcpClient {
+    private client;
+    private clientTransport;
+    private connected;
+    private constructor();
+    /**
+     * Create a mock client with linked transports
+     */
+    static create(options?: MockClientOptions): MockClientResult;
+    /**
+     * Connect to the server
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the connection
+     */
+    close(): Promise<void>;
+    /**
+     * List all available tools
+     */
+    listTools(): Promise<{
+        [x: string]: unknown;
+        tools: {
+            inputSchema: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: Record<string, object> | undefined;
+                required?: string[] | undefined;
+            };
+            name: string;
+            description?: string | undefined;
+            outputSchema?: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: Record<string, object> | undefined;
+                required?: string[] | undefined;
+            } | undefined;
+            annotations?: {
+                title?: string | undefined;
+                readOnlyHint?: boolean | undefined;
+                destructiveHint?: boolean | undefined;
+                idempotentHint?: boolean | undefined;
+                openWorldHint?: boolean | undefined;
+            } | undefined;
+            execution?: {
+                taskSupport?: "optional" | "required" | "forbidden" | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        }[];
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        nextCursor?: string | undefined;
+    }>;
+    /**
+     * Call a tool by name
+     */
+    callTool(name: string, args?: Record<string, unknown>): Promise<{
+        [x: string]: unknown;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                text: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                uri: string;
+                blob: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            };
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            uri: string;
+            name: string;
+            type: "resource_link";
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        })[];
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        structuredContent?: Record<string, unknown> | undefined;
+        isError?: boolean | undefined;
+    } | {
+        [x: string]: unknown;
+        toolResult: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    /**
+     * List all available resources
+     */
+    listResources(): Promise<{
+        [x: string]: unknown;
+        resources: {
+            uri: string;
+            name: string;
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        }[];
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        nextCursor?: string | undefined;
+    }>;
+    /**
+     * Read a resource by URI
+     */
+    readResource(uri: string): Promise<{
+        [x: string]: unknown;
+        contents: ({
+            uri: string;
+            text: string;
+            mimeType?: string | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            uri: string;
+            blob: string;
+            mimeType?: string | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        })[];
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    /**
+     * List all available prompts
+     */
+    listPrompts(): Promise<{
+        [x: string]: unknown;
+        prompts: {
+            name: string;
+            description?: string | undefined;
+            arguments?: {
+                name: string;
+                description?: string | undefined;
+                required?: boolean | undefined;
+            }[] | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        }[];
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        nextCursor?: string | undefined;
+    }>;
+    /**
+     * Get a prompt by name
+     */
+    getPrompt(name: string, args?: Record<string, string>): Promise<{
+        [x: string]: unknown;
+        messages: {
+            role: "user" | "assistant";
+            content: {
+                type: "text";
+                text: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                type: "image";
+                data: string;
+                mimeType: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                type: "audio";
+                data: string;
+                mimeType: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                type: "resource";
+                resource: {
+                    uri: string;
+                    text: string;
+                    mimeType?: string | undefined;
+                    _meta?: Record<string, unknown> | undefined;
+                } | {
+                    uri: string;
+                    blob: string;
+                    mimeType?: string | undefined;
+                    _meta?: Record<string, unknown> | undefined;
+                };
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                uri: string;
+                name: string;
+                type: "resource_link";
+                description?: string | undefined;
+                mimeType?: string | undefined;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                icons?: {
+                    src: string;
+                    mimeType?: string | undefined;
+                    sizes?: string[] | undefined;
+                }[] | undefined;
+                title?: string | undefined;
+            };
+        }[];
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        description?: string | undefined;
+    }>;
+    /**
+     * Ensure the client is connected
+     */
+    private ensureConnected;
+    /**
+     * Get the underlying MCP client
+     */
+    get rawClient(): Client;
+}
+
+/**
+ * Result from creating a test server
+ */
+interface TestServerResult<T> {
+    /** The server instance */
+    instance: T;
+    /** The bootstrapped server */
+    server: {
+        server: unknown;
+        transport: unknown;
+        connect: () => Promise<void>;
+        close: () => Promise<void>;
+    };
+    /** The test client */
+    client: MockMcpClient;
+    /** Cleanup function */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Create a test client for MCP server testing
+ *
+ * @example
+ * ```typescript
+ * const { client, serverTransport } = createTestClient();
+ * ```
+ */
+declare function createTestClient(options?: MockClientOptions): MockClientResult;
+/**
+ * Wait for a condition to be true, with timeout
+ *
+ * @example
+ * ```typescript
+ * await waitForCondition(() => server.isReady, { timeout: 5000 });
+ * ```
+ */
+declare function waitForCondition(condition: () => boolean | Promise<boolean>, options?: {
+    timeout?: number;
+    interval?: number;
+}): Promise<void>;
+/**
+ * Create a test server with a connected client
+ *
+ * This is a convenience function that sets up a complete test environment
+ * with a server instance, bootstrapped server, and connected client.
+ *
+ * @example
+ * ```typescript
+ * import { createTestServer } from '@mcpkit-dev/testing';
+ * import { listen } from '@mcpkit-dev/core';
+ *
+ * // In your test
+ * const { client, cleanup } = await createTestServer(MyServer, listen);
+ *
+ * // Test your server
+ * const tools = await client.listTools();
+ * expect(tools.tools).toHaveLength(1);
+ *
+ * // Clean up
+ * await cleanup();
+ * ```
+ */
+declare function createTestServer<T extends new () => object>(ServerClass: T, listenFn: (ServerClass: T) => Promise<{
+    server: unknown;
+    transport: unknown;
+    connect: () => Promise<void>;
+    close: () => Promise<void>;
+}>): Promise<TestServerResult<InstanceType<T>>>;
+
+/**
+ * In-memory transport for testing MCP servers
+ *
+ * This transport allows direct communication between a client and server
+ * without any network overhead, perfect for unit and integration tests.
+ *
+ * @example
+ * ```typescript
+ * const { clientTransport, serverTransport } = InMemoryTransport.createPair();
+ *
+ * // Connect server to serverTransport
+ * await server.connect(serverTransport);
+ *
+ * // Use clientTransport to send messages
+ * await clientTransport.send({ jsonrpc: '2.0', method: 'ping', id: 1 });
+ * ```
+ */
+declare class InMemoryTransport implements Transport {
+    private peer;
+    private messageQueue;
+    private started;
+    private closed;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    /**
+     * Create a linked pair of transports for testing
+     */
+    static createPair(): {
+        clientTransport: InMemoryTransport;
+        serverTransport: InMemoryTransport;
+    };
+    /**
+     * Start the transport
+     */
+    start(): Promise<void>;
+    /**
+     * Send a message to the peer transport
+     */
+    send(message: JSONRPCMessage): Promise<void>;
+    /**
+     * Close the transport
+     */
+    close(): Promise<void>;
+    /**
+     * Deliver a message directly (for testing purposes)
+     */
+    deliverMessage(message: JSONRPCMessage): void;
+}
+
+export { InMemoryTransport, type MockClientOptions, type MockClientResult, MockMcpClient, type TestServerResult, createTestClient, createTestServer, waitForCondition };

package/dist/index.js

@@ -0,0 +1,229 @@
+// src/mock-client.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+
+// src/transport.ts
+var InMemoryTransport = class _InMemoryTransport {
+  peer = null;
+  messageQueue = [];
+  started = false;
+  closed = false;
+  onclose;
+  onerror;
+  onmessage;
+  /**
+   * Create a linked pair of transports for testing
+   */
+  static createPair() {
+    const clientTransport = new _InMemoryTransport();
+    const serverTransport = new _InMemoryTransport();
+    clientTransport.peer = serverTransport;
+    serverTransport.peer = clientTransport;
+    return { clientTransport, serverTransport };
+  }
+  /**
+   * Start the transport
+   */
+  async start() {
+    if (this.started) {
+      throw new Error("Transport already started");
+    }
+    if (this.closed) {
+      throw new Error("Transport is closed");
+    }
+    this.started = true;
+    while (this.messageQueue.length > 0) {
+      const message = this.messageQueue.shift();
+      if (message) {
+        this.onmessage?.(message);
+      }
+    }
+  }
+  /**
+   * Send a message to the peer transport
+   */
+  async send(message) {
+    if (this.closed) {
+      throw new Error("Transport is closed");
+    }
+    if (!this.peer) {
+      throw new Error("No peer transport connected");
+    }
+    await Promise.resolve();
+    if (this.peer.started) {
+      this.peer.onmessage?.(message);
+    } else {
+      this.peer.messageQueue.push(message);
+    }
+  }
+  /**
+   * Close the transport
+   */
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.onclose?.();
+    if (this.peer && !this.peer.closed) {
+      await this.peer.close();
+    }
+  }
+  /**
+   * Deliver a message directly (for testing purposes)
+   */
+  deliverMessage(message) {
+    if (this.started) {
+      this.onmessage?.(message);
+    } else {
+      this.messageQueue.push(message);
+    }
+  }
+};
+
+// src/mock-client.ts
+var MockMcpClient = class _MockMcpClient {
+  client;
+  clientTransport;
+  connected = false;
+  constructor(options = {}) {
+    this.client = new Client(
+      {
+        name: options.name ?? "test-client",
+        version: options.version ?? "1.0.0"
+      },
+      {
+        capabilities: {}
+      }
+    );
+    this.clientTransport = new InMemoryTransport();
+  }
+  /**
+   * Create a mock client with linked transports
+   */
+  static create(options) {
+    const mockClient = new _MockMcpClient(options);
+    const { clientTransport, serverTransport } = InMemoryTransport.createPair();
+    mockClient.clientTransport = clientTransport;
+    return {
+      client: mockClient,
+      serverTransport
+    };
+  }
+  /**
+   * Connect to the server
+   */
+  async connect() {
+    if (this.connected) {
+      return;
+    }
+    await this.client.connect(this.clientTransport);
+    this.connected = true;
+  }
+  /**
+   * Close the connection
+   */
+  async close() {
+    if (!this.connected) {
+      return;
+    }
+    await this.client.close();
+    this.connected = false;
+  }
+  /**
+   * List all available tools
+   */
+  async listTools() {
+    await this.ensureConnected();
+    return this.client.listTools();
+  }
+  /**
+   * Call a tool by name
+   */
+  async callTool(name, args) {
+    await this.ensureConnected();
+    return this.client.callTool({ name, arguments: args });
+  }
+  /**
+   * List all available resources
+   */
+  async listResources() {
+    await this.ensureConnected();
+    return this.client.listResources();
+  }
+  /**
+   * Read a resource by URI
+   */
+  async readResource(uri) {
+    await this.ensureConnected();
+    return this.client.readResource({ uri });
+  }
+  /**
+   * List all available prompts
+   */
+  async listPrompts() {
+    await this.ensureConnected();
+    return this.client.listPrompts();
+  }
+  /**
+   * Get a prompt by name
+   */
+  async getPrompt(name, args) {
+    await this.ensureConnected();
+    return this.client.getPrompt({ name, arguments: args });
+  }
+  /**
+   * Ensure the client is connected
+   */
+  async ensureConnected() {
+    if (!this.connected) {
+      await this.connect();
+    }
+  }
+  /**
+   * Get the underlying MCP client
+   */
+  get rawClient() {
+    return this.client;
+  }
+};
+
+// src/helpers.ts
+function createTestClient(options) {
+  return MockMcpClient.create(options);
+}
+async function waitForCondition(condition, options = {}) {
+  const { timeout = 5e3, interval = 50 } = options;
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    if (await condition()) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+  throw new Error(`Condition not met within ${timeout}ms`);
+}
+async function createTestServer(ServerClass, listenFn) {
+  const { client, serverTransport } = createTestClient();
+  const instance = new ServerClass();
+  const bootstrapped = await listenFn(ServerClass);
+  const server = bootstrapped.server;
+  await server.connect(serverTransport);
+  await client.connect();
+  return {
+    instance,
+    server: bootstrapped,
+    client,
+    cleanup: async () => {
+      await client.close();
+      await bootstrapped.close();
+    }
+  };
+}
+export {
+  InMemoryTransport,
+  MockMcpClient,
+  createTestClient,
+  createTestServer,
+  waitForCondition
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mock-client.ts","../src/transport.ts","../src/helpers.ts"],"sourcesContent":["import { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';\nimport { InMemoryTransport } from './transport.js';\n\n/**\n * Options for creating a mock MCP client\n */\nexport interface MockClientOptions {\n  /** Client name */\n  name?: string;\n  /** Client version */\n  version?: string;\n}\n\n/**\n * Result from creating a mock client\n */\nexport interface MockClientResult {\n  /** The MCP client instance */\n  client: MockMcpClient;\n  /** Transport for connecting to a server */\n  serverTransport: Transport;\n}\n\n/**\n * Mock MCP client for testing servers\n *\n * Provides a simple interface for testing MCP server implementations\n * without needing actual network connections.\n *\n * @example\n * ```typescript\n * const { client, serverTransport } = MockMcpClient.create();\n *\n * // Connect your server to serverTransport\n * const server = await listen(MyServer);\n * await server.server.connect(serverTransport);\n *\n * // Use the client to test your server\n * const tools = await client.listTools();\n * const result = await client.callTool('myTool', { param: 'value' });\n * ```\n */\nexport class MockMcpClient {\n  private client: Client;\n  private clientTransport: InMemoryTransport;\n  private connected = false;\n\n  private constructor(options: MockClientOptions = {}) {\n    this.client = new Client(\n      {\n        name: options.name ?? 'test-client',\n        version: options.version ?? '1.0.0',\n      },\n      {\n        capabilities: {},\n      },\n    );\n\n    this.clientTransport = new InMemoryTransport();\n  }\n\n  /**\n   * Create a mock client with linked transports\n   */\n  static create(options?: MockClientOptions): MockClientResult {\n    const mockClient = new MockMcpClient(options);\n    const { clientTransport, serverTransport } = InMemoryTransport.createPair();\n\n    mockClient.clientTransport = clientTransport;\n\n    return {\n      client: mockClient,\n      serverTransport,\n    };\n  }\n\n  /**\n   * Connect to the server\n   */\n  async connect(): Promise<void> {\n    if (this.connected) {\n      return;\n    }\n\n    await this.client.connect(this.clientTransport);\n    this.connected = true;\n  }\n\n  /**\n   * Close the connection\n   */\n  async close(): Promise<void> {\n    if (!this.connected) {\n      return;\n    }\n\n    await this.client.close();\n    this.connected = false;\n  }\n\n  /**\n   * List all available tools\n   */\n  async listTools() {\n    await this.ensureConnected();\n    return this.client.listTools();\n  }\n\n  /**\n   * Call a tool by name\n   */\n  async callTool(name: string, args?: Record<string, unknown>) {\n    await this.ensureConnected();\n    return this.client.callTool({ name, arguments: args });\n  }\n\n  /**\n   * List all available resources\n   */\n  async listResources() {\n    await this.ensureConnected();\n    return this.client.listResources();\n  }\n\n  /**\n   * Read a resource by URI\n   */\n  async readResource(uri: string) {\n    await this.ensureConnected();\n    return this.client.readResource({ uri });\n  }\n\n  /**\n   * List all available prompts\n   */\n  async listPrompts() {\n    await this.ensureConnected();\n    return this.client.listPrompts();\n  }\n\n  /**\n   * Get a prompt by name\n   */\n  async getPrompt(name: string, args?: Record<string, string>) {\n    await this.ensureConnected();\n    return this.client.getPrompt({ name, arguments: args });\n  }\n\n  /**\n   * Ensure the client is connected\n   */\n  private async ensureConnected(): Promise<void> {\n    if (!this.connected) {\n      await this.connect();\n    }\n  }\n\n  /**\n   * Get the underlying MCP client\n   */\n  get rawClient(): Client {\n    return this.client;\n  }\n}\n","import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';\nimport type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';\n\n/**\n * In-memory transport for testing MCP servers\n *\n * This transport allows direct communication between a client and server\n * without any network overhead, perfect for unit and integration tests.\n *\n * @example\n * ```typescript\n * const { clientTransport, serverTransport } = InMemoryTransport.createPair();\n *\n * // Connect server to serverTransport\n * await server.connect(serverTransport);\n *\n * // Use clientTransport to send messages\n * await clientTransport.send({ jsonrpc: '2.0', method: 'ping', id: 1 });\n * ```\n */\nexport class InMemoryTransport implements Transport {\n  private peer: InMemoryTransport | null = null;\n  private messageQueue: JSONRPCMessage[] = [];\n  private started = false;\n  private closed = false;\n\n  onclose?: () => void;\n  onerror?: (error: Error) => void;\n  onmessage?: (message: JSONRPCMessage) => void;\n\n  /**\n   * Create a linked pair of transports for testing\n   */\n  static createPair(): { clientTransport: InMemoryTransport; serverTransport: InMemoryTransport } {\n    const clientTransport = new InMemoryTransport();\n    const serverTransport = new InMemoryTransport();\n\n    clientTransport.peer = serverTransport;\n    serverTransport.peer = clientTransport;\n\n    return { clientTransport, serverTransport };\n  }\n\n  /**\n   * Start the transport\n   */\n  async start(): Promise<void> {\n    if (this.started) {\n      throw new Error('Transport already started');\n    }\n    if (this.closed) {\n      throw new Error('Transport is closed');\n    }\n\n    this.started = true;\n\n    // Process any queued messages\n    while (this.messageQueue.length > 0) {\n      const message = this.messageQueue.shift();\n      if (message) {\n        this.onmessage?.(message);\n      }\n    }\n  }\n\n  /**\n   * Send a message to the peer transport\n   */\n  async send(message: JSONRPCMessage): Promise<void> {\n    if (this.closed) {\n      throw new Error('Transport is closed');\n    }\n\n    if (!this.peer) {\n      throw new Error('No peer transport connected');\n    }\n\n    // Simulate async behavior\n    await Promise.resolve();\n\n    if (this.peer.started) {\n      this.peer.onmessage?.(message);\n    } else {\n      this.peer.messageQueue.push(message);\n    }\n  }\n\n  /**\n   * Close the transport\n   */\n  async close(): Promise<void> {\n    if (this.closed) {\n      return;\n    }\n\n    this.closed = true;\n    this.onclose?.();\n\n    // Also close peer\n    if (this.peer && !this.peer.closed) {\n      await this.peer.close();\n    }\n  }\n\n  /**\n   * Deliver a message directly (for testing purposes)\n   */\n  deliverMessage(message: JSONRPCMessage): void {\n    if (this.started) {\n      this.onmessage?.(message);\n    } else {\n      this.messageQueue.push(message);\n    }\n  }\n}\n","import { type MockClientOptions, type MockClientResult, MockMcpClient } from './mock-client.js';\n\n/**\n * Result from creating a test server\n */\nexport interface TestServerResult<T> {\n  /** The server instance */\n  instance: T;\n  /** The bootstrapped server */\n  server: {\n    server: unknown;\n    transport: unknown;\n    connect: () => Promise<void>;\n    close: () => Promise<void>;\n  };\n  /** The test client */\n  client: MockMcpClient;\n  /** Cleanup function */\n  cleanup: () => Promise<void>;\n}\n\n/**\n * Create a test client for MCP server testing\n *\n * @example\n * ```typescript\n * const { client, serverTransport } = createTestClient();\n * ```\n */\nexport function createTestClient(options?: MockClientOptions): MockClientResult {\n  return MockMcpClient.create(options);\n}\n\n/**\n * Wait for a condition to be true, with timeout\n *\n * @example\n * ```typescript\n * await waitForCondition(() => server.isReady, { timeout: 5000 });\n * ```\n */\nexport async function waitForCondition(\n  condition: () => boolean | Promise<boolean>,\n  options: { timeout?: number; interval?: number } = {},\n): Promise<void> {\n  const { timeout = 5000, interval = 50 } = options;\n  const startTime = Date.now();\n\n  while (Date.now() - startTime < timeout) {\n    if (await condition()) {\n      return;\n    }\n    await new Promise((resolve) => setTimeout(resolve, interval));\n  }\n\n  throw new Error(`Condition not met within ${timeout}ms`);\n}\n\n/**\n * Create a test server with a connected client\n *\n * This is a convenience function that sets up a complete test environment\n * with a server instance, bootstrapped server, and connected client.\n *\n * @example\n * ```typescript\n * import { createTestServer } from '@mcpkit-dev/testing';\n * import { listen } from '@mcpkit-dev/core';\n *\n * // In your test\n * const { client, cleanup } = await createTestServer(MyServer, listen);\n *\n * // Test your server\n * const tools = await client.listTools();\n * expect(tools.tools).toHaveLength(1);\n *\n * // Clean up\n * await cleanup();\n * ```\n */\nexport async function createTestServer<T extends new () => object>(\n  ServerClass: T,\n  listenFn: (ServerClass: T) => Promise<{\n    server: unknown;\n    transport: unknown;\n    connect: () => Promise<void>;\n    close: () => Promise<void>;\n  }>,\n): Promise<TestServerResult<InstanceType<T>>> {\n  const { client, serverTransport } = createTestClient();\n  const instance = new ServerClass() as InstanceType<T>;\n  const bootstrapped = await listenFn(ServerClass);\n\n  // Connect server to transport\n  // We need to access the internal server and connect it\n  const server = bootstrapped.server as {\n    connect: (transport: unknown) => Promise<void>;\n  };\n  await server.connect(serverTransport);\n\n  // Connect client\n  await client.connect();\n\n  return {\n    instance,\n    server: bootstrapped,\n    client,\n    cleanup: async () => {\n      await client.close();\n      await bootstrapped.close();\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@mcpkit-dev/testing",
+  "version": "1.0.0",
+  "description": "Testing utilities for mcpkit MCP servers",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "peerDependencies": {
+    "@mcpkit-dev/core": ">=0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.9"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "testing",
+    "mcpkit",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/v-checha/mcpkit.git",
+    "directory": "packages/testing"
+  }
+}