@slbdn/mcp-tester 1.4.3 → 1.5.4

package/docs/examples.md

@@ -0,0 +1,300 @@
+# Examples
+
+Practical code examples for common MCP Tester use cases.
+
+## Example MCP Servers
+
+The `examples/` directory includes ready-to-run MCP servers for testing and learning:
+
+| Server | Description |
+|--------|-------------|
+| `mock-server.js` | Basic server with echo, add, delay, error_tool + 2 resources + 2 prompts |
+| `simple-server.ts` | Minimal TypeScript server — greet tool, version resource, welcome prompt |
+| `stateful-server.ts` | Server with mutable state — counter (increment/get/reset) and todo list (add/list/complete) |
+
+Run any server standalone:
+
+```bash
+# JavaScript (no build needed)
+node examples/mock-server.js
+
+# TypeScript (uses tsx)
+npx tsx examples/simple-server.ts
+npx tsx examples/stateful-server.ts
+```
+
+Test against them:
+
+```bash
+npx @slbdn/mcp-tester test -- node --loader tsx examples/simple-server.ts
+```
+
+## Basic Tool Testing
+
+```typescript
+import { MCPClient } from '@slbdn/mcp-tester';
+
+async function testTool() {
+  const client = new MCPClient();
+
+  try {
+    await client.start({
+      command: 'node',
+      args: ['./my-server.js'],
+    });
+
+    const tools = await client.listTools();
+    console.log(`Found ${tools.length} tools`);
+
+    for (const tool of tools) {
+      console.log(`\nTesting: ${tool.name}`);
+      const result = await client.callTool({
+        name: tool.name,
+        arguments: {},
+      });
+      console.log(`Result: ${result.content[0]?.text}`);
+    }
+  } finally {
+    await client.stop();
+  }
+}
+
+testTool();
+```
+
+## Resource Reading
+
+```typescript
+import { MCPClient } from '@slbdn/mcp-tester';
+
+async function readConfiguration() {
+  const client = new MCPClient();
+
+  try {
+    await client.start({
+      command: 'node',
+      args: ['./config-server.js'],
+    });
+
+    const resources = await client.listResources();
+    console.log('Available resources:', resources.map(r => r.uri));
+
+    const settings = await client.readResource('config://settings');
+    console.log('Settings:', JSON.parse(settings.contents[0].text as string));
+  } finally {
+    await client.stop();
+  }
+}
+
+readConfiguration();
+```
+
+## Using Prompts
+
+```typescript
+import { MCPClient } from '@slbdn/mcp-tester';
+
+async function usePrompt() {
+  const client = new MCPClient();
+
+  try {
+    await client.start({
+      command: 'node',
+      args: ['./prompt-server.js'],
+    });
+
+    const prompt = await client.getPrompt('greet', { name: 'World' });
+    console.log('Generated message:', prompt.messages[0].content.text);
+  } finally {
+    await client.stop();
+  }
+}
+
+usePrompt();
+```
+
+## Complete Jest Test Suite
+
+```typescript
+import { MCPClient, setupJestMatchers } from '@slbdn/mcp-tester';
+import { beforeAll, beforeEach, afterEach, describe, it, expect } from '@jest/globals';
+
+beforeAll(() => setupJestMatchers());
+
+describe('My MCP Server', () => {
+  let client: MCPClient;
+
+  beforeEach(async () => {
+    client = new MCPClient();
+    await client.start({ command: 'node', args: ['./server.js'] });
+  });
+
+  afterEach(async () => {
+    if (client.isConnected()) await client.stop();
+  });
+
+  it('should have expected tools', async () => {
+    const tools = await client.listTools();
+    expect(tools).toHaveTool('echo');
+    expect(tools).toHaveToolCount(5);
+  });
+
+  it('should call tool and check result', async () => {
+    const result = await client.callTool({
+      name: 'calculate',
+      arguments: { operation: 'add', values: [10, 20] },
+    });
+    expect(result).toReturnText('30');
+  });
+
+  it('should handle errors', async () => {
+    const result = await client.callTool({
+      name: 'fail-tool',
+      arguments: {},
+    });
+    expect(result).toReturnError();
+  });
+});
+```
+
+## Complete Vitest Test Suite
+
+```typescript
+import { MCPClient, setupVitestMatchers } from '@slbdn/mcp-tester';
+import { beforeAll, beforeEach, afterEach, describe, it, expect } from 'vitest';
+// /// <reference types="@slbdn/mcp-tester/vitest" />
+
+beforeAll(() => setupVitestMatchers());
+
+describe('My MCP Server', () => {
+  let client: MCPClient;
+
+  beforeEach(async () => {
+    client = new MCPClient();
+    await client.start({ command: 'node', args: ['./server.js'] });
+  });
+
+  afterEach(async () => {
+    if (client.isConnected()) await client.stop();
+  });
+
+  it('should have expected tools', async () => {
+    const tools = await client.listTools();
+    expect(tools).toHaveTool('echo');
+    expect(tools).toHaveToolCount(5);
+  });
+
+  it('should call tool and check result', async () => {
+    const result = await client.callTool({
+      name: 'calculate',
+      arguments: { operation: 'add', values: [10, 20] },
+    });
+    expect(result).toReturnText('30');
+  });
+});
+```
+
+## Using Assert Utilities (Any Test Runner)
+
+```typescript
+import { MCPClient, assert } from '@slbdn/mcp-tester';
+
+async function runTest(name: string, fn: () => Promise<void>) {
+  try {
+    await fn();
+    console.log(`✓ ${name}`);
+  } catch (error) {
+    console.error(`✗ ${name}: ${error instanceof Error ? error.message : error}`);
+  }
+}
+
+const client = new MCPClient();
+await client.start({ command: 'node', args: ['./server.js'] });
+
+await runTest('echo returns correct text', async () => {
+  const result = await client.callTool({ name: 'echo', arguments: { message: 'hello' } });
+  assert.toolTextEquals(result, 'Echo: hello');
+  assert.toolTextContains(result, 'hello');
+  assert.toolIsOk(result);
+});
+
+await runTest('add computes sum', async () => {
+  const result = await client.callTool({ name: 'add', arguments: { a: 3, b: 7 } });
+  assert.toolTextContains(result, '10');
+});
+
+await runTest('config is valid JSON', async () => {
+  const result = await client.readResource('config://settings');
+  assert.resourceHasContent(result);
+  assert.resourceTextContains(result, 'setting1');
+});
+
+await client.stop();
+```
+
+## Running the Examples
+
+```bash
+# Basic functionality test
+npx tsx examples/basic-test.ts
+
+# Full capabilities test
+npx tsx examples/full-test.ts
+
+# Jest matchers example
+npx tsx examples/jest-matchers-example.ts
+
+# Assert utilities example
+npx tsx examples/assert-example.ts
+
+# Test against a real MCP server (server-everything)
+npx tsx examples/everything-server-test.ts
+
+# Test stateful server patterns
+npx tsx examples/stateful-server-test.ts
+
+# Run mock server standalone (for manual testing)
+node examples/mock-server.js
+
+# Run simple TypeScript server (for learning)
+npx tsx examples/simple-server.ts
+
+# Run stateful server (counter + todos)
+npx tsx examples/stateful-server.ts
+```
+
+## Generating TypeScript Types
+
+Connect to any MCP server and generate typed `.d.ts` declarations:
+
+```typescript
+import { generateTypes } from '@slbdn/mcp-tester';
+import { writeFileSync } from 'fs';
+
+const types = await generateTypes({
+  command: 'node',
+  args: ['./my-server.js'],
+});
+
+writeFileSync('my-server-types.d.ts', types);
+```
+
+Or use the CLI:
+
+```bash
+npx @slbdn/mcp-tester generate-types node ./server.js -o server.d.ts
+```
+
+Then use the generated types for type-safe tool calls:
+
+```typescript
+import type { ToolArgsMap, ToolCall } from './server.d.ts';
+
+// TypeScript knows the exact arguments shape
+const result = await client.callTool({
+  name: 'add',
+  arguments: { a: 1, b: 2 } as ToolArgsMap['add'],
+});
+```
+
+**Supported schema features:** primitives, enums, arrays, nested objects, `oneOf`/`anyOf`/`allOf`, `$ref`, `const`, optional fields, JSDoc descriptions.

