@slbdn/mcp-tester 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -5,12 +5,119 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.4.0] - 2026-07-01
+
+### Added
+- **HTTP and SSE transport support** — connect to remote MCP servers:
+  - `StreamableHttpServerConfig` (`transport: 'http'`) — modern MCP Streamable HTTP (POST + SSE GET)
+  - `SseServerConfig` (`transport: 'sse'`) — legacy SSE transport
+  - `ServerConfig` union type — `StdioServerConfig | StreamableHttpServerConfig | SseServerConfig`
+  - `getTransportType()` method — returns `'stdio'`, `'http'`, `'sse'`, or `null`
+  - URL auto-detection in CLI (passing a URL as first arg uses HTTP transport)
+  - CLI `--transport`, `--url`, `--headers` options on all commands
+  - 15 integration tests (Streamable HTTP + SSE) against server-everything
+  - 5 CLI HTTP transport tests
+  - 14 validation tests for HTTP/SSE configs
+
+### Changed
+- `MCPServerConfig` is now a deprecated alias for `StdioServerConfig` (backward compatible)
+- `start()` accepts the `ServerConfig` discriminated union instead of `MCPServerConfig`
+- CLI commands now accept `[command]` (optional) instead of `<command>` to support HTTP/SSE
+
+## [1.3.0] - 2026-07-01
+
+### Added
+- **TypeScript type generator** (`src/generate-types.ts`) — generate typed `.d.ts` from MCP tool schemas:
+  - `generateTypes()` API: connect to server, inspect schemas, emit TypeScript declarations
+  - CLI: `npx mcp-tester generate-types node ./server.js -o server.d.ts`
+  - Handles: primitives, enums, arrays, nested objects, oneOf/anyOf/allOf, $ref, const
+  - Generated types: `{Tool}Args`, `ToolName`, `ToolArgsMap`, `ToolCall`, `ResourceUri`, `PromptCall`
+  - 59 tests (12 e2e + 4 options + 43 unit)
+- **Server health checks** — detect zombie processes and monitor server health:
+  - `isHealthy()` — sends a lightweight `tools/list` ping, returns `HealthStatus` with latency, PID, message
+  - `getServerPid()` — get the server process PID
+  - `getLastHealthStatus()` — cached result without re-checking
+  - `startHealthMonitor(options)` — periodic health monitoring with `onUnhealthy`/`onRecovery`/`onCheck` callbacks
+  - `stopHealthMonitor()` — stop periodic monitoring (also auto-stopped by `client.stop()`)
+  - Zombie process detection via `process.kill(pid, 0)`
+  - 17 tests (including SIGKILL zombie detection test)
+- **Enhanced mock server** (`src/__tests__/fixtures/mock-server.ts`) — 68 tests:
+  - Configurable delays (`defaultDelay`) and random failures (`failureRate`)
+  - Input schema validation (`validateSchemas` option)
+  - Stateful tools: `counter` (increment/get/reset), `items` (add/list/remove/clear)
+  - Transform tool: `upper`/`lower`/`reverse`/`length` operations
+  - Custom handlers: `registerToolHandler`, `registerResourceHandler`, `registerPromptHandler`
+  - Call history: `getCallHistory`, `getCallCount` for test assertions
+  - Streaming support: `setupStream`, `nextStreamChunk`
+  - Dynamic registration/removal of tools, resources, prompts
+
+### Changed
+- **CLI version** is now read dynamically from `package.json` (was hardcoded `1.0.0`)
+- Applied safe dependency patches: `@typescript-eslint/*` 8.60.0, `@types/node` 20.19.41, `prettier` 3.8.3, `ts-jest` 29.4.11
+- `npm audit fix` — 0 vulnerabilities (was 11)
+
+### Test Suite
+- **635 tests** (17 suites), up from 491 (14 suites)
+- New: mock server (68), generate-types (59), health checks (17)
+
 ## [1.2.0] - 2026-04-30
 
 ### Added
