@slbdn/mcp-tester 1.4.1 → 1.5.3

package/dist/templates/full-stack/tests/tools.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Tool tests for the full-stack server.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from '@jest/globals';
+import type { MCPClient } from '@slbdn/mcp-tester';
+import { contentText, createConnectedClient } from './helpers.js';
+
+describe('Tools', () => {
+  let client: MCPClient;
+
+  beforeAll(async () => {
+    client = await createConnectedClient('tools-test');
+  });
+
+  afterAll(async () => {
+    if (client?.isConnected()) {
+      await client.stop();
+    }
+  });
+
+  describe('greet', () => {
+    it('greets by name', async () => {
+      const result = await client.callTool({ name: 'greet', arguments: { name: 'Alice' } });
+      expect(contentText(result)).toBe('Hello, Alice!');
+    });
+  });
+
+  describe('sum', () => {
+    it('sums an array of numbers', async () => {
+      const result = await client.callTool({
+        name: 'sum',
+        arguments: { numbers: [1, 2, 3, 4] },
+      });
+      expect(contentText(result)).toBe('10');
+    });
+
+    it('returns 0 for an empty array', async () => {
+      const result = await client.callTool({ name: 'sum', arguments: { numbers: [] } });
+      expect(contentText(result)).toBe('0');
+    });
+  });
+
+  describe('uppercase', () => {
+    it('uppercases the input', async () => {
+      const result = await client.callTool({
+        name: 'uppercase',
+        arguments: { text: 'hello' },
+      });
+      expect(contentText(result)).toBe('HELLO');
+    });
+
+    it('preserves non-letter characters', async () => {
+      const result = await client.callTool({
+        name: 'uppercase',
+        arguments: { text: 'abc 123!' },
+      });
+      expect(contentText(result)).toBe('ABC 123!');
+    });
+  });
+});

package/dist/templates/full-stack/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "rootDir": "./",
+    "declaration": true,
+    "sourceMap": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "scripts/**/*.ts", "examples/**/*.js"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/templates/minimal-jest/README.md

@@ -0,0 +1,42 @@
+# MCP Test Minimal — Starter Template
+
+The smallest working project that uses [`@slbdn/mcp-tester`](https://www.npmjs.com/package/@slbdn/mcp-tester) to test an MCP server.
+
+## What's included
+- A mock MCP server (`examples/mock-server.js`) with two tools: `echo` and `add`.
+- One Jest test file (`tests/server.test.ts`) that connects, lists, and calls.
+- TypeScript + `ts-jest` ESM configuration.
+- A `package.json` with everything you need.
+
+## Quick start
+
+```bash
+npm install
+npm test
+```
+
+You should see something like:
+
+```
+PASS  tests/server.test.ts
+  Mock MCP server
+    ✓ should connect to the server
+    ✓ should list at least one tool
+    ✓ should echo a message
+    ✓ should add two numbers
+```
+
+## Point this at your own server
+
+Replace `examples/mock-server.js` with your server (or update `tests/server.test.ts` to point at a real one):
+
+```ts
+await client.start({
+  command: 'node',
+  args: ['./path/to/your-server.js'],
+});
+```
+
+## Next steps
+- **Standard tests**: see `templates/standard-jest/` for tools/resources/prompts suites, fixtures, and CI.
+- **Generation**: see `templates/full-stack/` for `generateTests` / `generateTypes` integration.

package/dist/templates/minimal-jest/examples/mock-server.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+/**
+ * Minimal mock MCP server for testing.
+ *
+ * Tools:
+ *   - echo(message): echoes back the input message
+ *   - add(a, b): returns the sum of two numbers
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const server = new Server(
+  { name: 'mock-mcp-server', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'echo',
+      description: 'Echo back the input message',
+      inputSchema: {
+        type: 'object',
+        properties: { message: { type: 'string', description: 'Message to echo' } },
+        required: ['message'],
+      },
+    },
+    {
+      name: 'add',
+      description: 'Add two numbers',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          a: { type: 'number', description: 'First number' },
+          b: { type: 'number', description: 'Second number' },
+        },
+        required: ['a', 'b'],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  switch (name) {
+    case 'echo':
+      return { content: [{ type: 'text', text: String(args.message) }] };
+    case 'add': {
+      const sum = Number(args.a) + Number(args.b);
+      return { content: [{ type: 'text', text: String(sum) }] };
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/templates/minimal-jest/jest.config.js

@@ -0,0 +1,24 @@
+/** @type {import('jest').Config} */
+export default {
+  preset: 'ts-jest/presets/default-esm',
+  testEnvironment: 'node',
+  extensionsToTreatAsEsm: ['.ts'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        useESM: true,
+        tsconfig: {
+          esModuleInterop: true,
+          allowSyntheticDefaultImports: true,
+        },
+      },
+    ],
+  },
+  testMatch: ['**/tests/**/*.test.ts'],
+  testTimeout: 30000,
+  maxWorkers: 1,
+};

