@slbdn/mcp-tester 1.5.4 → 1.6.0

package/docs/browser.md

@@ -0,0 +1,138 @@
+# Browser Support
+
+`mcp-tester` can run inside browser and edge runtimes to test MCP servers over
+network transports. This is useful for:
+
+- Component/unit tests that run in a real browser (Vitest browser mode, Karma,
+  Playwright component testing, Web Test Runner).
+- In-browser debugging or smoke checks of a remote MCP server.
+- Edge runtimes (Cloudflare Workers, Deno Deploy, Vercel Edge) that expose
+  `fetch` and `WebSocket`.
+
+## How it works
+
+The package declares a `browser` field in `package.json`:
+
+```json
+"browser": {
+  "./dist/index.js": "./dist/browser.js",
+  "./dist/utils/stdio-transport.js": false
+}
+```
+
+When a bundler targets the browser it resolves the package entry to
+`dist/browser.js` and replaces the Node-only stdio transport with an empty
+module. You import the package exactly as you would on Node:
+
+```typescript
+import { MCPClient, assert } from '@slbdn/mcp-tester';
+
+const client = new MCPClient();
+await client.start({ transport: 'http', url: 'https://api.example.com/mcp' });
+
+const result = await client.callTool({ name: 'echo', arguments: { message: 'hi' } });
+assert.toolTextContains(result, 'hi');
+
+await client.stop();
+```
+
+Webpack, Vite, Rollup, esbuild, Parcel, and Rspack all honor the `browser`
+field. The repository's CI runs `npm run test:browser`, which bundles the
+package with esbuild using `platform: 'browser'` and fails if any Node built-in
+(`node:*`) or the stdio transport (`cross-spawn`) leaks into the bundle.
+
+## Transports
+
+| Transport | Browser | Notes |
+|-----------|:-------:|-------|
+| `http` (Streamable HTTP) | ✅ | Uses `fetch` + `ReadableStream`. Recommended for remote servers. |
+| `sse` (legacy) | ✅ | Uses `fetch` + `EventSource` semantics. |
+| `websocket` | ✅ | Uses the global `WebSocket` API. |
+| `stdio` | ❌ | Spawns a local process; Node.js only. |
+
+### Streamable HTTP
+
+```typescript
+await client.start({
+  transport: 'http',
+  url: 'https://api.example.com/mcp',
+  headers: { Authorization: 'Bearer token' },
+});
+```
+
+### WebSocket
+
+```typescript
+await client.start({
+  transport: 'websocket',
+  url: 'wss://api.example.com/mcp',
+});
+```
+
+The client connects using the `mcp` WebSocket subprotocol, matching the MCP
+SDK's `WebSocketClientTransport`.
+
+> **Node.js note:** the WebSocket transport needs a global `WebSocket`.
+> Node.js 22+ provides one. On older Node versions use `--experimental-websocket`
+> or a polyfill such as [`ws`](https://www.npmjs.com/package/ws) installed on
+> `globalThis`.
+
+## What is included
+
+The browser entry point (`dist/browser.js`) exports the browser-safe subset:
+
+- `MCPClient` and all client types (`ServerConfig`, `StreamableHttpServerConfig`,
+  `SseServerConfig`, `WebSocketServerConfig`, `MCPClientOptions`, `HealthStatus`, …)
+- Custom matchers (`toHaveTool`, `toReturnText`, `setupVitestMatchers`, …)
+- The `assert` module
+- Error classes (`MCPClientError`, `MCPTimeoutError`, …)
+- Logging/masking utilities (`startTimer`, `prettyPrint`, `maskSecrets`, …)
+- The deterministic edge-case generator (`suggestEdgeCases`, `generateToolArgs`, …)
+
+## What is Node-only
+
+These are intentionally excluded and tree-shaken from browser bundles:
+
+- **stdio transport** — spawns a child process via `cross-spawn`.
+- **`generateTests` / `generateTypes`** — read/write files and read the package
+  version from disk.
+- **AI provider** (`OpenAICompatProvider`, `createProviderFromEnv`) — uses
+  `node:crypto`, `node:fs`, and `node:path`.
+
+If you need test generation in a browser workflow, generate the files in a Node
+step (CLI or script) and run the generated tests in the browser.
+
+## Limitations
+
+- **No stdio.** Browsers cannot spawn processes. Use `http`, `sse`, or
+  `websocket`.
+- **CORS applies.** The MCP server must send appropriate
+  `Access-Control-Allow-Origin` headers (and allow the `mcp-session-id` header
+  for Streamable HTTP). This is a browser/network constraint, not a limitation
+  of this library.
+- **File-based caching is unavailable.** The AI provider (Node-only) writes a
+  cache to disk; in-browser code paths do not touch the filesystem.
+- **`process`-based features degrade gracefully.** Health checks for stdio PIDs
+  return `null`, and logging falls back to a non-TTY format.
+
+## Testing from Node
+
+You can exercise the browser-safe entry point from Node without a browser. The
+repository's `test:browser` script is a good template; a focused version is:
+
+```js
+import { build } from 'esbuild';
+
+await build({
+  entryPoints: ['src/entry.ts'],
+  bundle: true,
+  platform: 'browser',
+  format: 'esm',
+  outfile: 'out.js',
+});
+```
+
+If the bundle succeeds, no Node built-ins were pulled in.
+
+See also: [Starter Templates](./starter-templates.md) and
+[Testing](./testing.md).

package/docs/cicd.md

@@ -39,6 +39,9 @@ jobs:
       - name: Build TypeScript
         run: npm run build
 
+      - name: Check browser bundle
+        run: npm run test:browser
+
       - name: Run tests
         run: npm test
 

package/docs/cli.md

@@ -10,7 +10,7 @@ npx @slbdn/mcp-tester test node ./server.js
 
 ## Transports
 
-The CLI supports three transport types:
+The CLI supports four transport types:
 
 ### Stdio (default)
 
@@ -43,6 +43,19 @@ mcp-tester test --transport http --url https://api.example.com/mcp --headers '{"
 mcp-tester test --transport sse --url http://localhost:3000/sse
 ```
 
+### WebSocket
+
+```bash
+mcp-tester test --transport websocket --url ws://localhost:3000
+```
+
+A `ws://` or `wss://` URL passed as the first argument is auto-detected as the
+WebSocket transport:
+
+```bash
+mcp-tester test wss://api.example.com/mcp
+```
+
 ## Commands
 
 ### `test` — Test Server Connection

package/docs/nodejs-compatibility.md

@@ -6,8 +6,8 @@
 |----------------|--------|-------|
 | 18.x | ⚠️ Not Supported | ESM limitations — upgrade recommended |
 | 20.x (LTS) | ✅ Fully Supported | **Recommended** (minimum required version) |
-| 21.x | ✅ Fully Supported | Latest stable |
-| 22.x+ | ✅ Compatible | Tested, works |
+| 21.x | ⚠️ Not Supported | End-of-life; dropped from the test matrix in 1.5.2 |
+| 22.x+ | ✅ Fully Supported | Latest LTS, tested |
 
 ## Requirements
 
@@ -36,6 +36,20 @@ Targets TypeScript 5.3+ with ES2022 output.
 - ✅ Linux (Ubuntu, Debian, CentOS, Alpine)
 - ✅ Windows 10/11 (via WSL or native Node.js)
 
+## Browser and Edge Runtimes
+
+Modern browsers and edge runtimes (Cloudflare Workers, Deno Deploy, Vercel
+Edge) are supported for the network transports:
+
+| Runtime | stdio | http | sse | websocket |
+|---------|:-----:|:----:|:---:|:---------:|
+| Node.js ≥ 20 | ✅ | ✅ | ✅ | ✅ (global `WebSocket` on ≥ 22) |
+| Browsers | ❌ | ✅ | ✅ | ✅ |
+| Edge runtimes | ❌ | ✅ | ✅ | ✅ |
+
+Bundlers select the browser entry point automatically via the `browser` field.
+See [Browser Support](./browser.md) for details.
+
 ## CI/CD Version Specification
 
 **GitHub Actions:**

package/docs/testing.md

@@ -8,6 +8,7 @@ Guide to writing and running tests with MCP Tester.
 npm test                # Run all tests
 npm run test:watch      # Watch mode (auto-rerun on changes)
 npm run test:coverage   # Run with coverage report
+npm run test:browser    # Bundle-check the browser build (esbuild)
 npm run lint            # Lint code
 ```
 
@@ -20,6 +21,8 @@ src/__tests__/
 ├── advanced.test.ts             # Sampling, elicitation
 ├── real-server.test.ts          # Integration tests (stdio transport)
 ├── everything-server.test.ts    # Full integration (server-everything)
+├── http-transport.test.ts       # Streamable HTTP / SSE transport
+├── websocket-transport.test.ts  # WebSocket transport (in-process double)
 ├── cli.test.ts                  # CLI tool tests
 └── fixtures/
     └── mock-server.ts           # In-memory mock MCP server

package/docs/troubleshooting.md

@@ -114,8 +114,8 @@ Coverage thresholds: **80%** for branches, functions, lines, and statements.
 
 ## Known Limitations
 
-- Supports **stdio**, **Streamable HTTP**, and **SSE** transports
-- Designed for **Node.js** servers (other runtimes may need adjustments)
+- Supports **stdio**, **Streamable HTTP**, **SSE**, and **WebSocket** transports
+- Node.js by default; the HTTP/SSE/WebSocket transports also run in browsers and edge runtimes (see [Browser Support](./browser.md))
 - Mock server has configurable delays, failures, stateful tools, and validation
 
 ## Vitest
@@ -137,3 +137,24 @@ If you get TypeScript errors with custom matchers, make sure your `tsconfig.json
   "include": ["node_modules/@slbdn/mcp-tester/vitest.d.ts"]
 }
 ```
+
+## Browser and Edge Runtimes
+
+**"Module not found: node:child_process" / "cross-spawn" in a browser build**
+Your bundler is not honouring the `browser` field. Ensure it targets `browser`
+(Webpack `target: 'web'`, Vite `build.target` not `ssr`, esbuild
+`platform: 'browser'`). The repo's `npm run test:browser` script is a minimal
+reference. Do not import `@slbdn/mcp-tester/dist/...` deep paths — import the
+package root so the browser entry point is selected.
+
+**"WebSocket is not defined" (Node.js)**
+The WebSocket transport needs a global `WebSocket`. Node.js 22+ provides one;
+on older versions enable it with `--experimental-websocket` or set a polyfill
+such as `ws` on `globalThis`.
+
+**CORS errors against a remote MCP server**
+The server must allow your origin and, for Streamable HTTP, the
+`mcp-session-id` header. This is a browser/network constraint — configure the
+server, not the client.
+
+See [Browser Support](./browser.md) for the full matrix.

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@slbdn/mcp-tester",
-  "version": "1.5.4",
+  "version": "1.6.0",
   "description": "Minimal MCP client implementation for CI/CD testing of MCP servers",
   "main": "dist/index.js",
+  "browser": {
+    "./dist/index.js": "./dist/browser.js",
+    "./dist/utils/stdio-transport.js": false
+  },
   "types": "dist/index.d.ts",
   "type": "module",
   "sideEffects": false,
@@ -24,6 +28,7 @@
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
     "test:package": "node scripts/smoke-test-package.mjs",
+    "test:browser": "node scripts/check-browser-bundle.mjs",
     "benchmark": "tsx src/__tests__/benchmarks.ts",
     "lint": "eslint src --ext .ts",
     "format": "prettier --write \"src/**/*.ts\"",
@@ -77,6 +82,7 @@
     "@types/node": "^20.19.41",
     "@typescript-eslint/eslint-plugin": "^8.60.0",
     "@typescript-eslint/parser": "^8.60.0",
+    "esbuild": "^0.28.2",
     "eslint": "^8.56.0",
     "fast-check": "^4.8.0",
     "husky": "^9.1.7",