Skip to main content
Glama

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:

Variable

Default

Description

TDD_MCP_BASE_DIR

./test-env

Base directory for test environment

TDD_MCP_WORKSPACE_RETENTION_HOURS

168 (7 days)

How long to keep workspaces

TDD_MCP_TEST_TIMEOUT_MS

60000

Default test timeout

TDD_MCP_MAX_HISTORY_ENTRIES

1000

Maximum history entries to keep

TDD_MCP_AUTO_CLEANUP_ON_START

true

Auto-clean old workspaces on startup

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

Available Tools

10 tools
add-test-fileAdd Test FileA

Add an additional test file to an existing workspace and optionally run all tests. Useful for adding edge case tests, integration tests, or additional test suites without re-uploading implementation code. Automatically runs all tests in the workspace unless autoRunTests is false.

Inputs: workspaceId (required), testFile (required), timeoutMs, autoRunTests.

clean-workspaceClean WorkspaceA

Delete test workspace(s) and their associated history. Can delete a specific workspace by ID, or clean all old workspaces based on age. Returns a summary of deleted workspaces.

Inputs: workspaceId, olderThanHours.

get-test-run-detailsGet Test Run DetailsA

Retrieve complete details of a historical test run by history ID. Returns full test results, error messages, stack traces, and coverage data from a previous test execution. Useful for comparing test results across iterations, reviewing past failures, or analyzing coverage progression.

Inputs: historyId (required).

get-test-workspaceGet Test WorkspaceA

Retrieve the contents and metadata of a test workspace. Returns workspace metadata, list of files with their contents, and current Jest configuration.

Inputs: workspaceId (required).

list-test-historyList Test HistoryA

Retrieve a list of past test runs with optional filters by workspace, status, or date. Returns summaries of test runs including timestamps, workspace IDs, pass/fail status, and file names.

Inputs: limit, workspaceId, status.

list-workspacesList WorkspacesA

List all available test workspaces with their metadata. Returns workspace IDs, creation timestamps, language type, and file counts. Useful for discovering existing workspaces, understanding workspace organization, and managing workspace lifecycle.

Inputs: limit, sortBy.

run-specific-testsRun Specific TestsA

Run a subset of tests in an existing workspace using Jest test name patterns or file path patterns. Useful for focused testing during debugging, running only failing tests, or testing specific functionality without running the entire suite. Supports Jest's -t flag for test names and file path patterns.

Inputs: workspaceId (required), testNamePattern, testPathPattern, timeoutMs.

run-testRun Jest TestsA

Execute Jest tests on provided implementation and test files in an isolated workspace. Returns detailed test results including pass/fail status, individual test results, error messages, stack traces, and code coverage metrics.

Inputs: implementationFile (required), testFile (required), language, workspaceId, +1 more.

update-implementationUpdate ImplementationA

Update an implementation file in an existing workspace and optionally run tests. This enables efficient iteration during the refactor phase of TDD without re-uploading test files. Automatically runs tests and saves results to history unless autoRunTests is false.

Inputs: workspaceId (required), implementationFile (required), timeoutMs, autoRunTests.

update-jest-configUpdate Jest ConfigurationA

Update the Jest configuration in a workspace by merging new settings with the existing config. Useful for adjusting coverage thresholds, test patterns, or other Jest options.

Inputs: workspaceId (required), configUpdates (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: adding test files, cleaning workspaces, retrieving details, listing, running tests, updating implementation or config. The only potential overlap is between run-test and run-specific-tests, but their descriptions clarify one is for initial execution and the other for subset runs.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with hyphens (e.g., add-test-file, list-workspaces, update-jest-config). The naming is predictable and uniform.

    Tool Count5/5

    10 tools appropriately cover the TDD workspace lifecycle: creating, listing, running tests, updating code, configuring Jest, and cleaning. This is a well-scoped set without unnecessary tools.

    Completeness4/5

    The tools cover the main TDD workflow well, including adding tests, updating implementation, running tests, viewing history, and managing workspaces. A minor gap is the lack of a tool to delete individual test files from a workspace, but the overall surface is comprehensive.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to manage development workflows by running build commands, executing tests, analyzing package.json files, installing dependencies, and performing code linting. Supports multiple package managers (npm, yarn, pnpm) and provides detailed error reporting for development operations.
      5
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Exposes TypeScript Language Server Protocol functionality to AI agents, enabling them to query types at specific positions, find definitions and references, get diagnostics, run type tests, and type-check inline code just like in an IDE.
      9
      297 npm
      3
      MIT