package/dist/templates/minimal-jest/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "__NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Minimal MCP server test scaffold using @slbdn/mcp-tester + Jest",
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@slbdn/mcp-tester": "^1.4.3",
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^30.5.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^5.3.0"
+  }
+}

package/dist/templates/minimal-jest/tests/server.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Minimal MCP server test scaffold.
+ *
+ * Demonstrates:
+ *   - Starting a stdio MCP server
+ *   - Listing tools
+ *   - Calling a tool
+ *   - Cleanup
+ */
+
+import { MCPClient, setupJestMatchers } from '@slbdn/mcp-tester';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const serverPath = join(here, '..', 'examples', 'mock-server.js');
+
+describe('Mock MCP server', () => {
+  let client: MCPClient;
+
+  beforeAll(async () => {
+    setupJestMatchers();
+    client = new MCPClient({
+      name: 'minimal-test',
+      version: '0.1.0',
+      timeout: 10000,
+    });
+    await client.start({
+      command: 'node',
+      args: [serverPath],
+    });
+  });
+
+  afterAll(async () => {
+    if (client?.isConnected()) {
+      await client.stop();
+    }
+  });
+
+  it('should connect to the server', () => {
+    expect(client.isConnected()).toBe(true);
+  });
+
+  it('should list at least one tool', async () => {
+    const tools = await client.listTools();
+    expect(tools.length).toBeGreaterThan(0);
+  });
+
+  it('should echo a message', async () => {
+    const result = await client.callTool({
+      name: 'echo',
+      arguments: { message: 'hello' },
+    });
+    expect(result).toReturnText('hello');
+  });
+
+  it('should add two numbers', async () => {
+    const result = await client.callTool({
+      name: 'add',
+      arguments: { a: 2, b: 3 },
+    });
+    expect(result).toReturnText('5');
+  });
+});

