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.
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.
✅ 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
npm installThe 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.
npm run buildnpm startFor interactive testing and debugging:
npm run inspectThen navigate to http://localhost:6274 in your browser.
run-testExecute 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"
}update-jest-configUpdate 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
}
}
}
}list-test-historyRetrieve 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)
get-test-workspaceInspect a workspace's contents and configuration.
Input:
workspaceId (string): Workspace ID
Output:
Workspace metadata (creation date, language, file count)
File contents
Current Jest configuration
clean-workspaceDelete 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
get-test-run-detailsRetrieve 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"
}list-workspacesList 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"
}update-implementationUpdate 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.
add-test-fileAdd 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.
run-specific-testsRun 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.
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 |
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.
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.mdnpm run buildUse the MCP Inspector for interactive testing:
npm run inspectAll 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
Run the setup command:
npm run setup:test-envCheck that files are valid TypeScript/JavaScript
Verify test file uses Jest syntax
Check timeout settings (increase if needed)
Inspect workspace with get-test-workspace tool
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
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
MIT
Contributions welcome! Please follow the existing code style and architecture patterns.
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
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.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | Yes | Workspace ID to add test file to | |
| testFile | Yes | Test file to add to the workspace | |
| timeoutMs | No | Test execution timeout in milliseconds | |
| autoRunTests | No | Automatically run all tests after adding (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses auto-run behavior and workspace prerequisite, but does not mention error conditions, authorization needs, or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences with no filler. Key information front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; description does not explain return values or test run result details. Adequate for core action but incomplete for a tool with 4 parameters and nested objects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description adds value by explaining autoRunTests default and effect. Does not add further to nested object parameters beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'add', resource 'test file', and optional action 'run all tests'. Distinguishes from siblings like 'run-test' and 'update-implementation'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides usage context ('edge case tests, integration tests, additional test suites') and notes automatic test running. Lacks explicit when-not or alternative tool recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | No | Optional workspace ID to clean. If not provided, cleans all old workspaces. | |
| olderThanHours | No | Only clean workspaces older than this many hours (safety filter) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description indicates a destructive action and returns a summary, but omits details like irreversibility, permission requirements, or side effects (e.g., cascading deletes). This is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the key information: what it does (delete workspaces), modes (by ID or age), and what it returns. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with no output schema, the description explains the return value (summary) and basic behavior. It is fairly complete, though it could mention that deletion is irreversible.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds context: workspaceId is optional and triggers age-based cleaning; olderThanHours is a safety filter. This enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes test workspaces and associated history, with two distinct modes: by ID or by age. This distinguishes it from sibling tools like get-test-workspace or list-workspaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each mode (specific ID vs. cleaning old workspaces), but does not explicitly state when not to use it or mention alternative tools like list-workspaces for inspection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| historyId | Yes | History ID of the test run to retrieve (returned by run-test) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses what is returned: full test results, error messages, stack traces, and coverage data. It does not explicitly state that the operation is read-only or idempotent, but the context suggests no side effects. Additional detail on rate limits or permissions would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and resource. No redundant or extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully explains what is returned and the purpose. For a simple tool with one parameter, this is complete. It covers the what, the inputs, and the use cases adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'historyId' and a description. The tool description adds context ('returned by run-test'), which clarifies where the ID comes from, adding value beyond the schema. Baseline is 3 due to high coverage, and this extra context earns a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'Retrieve complete details' and the resource 'historical test run by history ID'. It distinguishes itself from sibling tools like list-test-history (which lists runs) and run-test (creates runs) by focusing on historical detail retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'comparing test results across iterations, reviewing past failures, or analyzing coverage progression.' It implies when to use this tool but does not explicitly state when not to use it or contrast with alternatives like list-test-history for simpler listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the contents and metadata of a test workspace. Returns workspace metadata, list of files with their contents, and current Jest configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | Yes | ID of the workspace to inspect |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes a read-only retrieval but does not disclose potential side effects, prerequisites (e.g., workspace existence), or performance implications. Basic transparency, no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence (20 words) is appropriately sized and front-loaded with the main action. Could be slightly tighter by avoiding repetition of 'workspace', but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description explains return values (metadata, files with contents, Jest config). Covers input and output adequately for a simple retrieval tool. Missing error conditions or access requirements, but complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides full coverage for the single parameter with description 'ID of the workspace to inspect'. The tool description adds context about what the tool returns but does not add new meaning to the parameter itself. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (retrieve) and the specific resource (test workspace contents and metadata). It distinguishes from siblings by detailing what is returned: workspace metadata, file list with contents, and Jest configuration. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage: inspect a test workspace. No explicit guidance on when to use vs siblings like 'list-workspaces' or 'get-test-run-details'. Lacks exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return | |
| workspaceId | No | Filter by workspace ID | |
| status | No | Filter by test status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description partially covers behavior: it lists the return fields but does not disclose pagination, sorting order, or whether only completed runs are returned. It does not mention any side effects, but for a read-only tool, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and efficiently conveys purpose and output content. No redundant or filler information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (3 optional params, no output schema), the description covers the key aspects: what it returns (summaries with specific fields) and the filters. Could mention limit default or sorting, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description mentions 'optional filters' and lists the workspaceId and status implicitly, but does not add meaning beyond the schema descriptions. No additional parameter context provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: retrieving a list of past test runs. It specifies the resource (past test runs) and the action (retrieve with optional filters). It distinguishes from sibling tools like 'run-test' and 'get-test-run-details' by focusing on listing historical runs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, no mention of when to prefer 'get-test-run-details' for detailed info or 'run-test' for new runs. No hints about prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of workspaces to return (default: 50) | |
| sortBy | No | Sort workspaces by creation time or file count | created |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It correctly implies a read-only operation by stating 'list all... with their metadata' and lists returned fields. However, it does not disclose potential side effects, authentication needs, or behavior with large result sets beyond the limit parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences that are front-loaded with purpose, followed by output details and use cases. No superfluous language; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with two optional parameters and no output schema, the description adequately covers purpose, output fields, and usage context. It could mention pagination or ordering defaults more explicitly, but the limit parameter and sortBy enum cover these.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both parameters described. The description does not add additional meaning beyond what the schema already provides (limit and sortBy with defaults and descriptions), so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all available test workspaces with their metadata,' providing a specific verb-resource pair. It distinguishes from sibling tools like 'get-test-workspace' (which retrieves a single workspace) by emphasizing 'all' workspaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists use cases ('discovering existing workspaces, understanding workspace organization, and managing workspace lifecycle'), giving context for when to use. However, it does not explicitly state when not to use or mention alternatives like 'get-test-workspace' for a single workspace.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | Yes | Workspace ID to run tests in | |
| testNamePattern | No | Jest test name pattern (regex) to run specific tests by name (e.g., "should add", "multiplication") | |
| testPathPattern | No | File path pattern to run specific test files (e.g., "calculator.test.ts", "*.integration.test.*") | |
| timeoutMs | No | Test execution timeout in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses use of Jest patterns and timeout, but does not mention potential side effects, authentication needs, or return value format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with front-loaded purpose, no redundant information, each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description adequately explains functionality and parameters, though missing details on return values or results format. Overall sufficient for a test-runner tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions, and description adds context with examples for testNamePattern and testPathPattern, plus mentions Jest's -t flag, adding meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a subset of tests using Jest test name or file path patterns, distinguishing it from sibling tools like 'run-test' (likely runs all tests) and other workspace management tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (debugging, running only failing tests, specific functionality testing) and references Jest flags, but does not explicitly state when not to use it or compare with alternative tools like 'run-test'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| implementationFile | Yes | Implementation file to test | |
| testFile | Yes | Test file containing Jest tests | |
| language | No | Language of the files | typescript |
| workspaceId | No | Optional workspace ID to reuse existing workspace | |
| timeoutMs | No | Test execution timeout in milliseconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses return details (pass/fail, errors, stack traces, coverage) and mentions isolation. However, it does not clarify side effects like workspace creation or cleanup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first sentence clearly states action and context, second describes output. No wasted words, front-loaded with key info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers what the tool does and what it returns, which is important since no output schema exists. It mentions isolation but could clarify workspace lifecycle. Still fairly complete for a test execution tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The tool description does not add extra semantic meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes Jest tests on provided files in an isolated workspace, specific verb and resource. However, it does not explicitly differentiate from sibling tool 'run-specific-tests', so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'run-specific-tests' or what conditions are necessary. The description only states what it does without any contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | Yes | Workspace ID to update | |
| implementationFile | Yes | Implementation file with updated content | |
| timeoutMs | No | Test execution timeout in milliseconds | |
| autoRunTests | No | Automatically run tests after updating (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that tests are automatically run and results saved to history unless autoRunTests is false, and emphasizes efficient iteration. It does not mention potential destructive overwrite behavior, but that is implied by 'update'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action and purpose. Every sentence adds value: first sentence states the action and option, second sentence explains the use case and auto-run behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main behavior and use case, but lacks explanation of the return value or what 'saves results to history' means for the agent. Given the tool has no output schema and 4 parameters including a nested object, the description is mostly complete but could clarify the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds context about auto-run tests related to autoRunTests but does not add meaning to workspaceId or implementationFile beyond the schema. This is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update' and the resource 'implementation file', and specifies the context 'during the refactor phase of TDD' and the benefit 'without re-uploading test files'. It distinguishes from siblings like 'add-test-file' and 'run-test'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (during TDD refactor) and contrasts with not needing to re-upload test files. However, it does not explicitly state when not to use it or mention alternatives beyond sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | Yes | ID of the workspace to update Jest config for | |
| configUpdates | Yes | Jest configuration options to merge with existing config |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It mentions 'merging new settings' but does not elaborate on merge semantics (e.g., shallow vs deep, error handling, persistence). Basic transparency is provided but lacks detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences concisely convey the purpose and typical use cases without extraneous information. The key point is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, but the description adequately covers the input and operation. However, it could mention return value or side effects (e.g., if validation occurs). Overall sufficient for a straightforward update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds context by explaining the merge behavior, which goes beyond the schema's 'merge with existing config' note. This helps the agent understand the update mechanism.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: update Jest configuration in a workspace via merging. It distinguishes from sibling tools like 'add-test-file' or 'run-test', which focus on other test-related operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidance by listing example adjustments (coverage thresholds, test patterns). However, it does not specify when not to use this tool or mention alternatives, though sibling tools imply distinct purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.1.0add-test-fileclean-workspaceget-test-run-detailsget-test-workspacelist-test-historylist-workspacesrun-specific-testsrun-testupdate-implementationupdate-jest-configScored 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.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
Build Apps and run code in 30 languages — sandboxed, with persistent sessions for agent loops.
Hosted runtime for persistent agent teams, durable workflows, memory, schedules, and goals.
Test the idea before you build it. Rapidly works inside your AI agent.
