TDD MCP Server

A production-quality MCP (Model Context Protocol) server that enables AI agents to run Jest/TypeScript tests in isolated workspaces for Test-Driven Development (TDD) workflows.

Features

• ✅ Run Jest tests on TypeScript and JavaScript code in isolated workspaces

• ✅ Concurrent test execution with isolated workspace directories

• ✅ Detailed test results with pass/fail status, error messages, stack traces, and code coverage

• ✅ Test history tracking to review past test runs with full detail retrieval

• ✅ Dynamic Jest configuration updates for custom test settings

• ✅ Workspace inspection to view test files and configurations

• ✅ Workspace management with discovery, listing, and metadata viewing

• ✅ Incremental iteration - update implementation or add tests without re-uploading

• ✅ Focused testing - run specific tests by name or file pattern

• ✅ Automatic cleanup of old workspaces based on retention policy

Related MCP server: TypeScript LSP MCP

Installation

1. Install Dependencies

npm install

2. Set Up Test Environment

The server needs Jest and related tools installed in a separate test environment directory:

npm run setup:test-env

This creates a test-env/ directory with Jest, ts-jest, and TypeScript installed.

3. Build the Server

npm run build

Usage

Running the Server Directly

npm start

Testing with MCP Inspector

For interactive testing and debugging:

npm run inspect

Then navigate to http://localhost:6274 in your browser.

Available Tools

1. run-test

Execute Jest tests on provided implementation and test files.

Input:

• implementationFile (object):

  • name (string): File name (e.g., "calculator.ts")

  • content (string): Implementation code

• testFile (object):

  • name (string): Test file name (e.g., "calculator.test.ts")

  • content (string): Test code

• language (optional): "typescript" (default) or "javascript"

• workspaceId (optional): Reuse existing workspace

• timeoutMs (optional): Test timeout in milliseconds (default: 60000)

Output:

• Test results with pass/fail status

• Individual test details with error messages and stack traces

• Code coverage metrics

• Workspace ID for future reference

Example:

{
  "implementationFile": {
    "name": "calculator.ts",
    "content": "export function add(a: number, b: number): number { return a + b; }"
  },
  "testFile": {
    "name": "calculator.test.ts",
    "content": "import { add } from './calculator';\n\ntest('adds 1 + 2 to equal 3', () => {\n  expect(add(1, 2)).toBe(3);\n});"
  },
  "language": "typescript"
}

2. update-jest-config

Update Jest configuration in a workspace.

Input:

• workspaceId (string): Workspace ID

• configUpdates (object): Jest config properties to merge

Example:

{
  "workspaceId": "abc123...",
  "configUpdates": {
    "coverageThreshold": {
      "global": {
        "branches": 80,
        "functions": 80,
        "lines": 80,
        "statements": 80
      }
    }
  }
}

3. list-test-history

Retrieve past test runs with optional filters.

Input:

• limit (optional): Max results (default: 10)

• workspaceId (optional): Filter by workspace

• status (optional): "passed" or "failed"

Output:

• Array of test run summaries

• Statistics (total runs, passed/failed counts, unique workspaces)

4. get-test-workspace

Inspect a workspace's contents and configuration.

Input:

• workspaceId (string): Workspace ID

Output:

• Workspace metadata (creation date, language, file count)

• File contents

• Current Jest configuration

5. clean-workspace

Delete workspace(s) and associated history.

Input:

• workspaceId (optional): Specific workspace to clean

• olderThanHours (optional): Clean workspaces older than N hours

Output:

• Count of deleted workspaces and history entries

6. get-test-run-details

Retrieve complete details of a historical test run by history ID.

Input:

• historyId (string): History ID from a previous test run

Output:

• Full test results with all details

• Error messages and stack traces

• Coverage data

• Timestamp and metadata

Example:

{
  "historyId": "1706234567890-abc12345"
}

7. list-workspaces

List all available test workspaces with metadata.

Input:

• limit (optional): Maximum workspaces to return (default: 50)

• sortBy (optional): "created" (default) or "fileCount"

Output:

• Array of workspaces with IDs, creation dates, languages, and file counts

Example:

{
  "limit": 20,
  "sortBy": "created"
}

8. update-implementation

Update an implementation file in an existing workspace and optionally run tests.

Input:

• workspaceId (string): Workspace ID

• implementationFile (object):

  • name (string): File name to update

  • content (string): New implementation code

• timeoutMs (optional): Test timeout (default: 60000)

• autoRunTests (optional): Run tests after update (default: true)

Output:

• Test results (if autoRunTests is true)

• Updated file name and workspace ID

Example:

{
  "workspaceId": "abc123...",
  "implementationFile": {
    "name": "calculator.ts",
    "content": "export function add(a: number, b: number): number { return a + b + 1; }"
  },
  "autoRunTests": true
}

