API Reference

Complete reference for MCP Jest's CLI commands and programmatic API.

CLI Commands

mcp-jest <config-file> [options]

Options

--timeout <ms>

Set the timeout for server startup and test execution. Default: 30000ms

--verbose

Enable verbose output for debugging

--watch

Watch for file changes and re-run tests automatically

--update-snapshots

Update snapshot files with current test results

--no-colors

Disable colored output (useful for CI environments)

Test Configuration Schema

interface MCPTestConfig {
  // Test suite name
  name: string;
  
  // Server configuration
  server: {
    command: string;      // Command to start the server
    args?: string[];      // Command arguments
    env?: Record<string, string>;  // Environment variables
    cwd?: string;         // Working directory
  };
  
  // Global timeout (applies to all tests)
  timeout?: number;
  
  // Test definitions
  tests: TestDefinition[];
  
  // Snapshot configuration
  snapshots?: {
    updateSnapshots?: boolean;
    snapshotDir?: string;
  };
}

Test Types

Capabilities Test

Tests server metadata and capabilities:

{
  "name": "Test server capabilities",
  "type": "capabilities",
  "expect": {
    "name": "my-server",
    "version": "1.0.0",
    "capabilities": {
      "tools": {},
      "resources": {}
    }
  }
}

Tool Test

Tests individual tool execution:

{
  "name": "Test calculator tool",
  "type": "tool",
  "tool": "calculate",
  "arguments": {
    "expression": "2 + 2"
  },
  "expect": {
    "result": 4
  }
}

Resource Test

Tests resource reading:

{
  "name": "Test file resource",
  "type": "resource",
  "resource": "file://config.json",
  "expect": {
    "contents": [
      {
        "type": "text",
        "text": "{ \"key\": \"value\" }"
      }
    ]
  }
}

Programmatic API

Use MCP Jest programmatically in your Node.js scripts:

import { mcpTest } from 'mcp-jest';

// Define your test configuration
const config = {
  name: 'My Test Suite',
  server: {
    command: 'node',
    args: ['my-server.js']
  },
  tests: [
    {
      name: 'Test my tool',
      type: 'tool',
      tool: 'my-tool',
      arguments: { input: 'test' },
      expect: { success: true }
    }
  ]
};

// Run tests
const results = await mcpTest(config);

// Process results
if (results.success) {
  console.log('All tests passed!');
} else {
  console.error('Some tests failed:', results.failures);
}

Expectation Matchers

MCP Jest supports flexible expectation matching:

Exact Match

Values must match exactly:

"expect": { "value": "exact string" }

Type Match

Match by type only:

"expect": { "value": { "type": "string" } }

Pattern Match

Match using regular expressions:

"expect": { "message": { "pattern": "^Error:.*" } }

Partial Match

Match object subsets:

"expect": {
  "response": {
    "status": "success"
    // Other fields are ignored
  }
}

Error Handling

MCP Jest provides detailed error messages:

Test Failure Output

✗ Should calculate correctly
  Expected: { "result": 4 }
  Received: { "result": 5 }
  
  Difference:
  - Expected
  + Received
  
    {
  -   "result": 4
  +   "result": 5
    }