+- **Visual test reports** — HTML test report auto-generated on every `npm test` run:
+  - Uses `jest-html-reporters` with collapsible test trees, timing, failure details
+  - Report saved to `reports/test-report.html`
+  - CI uploads report as artifact (14-day retention)
+  - Open locally: `open reports/test-report.html`
+- **Property-based tests** (`src/__tests__/property-based.test.ts`) — 73 tests using fast-check:
+  - 44 validation tests: reject/accept all input types, error code invariants
+  - 17 masking tests: idempotency, completeness, secret detection, length bounds
+  - 12 generate-tests tests: no-throw, serializability, schema priority, nested arrays
+  - Fixed flaky `fc.double()` producing NaN/Infinity → use `fc.integer()` for numeric fields
+- **Enhanced mock server** (`src/__tests__/fixtures/mock-server.ts`) — 68 tests:
+  - Configurable delays (`defaultDelay`) and random failures (`failureRate`)
+  - Input schema validation (`validateSchemas` option)
+  - Stateful tools: `counter` (increment/get/reset), `items` (add/list/remove/clear)
+  - Transform tool: `upper`/`lower`/`reverse`/`length` operations
+  - Custom handlers: `registerToolHandler`, `registerResourceHandler`, `registerPromptHandler`
+  - Call history: `getCallHistory`, `getCallCount` for test assertions
+  - Streaming support: `setupStream`, `nextStreamChunk`
+  - Dynamic registration/removal of tools, resources, prompts
+- **TypeScript type generator** (`src/generate-types.ts`) — generate typed `.d.ts` from MCP tool schemas:
+  - `generateTypes()` API: connect to server, inspect schemas, emit TypeScript declarations
+  - CLI: `npx mcp-tester generate-types node ./server.js -o server.d.ts`
+  - Handles: primitives, enums, arrays, nested objects, oneOf/anyOf/allOf, $ref, const
+  - Generated types: `{Tool}Args`, `ToolName`, `ToolArgsMap`, `ToolCall`, `ResourceUri`, `PromptCall`
+  - 59 tests (12 e2e + 4 options + 43 unit)
+- **Server health checks** — detect zombie processes and monitor server health:
+  - `isHealthy()` — sends a lightweight `tools/list` ping, returns `HealthStatus` with latency, PID, message
+  - `getServerPid()` — get the server process PID
+  - `getLastHealthStatus()` — cached result without re-checking
+  - `startHealthMonitor(options)` — periodic health monitoring with `onUnhealthy`/`onRecovery`/`onCheck` callbacks
+  - `stopHealthMonitor()` — stop periodic monitoring (also auto-stopped by `client.stop()`)
+  - Zombie process detection via `process.kill(pid, 0)`
+  - 17 tests (including SIGKILL zombie detection test)
+- **Test code generator** (`src/generate-tests.ts`) — generate a complete test file from MCP server inspection:
+  - CLI: `mcp-tester generate node ./server.js -o server.test.ts` (alias: `gen`)
+  - API: `generateTests({ command, args, framework, ... })`
+  - Generates lifecycle tests, tool call tests with sample args from JSON Schema, resource read tests, prompt tests
+  - Options: `--framework jest|vitest`, `--output <file>`, `--description <name>`, `--no-tools`, `--no-resources`, `--no-prompts`, `--no-matchers`
+  - Sample arguments derived from JSON Schema: types, enums, defaults, examples
+  - 21 tests in `generate-tests.test.ts`
+- **Input validation** (`src/utils/validation.ts`) — all MCPClient methods validate inputs before execution:
+  - `start()`: validates command (required string), args (string array), env (string values), startupDelay (non-negative number)
+  - `callTool()`: validates name (required string), arguments (object), timeout (positive number), retries (non-negative number)
+  - `readResource()`: validates URI (required non-empty string)
+  - `getPrompt()`: validates name (required string), args (string values)
+  - `requestSampling()`: validates messages (non-empty array)
+  - Constructor: validates timeout (positive), retries/retryDelay/startupDelay (non-negative), name/version (string)
+  - Validation runs before connection checks — invalid args throw `MCPClientError`, not `MCPNotStartedError`
+  - 91 tests in `validation.test.ts`
 - **Code coverage comments on PRs** — GitHub Actions workflow now posts a coverage table as a sticky comment on every pull request (statements/branches/functions/lines with thresholds)
 - **Dedicated `coverage` CI job** — runs on single Node.js version (faster than matrix), generates `coverage-summary.json`, uploads to Codecov v4
 - **`coverageReporters`** in `jest.config.js` — added `json-summary` reporter for CI coverage data extraction
