TDD MCP Server
Runs Jest tests on TypeScript and JavaScript code in isolated workspaces, providing detailed results, coverage metrics, and test history for test-driven development workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TDD MCP Server test my calculator implementation"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 install2. Set Up Test Environment
The server needs Jest and related tools installed in a separate test environment directory:
npm run setup:test-envThis creates a test-env/ directory with Jest, ts-jest, and TypeScript installed.
3. Build the Server
npm run buildUsage
Running the Server Directly
npm startTesting with MCP Inspector
For interactive testing and debugging:
npm run inspectThen 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 workspacetimeoutMs(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 IDconfigUpdates(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 workspacestatus(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 cleanolderThanHours(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 IDimplementationFile(object):name(string): File name to updatecontent(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 IDtestFile(object):name(string): Test file namecontent(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 IDtestNamePattern(optional): Regex pattern to match test names (Jest -t flag)testPathPattern(optional): File path pattern for specific test filestimeoutMs(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 |
|
| Base directory for test environment |
|
| How long to keep workspaces |
|
| Default test timeout |
|
| Maximum history entries to keep |
|
| 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.mdDevelopment
Building
npm run buildTesting Tools
Use the MCP Inspector for interactive testing:
npm run inspectLogging
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-envTest execution fails
Check that files are valid TypeScript/JavaScript
Verify test file uses Jest syntax
Check timeout settings (increase if needed)
Inspect workspace with
get-test-workspacetool
Workspace not found
Workspaces may have been cleaned up due to retention policy. Check:
TDD_MCP_WORKSPACE_RETENTION_HOURSsettingUse
list-test-historyto 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 toolsadd-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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Writes adversarial test suites for AI-built code. Your agent's test engineer.
Write, validate, deploy and run TypeScript workflow automations on Whenever from your coding agent.
Run AI agent tasks in isolated sandboxes with a cost cap, saved workflows and scoped connections.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables 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.5MIT
- AlicenseBqualityDmaintenanceExposes 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.9297 npm3MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to run Vitest tests and analyze code coverage, supporting test-driven development workflows with tools for test execution and coverage analysis.207 npm3MIT
- AlicenseAqualityDmaintenanceEnables AI agents to run reusable Playwright test fixtures against live deployments, providing structured test results, screenshots, and assertions.3MIT