package/dist/templates/minimal-jest/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "rootDir": "./",
+    "declaration": true,
+    "sourceMap": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["tests/**/*.ts", "examples/**/*.js"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/templates/standard-jest/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v5
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v5
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      - name: Install
+        run: npm ci
+      - name: Test
+        run: npm test
+      - name: Upload HTML report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-report-${{ matrix.node-version }}
+          path: reports/
+          retention-days: 14

package/dist/templates/standard-jest/README.md

@@ -0,0 +1,44 @@
+# MCP Test Standard — Starter Template
+
+A "blessed" layout for testing MCP servers with [`@slbdn/mcp-tester`](https://www.npmjs.com/package/@slbdn/mcp-tester). Splits tests by capability, ships an HTML reporter, includes a CI workflow, and demonstrates richer mocking patterns.
+
+## What's included
+
+```
+standard-jest/
+├── examples/
+│   └── mock-server.js        # Stdio mock server: echo, add, slow, version resource, greet prompt
+├── tests/
+│   ├── helpers.ts            # Shared client setup
+│   ├── server.test.ts        # Lifecycle and health
+│   ├── tools.test.ts         # Tool listing, schemas, calls (incl. timeout)
+│   ├── resources.test.ts     # Resource listing and reads
+│   └── prompts.test.ts       # Prompt listing and gets
+├── .github/workflows/
+│   └── test.yml              # CI matrix (Node 20, 22) + HTML report upload
+├── jest.config.js
+├── tsconfig.json
+└── package.json
+```
+
+## Quick start
+
+```bash
+npm install
+npm test
+```
+
+Open `reports/test-report.html` for the visual report.
+
+## What's different from `minimal-jest`
+- **Test split**: separate files per capability for clearer failure attribution.
+- **HTML reporter**: jest-html-reporters preconfigured.
+- **Coverage**: `npm run test:coverage` runs with text/lcov reporters.
+- **CI workflow**: GitHub Actions matrix on Node 20 and 22.
+- **Timeout testing**: demonstrates `timeout` per-call option.
+
+## Point this at your own server
+Replace `examples/mock-server.js` with your server, or update `tests/helpers.ts` to point at it.
+
+## Next steps
+- **Full stack**: see `templates/full-stack/` for code generation (`generateTests` / `generateTypes`) and typed tool calls.

package/dist/templates/standard-jest/examples/mock-server.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * Standard mock MCP server — used by all test files in this template.
+ *
+ * Tools:
+ *   - echo(message): returns the input message
+ *   - add(a, b): returns the sum
+ *   - slow(ms): waits N ms then returns (good for timeout tests)
+ *
+ * Resources:
+ *   - config://version: returns "1.0.0"
+ *
+ * Prompts:
+ *   - greet(user): returns a greeting
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+const server = new Server(
+  { name: 'standard-mock-server', version: '1.0.0' },
+  { capabilities: { tools: {}, resources: {}, prompts: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'echo',
+      description: 'Echo back the input message',
+      inputSchema: {
+        type: 'object',
+        properties: { message: { type: 'string' } },
+        required: ['message'],
+      },
+    },
+    {
+      name: 'add',
+      description: 'Add two numbers',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          a: { type: 'number' },
+          b: { type: 'number' },
+        },
+        required: ['a', 'b'],
+      },
+    },
+    {
+      name: 'slow',
+      description: 'A slow tool for testing timeouts',
+      inputSchema: {
+        type: 'object',
+        properties: { ms: { type: 'number', default: 100 } },
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [
+    {
+      uri: 'config://version',
+      name: 'version',
+      description: 'Server version',
+      mimeType: 'text/plain',
+    },
+  ],
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  if (request.params.uri === 'config://version') {
+    return { contents: [{ uri: 'config://version', mimeType: 'text/plain', text: '1.0.0' }] };
+  }
+  throw new Error(`Unknown resource: ${request.params.uri}`);
+});
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  prompts: [
+    {
+      name: 'greet',
+      description: 'Greet a user by name',
+      arguments: [{ name: 'user', description: 'Name', required: true }],
+    },
+  ],
+}));
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  if (request.params.name === 'greet') {
+    const user = String(request.params.arguments?.user ?? 'world');
+    return {
+      messages: [{ role: 'assistant', content: { type: 'text', text: `Hello, ${user}!` } }],
+    };
+  }
+  throw new Error(`Unknown prompt: ${request.params.name}`);
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  switch (name) {
+    case 'echo':
+      return { content: [{ type: 'text', text: String(args.message) }] };
+    case 'add':
+      return { content: [{ type: 'text', text: String(Number(args.a) + Number(args.b)) }] };
+    case 'slow':
+      await new Promise((r) => setTimeout(r, Number(args.ms ?? 100)));
+      return { content: [{ type: 'text', text: `waited ${args.ms ?? 100}ms` }] };
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/templates/standard-jest/jest.config.js

@@ -0,0 +1,39 @@
+/** @type {import('jest').Config} */
+export default {
+  preset: 'ts-jest/presets/default-esm',
+  testEnvironment: 'node',
+  cacheDirectory: '/tmp/mcp-tester-cache',
+  extensionsToTreatAsEsm: ['.ts'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        useESM: true,
+        tsconfig: {
+          esModuleInterop: true,
+          allowSyntheticDefaultImports: true,
+        },
+      },
+    ],
+  },
+  testMatch: ['**/tests/**/*.test.ts'],
+  testTimeout: 30000,
+  maxWorkers: 1,
+  reporters: [
+    'default',
+    [
+      'jest-html-reporters',
+      {
+        publicPath: './reports',
+        filename: 'test-report.html',
+        expand: true,
+        pageTitle: 'MCP Test Report',
+        hideIcon: true,
+      },
+    ],
+  ],
+  coverageReporters: ['text', 'text-summary', 'lcov'],
+};