+- **VS Code snippets** (`.vscode/mcp-tester.code-snippets`) — 15 snippets for MCP test patterns (type `mcp` prefix)
 
 ### Changed
 - **Per-file coverage thresholds** updated for new files (`masking.ts`, `logger.ts`) and actual coverage numbers
@@ -20,6 +127,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **docs/testing.md** — updated coverage thresholds (was "80%", now per-file table)
 - **AGENTS.md** — updated test count, coverage stats, CI job descriptions, file listing
 - Fixed flaky `delay` test (100ms → 90ms tolerance for timing variance)
+- **Updated test count**: 491 (was 306)
 
 ## [1.1.0] - 2026-04-23
 

package/README.md

@@ -8,7 +8,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@slbdn/mcp-tester)](https://www.npmjs.com/package/@slbdn/mcp-tester)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Test Status](https://img.shields.io/badge/tests-306%20passing-brightgreen)](https://github.com/islobodan/mcp-tester/actions/workflows/test.yml)
+[![Test Status](https://img.shields.io/badge/tests-669%20passing-brightgreen)](https://github.com/islobodan/mcp-tester/actions/workflows/test.yml)
 [![Coverage](https://img.shields.io/badge/coverage-68%2F61%2F60%2F68-brightgreen)](https://github.com/islobodan/mcp-tester/actions/workflows/test.yml)  <!-- statements/branches/functions/lines -->
 
 A production-ready MCP (Model Context Protocol) client for **automated testing** of MCP servers with Jest.
@@ -50,7 +50,7 @@ No more manual clicking through inspectors — write real tests, run them in CI,
 │  │  │    MCPTimeoutError │ MCPConnectionError │ ...        │    │    │
 │  │  └──────────────────────┬───────────────────────────────┘    │    │
 │  └─────────────────────────┼─────────────────────────────────────┘    │
-│                            │ stdio (JSON-RPC)                        │
+│                            │ stdio, HTTP, SSE                        │
 │  ┌─────────────────────────▼─────────────────────────────────────┐  │
 │  │              MCP Server (child process)                       │  │
 │  │  ┌────────┐  ┌───────────┐  ┌──────────┐  ┌────────────┐   │  │
@@ -60,9 +60,9 @@ No more manual clicking through inspectors — write real tests, run them in CI,
 └─────────────────────────────────────────────────────────────────────┘
 ```
 
-**Data flow**: Your test calls `MCPClient` → which sends JSON-RPC over stdio → to the MCP server process → server responds → `MCPClient` returns typed results → your assertion validates them.
+**Data flow**: Your test calls `MCPClient` → which sends JSON-RPC over stdio/HTTP/SSE → to the MCP server → server responds → `MCPClient` returns typed results → your assertion validates them.
 
-**Key design**: `MCPClient` manages the server lifecycle (spawn/kill) and protocol handling. Your tests never deal with the transport layer directly.
+**Key design**: `MCPClient` manages the server lifecycle (spawn/kill for stdio, connect/disconnect for HTTP/SSE) and protocol handling. Your tests never deal with the transport layer directly.
 
 ## Why MCP Tester?
 
@@ -84,10 +84,22 @@ No more manual clicking through inspectors — write real tests, run them in CI,
 | Branches | 61% |
 | Functions | 60% |
 | Lines | 68% |
-| Tests | 306 passing |
+| Tests | 669 passing |
 
 Per-file coverage thresholds are set in `jest.config.js` to catch regressions while avoiding CI noise. Run `npm run test:coverage` to see the full breakdown by file. PRs automatically receive a coverage comment via GitHub Actions.
 
+## Test Reports
+
+Every `npm test` run auto-generates an HTML test report:
+
+```bash
+npm test                # generates reports/test-report.html
+open reports/test-report.html   # macOS
+xdg-open reports/test-report.html  # Linux
+```
+
+The report includes collapsible test trees, timing per test, and failure details with stack traces. CI uploads reports as artifacts (14-day retention).
+
 ## Install
 
 ```bash
@@ -124,6 +136,22 @@ const result = await client.callTool({
 await client.stop();
 ```
 
+### Connect via HTTP
+
+```typescript
+// Streamable HTTP transport (recommended for remote servers)
+await client.start({
+  transport: 'http',
+  url: 'https://api.example.com/mcp',
+});
+
+// Legacy SSE transport
+await client.start({
+  transport: 'sse',
+  url: 'http://localhost:3000/sse',
+});
+```
+
 ### Test with Jest
 
 ```typescript
@@ -173,12 +201,90 @@ npx @slbdn/mcp-tester list-tools node ./server.js --json
 # Call a tool
 npx @slbdn/mcp-tester call-tool echo node ./server.js --params '{"message":"Hello"}'
 
-# Short aliases: lt, ct, rr, gp
+# Generate test file from server inspection
+npx @slbdn/mcp-tester generate node ./server.js -o server.test.ts
+npx @slbdn/mcp-tester gen node ./server.js --framework vitest --no-resources
+
+# Short aliases: lt, ct, rr, gp, gen
 npx @slbdn/mcp-tester lt node ./server.js
 ```
 
 See [CLI Reference](./docs/cli.md) for all commands and options.
 
+### Generate Test Files
+
+Connect to any MCP server and generate a ready-to-run test file:
+
+```bash
+# Generate Jest test file
+npx @slbdn/mcp-tester generate node ./server.js -o server.test.ts
+
+# Generate Vitest test file
+npx @slbdn/mcp-tester gen node ./server.js --framework vitest
+
+# Skip specific sections
+npx @slbdn/mcp-tester generate node ./server.js --no-resources --no-prompts -o tools-only.test.ts
+```
+
+Or use the API:
+
+```typescript
+import { generateTests } from '@slbdn/mcp-tester';
+
+const code = await generateTests({
+  command: 'node',
+  args: ['./server.js'],
+  framework: 'jest',
+  description: 'My Server Tests',
+});
+
+fs.writeFileSync('server.test.ts', code);
+```
+
+The generator connects to the server, inspects all tools/resources/prompts, and generates:
+- Connection and lifecycle tests
+- Tool call tests with **sample arguments derived from JSON Schema**
+- Resource read tests
+- Prompt tests with sample arguments
+- Proper `beforeEach`/`afterEach` cleanup
+
+### Generate TypeScript Types
+
+Connect to any MCP server and generate typed `.d.ts` declarations from tool schemas:
+
+```bash
+# Generate TypeScript types
+npx @slbdn/mcp-tester generate-types node ./server.js -o server.d.ts
+```
+
+Or use the API:
+
+```typescript
+import { generateTypes } from '@slbdn/mcp-tester';
+import { writeFileSync } from 'fs';
+
+const types = await generateTypes({
+  command: 'node',
+  args: ['./server.js'],
+});
+
+writeFileSync('server.d.ts', types);
+```
+
+This produces typed interfaces you can use for type-safe tool calls:
+
+```typescript
+import type { ToolArgsMap } from './server.d.ts';
+
+// TypeScript knows: { a: number; b: number }
+const result = await client.callTool({
+  name: 'add',
+  arguments: { a: 1, b: 2 } as ToolArgsMap['add'],
+});
+```
+
+Supports: primitives, enums, nested objects, arrays, `oneOf`/`anyOf`/`allOf`, `$ref`, `const`.
+
 ## Speed Up Your Tests with Parallel Execution
 
 MCP Tester is built for concurrency. Fire off multiple tool calls at once — no waiting in line:
@@ -216,6 +322,10 @@ No extra config needed. Just `Promise.all` and go.
 | `start(config)` | `Promise<void>` | Connect to an MCP server |
 | `stop()` | `Promise<void>` | Disconnect and clean up |
 | `isConnected()` | `boolean` | Check connection state |
+| `isHealthy()` | `Promise<HealthStatus>` | Check server health and responsiveness |
+| `getServerPid()` | `number | null` | Get server process PID |
+| `startHealthMonitor(opts)` | `void` | Start periodic health monitoring |
+| `stopHealthMonitor()` | `void` | Stop health monitoring |
 | `listTools()` | `Promise<Tool[]>` | List available tools |
 | `callTool(options)` | `Promise<CallToolResult>` | Call a tool with arguments |
 | `listResources()` | `Promise<Resource[]>` | List available resources |
@@ -228,6 +338,25 @@ No extra config needed. Just `Promise.all` and go.
 
 See [API Reference](./docs/api-reference.md) for full details including types, options, and error classes.
 
+## Server Health Checks
+
+Detect crashed servers and zombie processes during long test runs:
+
+```typescript
+// One-time check
+const health = await client.isHealthy();
+console.log(`Healthy: ${health.healthy}, PID: ${health.pid}, latency: ${health.latencyMs}ms`);
+
+// Periodic monitoring
+client.startHealthMonitor({
+  interval: 3000,
+  onUnhealthy: (status) => console.error('Server down:', status.message),
+  onRecovery: (status) => console.log('Server recovered!'),
+});
+```
+
+Health checks detect zombie processes (killed/crashed but `isConnected()` still returns `true`) using `process.kill(pid, 0)`.
+
 ## Custom Jest Matchers
 
 Built-in matchers so your assertions read like English:
@@ -390,7 +519,7 @@ mcp-tester/
 npm install          # Install dependencies
 npm run build        # Compile TypeScript
 npm run dev          # Watch mode — auto-rebuild on source changes
-npm test             # Run tests (306 tests)
+npm test             # Run tests (auto-generates reports/test-report.html)
 npm run lint         # Lint code
 npm run format       # Format with Prettier
 ```
@@ -476,6 +605,30 @@ prettyPrint({ apiKey: 'sk-proj-abc123...', count: 42 });
 
 See [Troubleshooting Guide](./docs/troubleshooting.md) for more details.
 
+## VS Code Snippets
+
+Type `mcp` in any TypeScript file to get started — 15 built-in snippets:
+
+| Prefix | Inserts |
+|--------|--------|
+| `mcp-test` | Full test suite with lifecycle setup |
+| `mcp-tool` | Tool call test + assertion |
+| `mcp-resource` | Resource read test |
+| `mcp-prompt` | Prompt get test |
+| `mcp-client` | `new MCPClient()` + `start()` |
+| `mcp-client-opts` | Client with timeout, retries, log level |
+| `mcp-error` | Error handling test (`rejects.toThrow`) |
+| `mcp-parallel` | `Promise.all` parallel tool calls |
+| `mcp-list-tools` | List tools + `toHaveTool` assertion |
+| `mcp-list-resources` | List resources + `toHaveResource` assertion |
+| `mcp-list-prompts` | List prompts + `toHavePrompt` assertion |
+| `mcp-assert-text` | `assert.toolTextEquals()` |
+| `mcp-assert-json` | `assert.toolJsonEquals()` |
+| `mcp-notifications` | Notification handler setup |
+| `mcp-import` / `mcp-import-full` | Import statements |
+
+Snippets are in `.vscode/mcp-tester.code-snippets` — works out of the box when you open the project in VS Code.
+
 ## Contributing
 
 1. Fork the repository