Use Case: Efficient iteration during the refactor phase of TDD without re-uploading test files.

9. add-test-file

Add an additional test file to an existing workspace and optionally run all tests.

Input:

• workspaceId (string): Workspace ID

• testFile (object):

  • name (string): Test file name

  • content (string): Test code

• timeoutMs (optional): Test timeout (default: 60000)

• autoRunTests (optional): Run all tests after adding (default: true)

Output:

• Test results for all tests in workspace (if autoRunTests is true)

• Added file name and workspace ID

Example:

{
  "workspaceId": "abc123...",
  "testFile": {
    "name": "calculator.edge-cases.test.ts",
    "content": "import { add } from './calculator';\n\ntest('handles negative numbers', () => {\n  expect(add(-1, -2)).toBe(-3);\n});"
  }
}

Use Case: Add edge case tests, integration tests, or additional test suites incrementally.

10. run-specific-tests

Run a subset of tests using Jest patterns for focused testing.

Input:

• workspaceId (string): Workspace ID

• testNamePattern (optional): Regex pattern to match test names (Jest -t flag)

• testPathPattern (optional): File path pattern for specific test files

• timeoutMs (optional): Test timeout (default: 60000)

Note: At least one pattern (testNamePattern or testPathPattern) must be provided.

Output:

• Test results for matched tests only

• Applied filters

• Coverage data

Example:

{
  "workspaceId": "abc123...",
  "testNamePattern": "should multiply",
  "timeoutMs": 30000
}

Use Case: Focused testing during debugging, running only failing tests, or testing specific functionality.

Configuration

Configure the server via environment variables:

MCP Client Configuration

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "tdd-mcp-server": {
      "command": "npx",
      "args": ["-y", "tsx", "G:/tdd-mcp/server.ts"],
      "env": {
        "TDD_MCP_BASE_DIR": "G:/tdd-mcp/test-env",
        "TDD_MCP_WORKSPACE_RETENTION_HOURS": "168"
      }
    }
  }
}

Note: Use absolute paths. Replace G:/tdd-mcp with your actual installation path.

Project Structure

tdd-mcp/
├── server.ts                          # MCP server entry point
├── src/
│   ├── config.ts                      # Configuration management
│   ├── logger.ts                      # Structured logging
│   ├── tool.ts                        # Abstract Tool base class
│   ├── workspace-manager.ts           # Workspace creation & file management
│   ├── jest-config-manager.ts         # Jest configuration handling
│   ├── test-runner.ts                 # Jest execution & result parsing
│   ├── test-history-manager.ts        # Test history storage & queries
│   └── tools/
│       ├── run-test.ts                # Main test execution tool
│       ├── update-jest-config.ts      # Config update tool
│       ├── list-test-history.ts       # History listing tool
│       ├── get-test-workspace.ts      # Workspace inspection tool
        ├── clean-workspace.ts         # Cleanup tool
        ├── get-test-run-details.ts    # History details retrieval
        ├── list-workspaces.ts         # Workspace discovery
        ├── update-implementation.ts   # Implementation file updates
        ├── add-test-file.ts           # Add test files incrementally
        └── run-specific-tests.ts      # Focused test execution
├── test-env/                          # Jest installation directory
│   ├── node_modules/                  # Jest & dependencies
│   ├── workspaces/                    # Isolated test workspaces
│   └── history/                       # Test run history
├── package.json
├── tsconfig.json
└── README.md

Development

Building

npm run build

Testing Tools

Use the MCP Inspector for interactive testing:

npm run inspect

Logging

All logs are written to stderr (MCP protocol requirement). The server uses structured logging with:

• Timestamps

• Color-coded levels (info, warn, error)

• Tool execution tracking

• Performance metrics

Troubleshooting

"Jest environment not initialized"

Run the setup command:

npm run setup:test-env

Test execution fails

1. Check that files are valid TypeScript/JavaScript

2. Verify test file uses Jest syntax

3. Check timeout settings (increase if needed)

4. Inspect workspace with get-test-workspace tool

Workspace not found

Workspaces may have been cleaned up due to retention policy. Check:

• TDD_MCP_WORKSPACE_RETENTION_HOURS setting

• Use list-test-history to see available workspaces

Security

• Path validation: All file operations validate paths to prevent directory traversal

• Workspace isolation: Each test run is isolated in its own directory

• No external dependencies: Tests run with provided code only (no npm install in workspaces)

• Timeout protection: Tests are killed if they exceed timeout

License

MIT

Contributing

Contributions welcome! Please follow the existing code style and architecture patterns.

Support

For issues or questions, please file a GitHub issue with:

• MCP server version

• Tool used and parameters

• Error messages (from stderr logs)

• Expected vs actual behavior