TDD MCP Server
A Model Context Protocol (MCP) server designed for test-driven development workflows. This server allows you to register command-line tools in a configuration file and execute them through MCP, with features like output caching, runtime estimation, and quiet mode execution.
Features
- Configurable Tools: Define any command-line tool in
tdd-mcp-config.toml - Flexible Configuration: Support for custom arguments, working directories, environment variables, and timeouts
- Runtime Estimation: Tracks historical execution times, allowing agent to call cheap tools many times and only prefer expensive ones when necessary
- Context window efficient: Tools run in quiet mode by default, returning only execution ID, exit code, and duration, with full output available on agent request
Installation
pip install tdd-mcp-server
Quick Start
-
Initialize configuration:
tdd-mcp-server init -
Edit the configuration (
tdd-mcp-config.toml) to add your tools -
Add the MCP server to your cursor config (
.cursor/mcp.json):{ "mcpServers": { "tdd-mcp-server": { "command": "/venv/path/to/bin/tdd-mcp-server", // example: ~/.virtualenvs/tdd-mcp-server/bin/tdd-mcp-server "args": ["--config", "tdd-mcp-config.toml", "run"] } } }
...or, simply run it standalone:
tdd-mcp-server run
Configuration
The server is configured via a TOML file (by default tdd-mcp-config.toml). Here's an example:
# Global settings
cache_directory = ".tdd-mcp-cache"
max_cache_size_mb = 100
max_history_entries = 1000
# Tool definitions
[tools.pytest]
description = "Run Python tests using pytest"
command = "pytest"
args = ["-v", "--tb=short"]
expected_runtime_seconds = 5.0
expected_output_size_bytes = 2048
working_directory = "."
timeout_seconds = 60.0
[tools.npm_test]
description = "Run JavaScript/TypeScript tests using npm"
command = "npm"
args = ["test"]
expected_runtime_seconds = 3.0
expected_output_size_bytes = 1024
working_directory = "."
timeout_seconds = 30.0
[tools.mypy]
description = "Run Python type checking with mypy"
command = "mypy"
args = ["."]
expected_runtime_seconds = 8.0
expected_output_size_bytes = 2048
working_directory = "."
timeout_seconds = 60.0
[tools.security_scan]
description = "Run security vulnerability scan"
command = "safety"
args = ["check", "--json"]
expected_runtime_seconds = 5.0
expected_output_size_bytes = 2048
working_directory = "."
timeout_seconds = 60.0
frozen_args = true # Prevents agents from changing scan parameters
Tool Configuration Options
description: Human-readable description of what the tool doescommand: The executable command to runargs: Default arguments to pass to the commandexpected_runtime_seconds: Estimated runtime (used for planning)expected_output_size_bytes: Estimated output sizeworking_directory: Directory to run the command in (optional)environment_variables: Additional environment variables (optional)timeout_seconds: Maximum time to allow the command to run (optional)frozen_args: If true, prevents agents from providing alternative arguments (optional, default: false)
Frozen Arguments
The frozen_args option allows you to lock down the arguments for specific tools, preventing AI agents from modifying them. This is useful for:
- Security tools: Ensure security scans run with specific, audited parameters
- Critical operations: Prevent accidental modification of important build or deployment commands
- Compliance: Maintain consistent tool execution for regulatory requirements
- Production safety: Lock configuration for tools that affect production systems
When frozen_args = true:
- The tool's MCP schema will not include an
argsparameter - Any additional arguments passed by the agent will be ignored
- Only the pre-configured
argsfrom the TOML file will be used
Example use cases:
[tools.security_audit]
command = "bandit"
args = ["-r", ".", "-f", "json", "-ll"]
frozen_args = true # Security audit must use exact parameters
[tools.production_deploy]
command = "kubectl"
args = ["apply", "-f", "prod-config.yaml", "--dry-run=server"]
frozen_args = true # Deployment commands cannot be modified
Available MCP Tools
Configured Tools
Each tool you define in the configuration becomes available as an MCP tool with these parameters:
args(optional): Additional arguments to pass to the toolquiet(default: true): Whether to return minimal output
Utility Tools
get_output_for_tool_call_id
Retrieve the full output for a specific execution:
{
"id": "uuid-of-execution"
}
get_last_tool_call_output
Retrieve the full output for the most recent execution:
{}
get_runtime_estimate
Get runtime estimate for a tool:
{
"tool_name": "pytest"
}
list_tool_history
List recent executions:
{
"limit": 10
}
get_tool_config
Get configuration for a specific tool:
{
"tool_name": "pytest"
}
Usage Patterns
Typical TDD Workflow
-
Run tests in quiet mode (default behavior):
{ "tool": "pytest", "arguments": {} }
Returns:
{"id": "uuid", "exit_code": 1, "duration_seconds": 2.34, "status": "failure"} -
Get full output for failed tests:
{ "tool": "get_output_for_tool_call_id", "arguments": {"id": "uuid"} }
Returns full stdout/stderr to analyze failures
-
Check runtime estimates before running expensive tools:
{ "tool": "get_runtime_estimate", "arguments": {"tool_name": "mypy"} }
Custom Arguments
You can pass additional arguments to any tool:
{
"tool": "pytest",
"arguments": {
"args": ["tests/test_specific.py", "-k", "test_function"],
"quiet": false
}
}
CLI Commands
tdd-mcp-server init
Create a new configuration file with example tools.
Options:
--force, -f: Overwrite existing configuration--config, -c: Specify config file path
tdd-mcp-server validate
Validate the configuration file.
tdd-mcp-server list-tools
Show all configured tools and their settings.
tdd-mcp-server run
Start the MCP server.
File Structure
.tdd-mcp-cache/ # Cache directory
├── execution_cache.json # Cached command outputs
└── runtime_history.json # Historical runtime data
tdd-mcp-config.toml # Main configuration file
Integration with AI Assistants
This MCP server is designed to work with AI assistants that support the Model Context Protocol. The assistant can:
- Run tests and other tools in quiet mode for quick feedback
- Only request full output when there are failures (non-zero exit codes)
- Use runtime estimates to make informed decisions about which tools to run
- Build up historical data to improve estimates over time
Example Use Cases
- Python Projects: pytest, mypy, black, ruff, coverage
- JavaScript/TypeScript: npm test, jest, eslint, tsc, prettier
- Rust: cargo test, cargo check, cargo clippy, cargo fmt
- Go: go test, go vet, go fmt, golint
- Multi-language: running language-specific tools based on file changes
Security Considerations
- The server executes arbitrary commands defined in the configuration
- Only use this with trusted configuration files
- Consider running in a containerized environment for additional isolation
- Review all tool configurations before deployment
Contributing
Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.
License
BSD 3 Clause License - see LICENSE file for details.
Metadata
Release files for tdd-mcp-server 0.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tdd_mcp_server-0.0.1.tar.gz | 22.0 kB | Without provenance | Details for tdd_mcp_server-0.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tdd_mcp_server-0.0.1-py3-none-any.whl | Python 3 | none | any | Details for tdd_mcp_server-0.0.1-py3-none-any.whl |
Total release size: 43.7 kB
Release files / tdd_mcp_server-0.0.1.tar.gz
| Download URL | tdd_mcp_server-0.0.1.tar.gz |
|---|---|
| Size | 22.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0f5e487a7ba1410aab6c1071584e73893d0e4215c657013eff33bd5e6bb4a977
|
|
BLAKE2b-256 checksum How to use checksums |
be81d5dd62ad10341987ce4c9eeb3b8290566e18d60519d7ec9771569744183d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.10
|
Release files / tdd_mcp_server-0.0.1-py3-none-any.whl
| Download URL | tdd_mcp_server-0.0.1-py3-none-any.whl |
|---|---|
| Size | 21.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aa081f2d28335cc1529ade7f21e60f217f737f787a4aeb63a097315489e6359e
|
|
BLAKE2b-256 checksum How to use checksums |
eb48643372295d6633b4d312066820436e1ee99c1e4e275867c441e2460da7c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.10
|
Security for tdd-mcp-server 0.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.