package/docs/nodejs-compatibility.md

@@ -0,0 +1,81 @@
+# Node.js Compatibility
+
+## Supported Versions
+
+| Node.js Version | Status | Notes |
+|----------------|--------|-------|
+| 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 |
+
+## Requirements
+
+- **Node.js** >= 20
+- **npm** >= 9
+- ES2022 Modules (ESM)
+- Async/await support
+
+The `package.json` enforces the minimum version:
+
+```json
+{
+  "engines": {
+    "node": ">=20"
+  }
+}
+```
+
+## TypeScript Compatibility
+
+Targets TypeScript 5.3+ with ES2022 output.
+
+## Platform Support
+
+- ✅ macOS (Intel & Apple Silicon)
+- ✅ Linux (Ubuntu, Debian, CentOS, Alpine)
+- ✅ Windows 10/11 (via WSL or native Node.js)
+
+## CI/CD Version Specification
+
+**GitHub Actions:**
+```yaml
+- uses: actions/setup-node@v5
+  with:
+    node-version: '20'
+```
+
+**CircleCI:**
+```yaml
+docker:
+  - image: cimg/node:20.11.0
+```
+
+**Jenkins:**
+```groovy
+tools {
+  nodejs 'Node.js 20.11.0'
+}
+```
+
+## Upgrading Node.js
+
+**Using nvm:**
+```bash
+nvm install 20
+nvm use 20
+nvm alias default 20
+```
+
+**Using n:**
+```bash
+n 20
+```
+
+## Known Issues
+
+| Version | Issue | Workaround |
+|---------|-------|------------|
+| < 18 | Not supported | Upgrade to 18+ |
+| 18.0–18.16 | Potential ESM issues | Use 18.17+ |
+| Any | Memory limits for large ops | Increase `--max-old-space-size` |