package/dist/templates/standard-jest/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "__NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Standard MCP server test scaffold using @slbdn/mcp-tester + Jest (tools, resources, prompts, fixtures, CI)",
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+    "test:report": "node --experimental-vm-modules node_modules/jest/bin/jest.js --reporters=default --reporters=jest-html-reporters"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@slbdn/mcp-tester": "^1.4.3",
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^30.5.2",
+    "jest-html-reporters": "^3.0.11",
+    "ts-jest": "^29.4.11",
+    "typescript": "^5.3.0"
+  }
+}

package/dist/templates/standard-jest/tests/helpers.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared test helpers: path resolution and per-suite client lifecycle.
+ */
+
+import { MCPClient } from '@slbdn/mcp-tester';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+export const serverPath = join(here, '..', 'examples', 'mock-server.js');
+
+/** The result type of {@link MCPClient.callTool}. */
+type ToolCallResult = Awaited<ReturnType<MCPClient['callTool']>>;
+
+/** Extract the text of the first content item (empty string if not text). */
+export function contentText(result: ToolCallResult): string {
+  const first = result.content[0];
+  return first && first.type === 'text' ? first.text : '';
+}
+
+/** Extract the text of the first prompt message (empty string if not text). */
+export function promptText(result: Awaited<ReturnType<MCPClient['getPrompt']>>): string {
+  const first = result.messages[0];
+  const content = first?.content;
+  return content && content.type === 'text' ? content.text : '';
+}
+
+/** Extract the text of the first resource contents entry (empty string if not text). */
+export function resourceText(result: Awaited<ReturnType<MCPClient['readResource']>>): string {
+  const first = result.contents[0];
+  return first && 'text' in first ? (first.text as string) : '';
+}
+
+/** Create a connected MCPClient pointed at the standard mock server. */
+export async function createConnectedClient(name = 'standard-test'): Promise<MCPClient> {
+  const client = new MCPClient({
+    name,
+    version: '0.1.0',
+    timeout: 10000,
+  });
+  await client.start({ command: 'node', args: [serverPath] });
+  return client;
+}

package/dist/templates/standard-jest/tests/prompts.test.ts

@@ -0,0 +1,37 @@
+/**
+ * Prompt tests.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from '@jest/globals';
+import type { MCPClient } from '@slbdn/mcp-tester';
+import { contentText, createConnectedClient, promptText, resourceText } from './helpers.js';
+
+describe('Prompts', () => {
+  let client: MCPClient;
+
+  beforeAll(async () => {
+    client = await createConnectedClient('prompts-test');
+  });
+
+  afterAll(async () => {
+    if (client?.isConnected()) {
+      await client.stop();
+    }
+  });
+
+  it('lists available prompts', async () => {
+    const prompts = await client.listPrompts();
+    expect(prompts.map((p) => p.name)).toContain('greet');
+  });
+
+  it('gets the greet prompt with arguments', async () => {
+    const result = await client.getPrompt('greet', { user: 'Alice' });
+    expect(result.messages.length).toBeGreaterThan(0);
+    const text = promptText(result);
+    expect(text).toContain('Alice');
+  });
+
+  it('rejects unknown prompts', async () => {
+    await expect(client.getPrompt('unknown-prompt')).rejects.toThrow();
+  });
+});