TDD-MCP Server (Experimental)

A Model Context Protocol (MCP) server that focuses on disciplined Test-Driven Development workflows by managing session state and providing guided phase transitions. It ensures developers and AI agents follow proper TDD methodology through explicit state management and evidence-based phase transitions.

What This MCP Server Does

TDD-MCP acts as your TDD coach, guiding you through proper Test-Driven Development cycles by:

🔄 Enforcing the 3-phase TDD cycle: Write failing test → Implement → Refactor → Repeat
🎯 Maintaining focus on one goal at a time with clear success criteria
📝 Tracking your progress through persistent session state
🛡️ Guiding against TDD violations like implementing before writing tests
🧭 Providing contextual guidance at every step

⚠️ Important Considerations

Token Usage Warning This MCP server significantly increases token usage for LLM interactions. Modern LLMs like Claude Sonnet can generate complete classes and test files in a single response, but TDD-MCP deliberately constrains this to enforce disciplined development. Consider the trade-off between development speed and TDD discipline.

Not Ideal For:

Large-scale refactoring or architectural changes
Simple CRUD operations or boilerplate code
When you need to generate many files quickly
Prototyping or exploratory development phases

Quickstart Guide

Get up and running with TDD-MCP in minutes:

1. Configure the MCP Server

Choose your AI editor and add TDD-MCP to your configuration:

VS Code with Copilot Chat:

// .vscode/mcp.json
{
  "servers": {
    "tdd-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["tdd-mcp"],
      "env": {
        "TDD_MCP_LOG_LEVEL": "info",
        "TDD_MCP_SESSION_DIR": ".tdd-mcp/sessions/"
      }
    }
  }
}

Cursor:

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "tdd-mcp": {
      "command": "uvx",
      "args": ["tdd-mcp"],
      "env": {
        "TDD_MCP_LOG_LEVEL": "info",
        "TDD_MCP_SESSION_DIR": ".tdd-mcp/sessions/"
      }
    }
  }
}

For Local Development (if you cloned the repo):

// .vscode/mcp.json
{
  "servers": {
    "tdd-mcp-dev": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "tdd_mcp.main"],
      "cwd": "/path/to/tdd-mcp"
    }
  }
}

2. Start a New Agent Chat

Open your AI editor and start a new conversation. The TDD-MCP server will automatically connect.

3. Initialize TDD-MCP

Teach your AI editor the basics of TDD-MCP by using the built-in initialize prompt:

In VS Code with Copilot Chat:

@tdd-mcp.initialize

In other editors, paste this:

Some AI editors may require a different format, but the goal is to trigger the initialization prompt. This prompt provides all the instructions on how to use TDD-MCP effectively in the Model's context.

4. Plan Your Session

Start planning with the session wizard:

I want to implement a password validator function. 
Please use the start_session_wizard prompt to help me set up the session parameters.

Or directly ask your AI:

Help me start a TDD session for implementing a password validator that checks:
- Minimum 8 characters
- At least one uppercase letter
- At least one number

5. Start Your TDD Session

Your AI will call start_session() with the planned parameters:

start_session(
    goal="Implement password validator with length, uppercase, and number requirements",
    test_files=["tests/test_password_validator.py"],
    implementation_files=["src/password_validator.py"],
    run_tests=["pytest tests/test_password_validator.py -v"]
)

6. Follow the Red-Green-Refactor Flow

Work with your AI through the TDD cycle:

🔴 Red Phase (Write Failing Test):

Let's write our first failing test for minimum length validation.

🟢 Green Phase (Make Test Pass):

Now let's implement the minimal code to make this test pass.

🔵 Refactor Phase (Improve Code):

Let's refactor to improve the code quality while keeping tests green.

7. Add Logs Anytime

Capture your thoughts during development:

Log: "Considering if we should validate empty strings separately"

Log: "Found a good pattern for chaining validation rules"

8. End the Session

When you've reached your goal:

We've successfully implemented the password validator with all requirements. 
Please call end_session() to complete our TDD session.

You'll get a summary of what was accomplished during the session.

🎉 You're Ready!

You now have:

✅ A working TDD workflow with AI guidance
✅ Complete session history and audit trail
✅ Disciplined test-first development
✅ Evidence-based phase transitions

How It Works

TDD Phase Management

The server maintains strict control over the TDD workflow:

📝 WRITE_TEST Phase: You can only modify test files. Write ONE failing test that captures the next small increment of functionality.
✅ IMPLEMENT Phase: You can only modify implementation files. Write the minimal code needed to make the failing test pass.
🔧 REFACTOR Phase: You can modify both test and implementation files. Improve code quality without changing behavior.

Each phase transition requires evidence - you must describe what you accomplished to justify moving to the next phase.

State Persistence

Sessions persist across server restarts
Complete audit trail of all actions through event sourcing
Pause/resume functionality for long-running projects
Session history shows your TDD journey

File Access Guidance

The server provides guidance on which files to modify based on your current TDD phase:

WRITE_TEST: Only test files specified in your session
IMPLEMENT: Only implementation files specified in your session
REFACTOR: Both test and implementation files

Note: This is guidance for your AI assistant - the server doesn't enforce file system restrictions.

When to Use TDD-MCP?

🎯 Mission-Critical Features

Use when building components where bugs have serious consequences
Perfect for core business logic, security features, or data integrity functions
When you need rock-solid reliability and comprehensive test coverage

📏 Small, Focused Goals

Best for goals that fit within a single context window
Ideal for individual functions, classes, or small modules
When you can clearly define "done" in a few sentences

🧠 Learning TDD Discipline

Excellent for developers new to Test-Driven Development
Helps build muscle memory for the Red-Green-Refactor cycle
Provides structured guidance when working with AI assistants

� Complex Logic Development

When you need to think through edge cases step by step
For algorithms or business rules that benefit from incremental development
When you want to document your thought process through tests

Available MCP Tools & Prompts

When you connect to the TDD-MCP server, you get access to these tools and prompts:

🚀 Session Management Tools

`start_session(goal, test_files, implementation_files, run_tests, custom_rules)`

Start a new TDD session with:

goal: Clear, testable objective with definition of done
test_files: List of test files you're allowed to modify (e.g., ["tests/test_auth.py"])
implementation_files: List of implementation files you're allowed to modify (e.g., ["src/auth.py"])
run_tests: Commands to run your tests (e.g., ["pytest tests/test_auth.py -v"])
custom_rules: Additional TDD rules specific to your project (optional)

Returns: Session ID string

`update_session(...)`

Update any session parameters as your project evolves. Returns True if successful.

`pause_session()` / `resume_session(session_id)`

Pause your current session and resume it later (even after server restart).

pause_session() returns the session ID
resume_session(session_id) returns a TDDSessionState object

`end_session()`

Complete your session and get a summary of what was accomplished. Returns summary string.

🔄 Workflow Control Tools

`get_current_state()`

Use this frequently! Returns a TDDSessionState object with your current TDD phase, cycle number, allowed files, and suggested next actions.

`next_phase(evidence_description)`

Move to the next TDD phase by providing evidence of what you accomplished. Returns a TDDSessionState object with the new phase:

From WRITE_TEST → IMPLEMENT: "wrote failing test for user login validation"
From IMPLEMENT → REFACTOR: "implemented basic login function, test now passes"
From REFACTOR → WRITE_TEST: "refactored login code for better error handling"

`rollback(reason)`

Go back to the previous phase if you made a mistake. Returns a TDDSessionState object with the previous phase:

"realized I implemented too much functionality in one test"
"need to write a better test first"

📝 Logging & History Tools

`log(message)`

Add notes to your session without affecting workflow state. Returns True if successful:

"considering edge case for empty passwords"
"found useful pattern in existing codebase"

`history()`

View your complete TDD journey - all phase transitions, logs, and evidence. Returns a list of formatted history strings.

🧭 Guidance & Help

`initialize` (Prompt)

Get comprehensive instructions for using TDD-MCP effectively. Use this first when starting with the server.

`start_session_wizard(goal)` (Prompt)

Get personalized guidance for setting up your TDD session. Analyzes your workspace and suggests optimal session parameters.

`quick_help()`

Get context-aware help and shortcuts based on your current phase and session state. Returns a dictionary with available actions and reminders.

How Session Management Works

State Persistence

Your TDD sessions are automatically saved and persist across server restarts:

🔄 Event Sourcing

Every action you take is recorded as an event
Your session state is calculated from these events
Complete audit trail of your TDD journey
Rollback capability to previous phases

💾 Automatic Saving

Sessions are saved to .tdd-mcp/sessions/ directory
Each session gets a unique JSON file
No manual save/load required
Safe concurrent access with file locking

⏸️ Pause & Resume

Pause your session anytime with pause_session()
Resume later with resume_session(session_id)
Perfect for long-running projects
Session state preserved exactly as you left it

Session Lifecycle

📋 PLANNING
├── Use start_session_wizard prompt for guided setup
├── Review suggested parameters
└── Call start_session() to begin (returns session ID)

🔄 ACTIVE TDD CYCLES
├── Phase: WRITE_TEST → write failing test
├── Phase: IMPLEMENT → make test pass  
├── Phase: REFACTOR → improve code quality
└── Repeat cycles until goal achieved

⏸️ PAUSE/RESUME (Optional)
├── Call pause_session() to save state (returns session ID)
├── Server can restart, system can reboot
└── Call resume_session() to continue (returns TDDSessionState)

✅ COMPLETION
├── Call end_session() when goal achieved (returns summary)
└── Get summary of what was accomplished

File Access Guidance

The server provides guidance on which files should be modified based on your current TDD phase:

📝 WRITE_TEST Phase: Only your specified test files should be modified
✅ IMPLEMENT Phase: Only your specified implementation files should be modified
🔧 REFACTOR Phase: Both test and implementation files can be modified

Note: This is guidance provided to your AI assistant through the MCP tools - the server doesn't enforce file system restrictions. Your AI can still choose to modify any files, but the server helps it understand which files are appropriate for each TDD phase.

Development

Prerequisites

Python 3.12+
uv for dependency management

Setup

# Clone the repository
git clone https://github.com/tinmancoding/tdd-mcp.git
cd tdd-mcp

# Install dependencies
uv sync

# Install development dependencies
uv sync --group dev

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=tdd_mcp

# Run specific test file
uv run pytest tests/domain/test_session.py

# Run tests in watch mode
uv run pytest-watch

Development Workflow

The project itself follows TDD principles:

Write failing tests first for new functionality
Implement minimal code to make tests pass
Refactor for code quality while keeping tests green

Project Structure

src/tdd_mcp/
├── main.py                    # FastMCP server entry point
├── handlers/                  # MCP tool handlers
│   ├── session_handlers.py    # start_session, update_session, etc.
│   ├── workflow_handlers.py   # next_phase, rollback, get_current_state
│   ├── logging_handlers.py    # log, history
│   └── guidance_handlers.py   # initialize, quick_help
├── domain/                    # Core business logic
│   ├── session.py            # TDDSession class
│   ├── events.py             # Event schemas and TDDEvent
│   └── exceptions.py         # Custom exception classes
├── repository/                # Data persistence layer
│   ├── base.py               # Abstract TDDSessionRepository
│   └── filesystem.py         # FileSystemRepository implementation
└── utils/                     # Supporting utilities
    ├── config.py             # Environment variable handling
    └── logging.py            # Logging configuration

Building and Publishing

# Build the package
uv build

# Install locally for testing
uv pip install -e .

# Publish to PyPI (maintainers only)
uv publish

Architecture

Event Sourcing

Complete Audit Trail: Every action, phase change, and log entry preserved
Rollback Capability: Navigate backward through phases when needed
State Consistency: Current state calculated from authoritative event stream
Future-Proof: New event types can be added without breaking existing sessions

Repository Pattern

Pluggable Storage: Abstract repository interface with filesystem implementation
Concurrency Safety: Lock file mechanism prevents concurrent session access
Session Persistence: JSON event streams survive server restarts

MCP Integration

FastMCP V2: Built on the latest MCP framework
Rich Tool Set: 12 comprehensive tools for session and workflow management
Error Handling: Structured error responses with recovery suggestions

Configuration

Environment Variables

TDD_MCP_SESSION_DIR: Custom session storage directory (default: .tdd-mcp/sessions/)
TDD_MCP_LOG_LEVEL: Logging verbosity - debug|info|warn|error (default: info)
TDD_MCP_USE_MEMORY_REPOSITORY: Use in-memory storage for testing (default: false)

Session Structure

Sessions are stored as JSON event streams:

{
  "schema_version": "1.0",
  "events": [
    {
      "timestamp": "2025-07-11T10:30:00Z",
      "event_type": "session_started",
      "data": {
        "goal": "Implement user authentication",
        "test_files": ["tests/test_auth.py"],
        "implementation_files": ["src/auth.py"],
        "run_tests": ["pytest tests/test_auth.py -v"]
      }
    }
  ]
}

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Follow TDD: Write tests first, then implement
Ensure all tests pass (uv run pytest)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Issues: GitHub Issues
Documentation: See the PRD for detailed specifications
MCP Protocol: Model Context Protocol

Practice what we preach: This TDD-MCP server was built using the same TDD discipline it aims to enforce!

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.github/workflows		.github/workflows
aidocs		aidocs
src/tdd_mcp		src/tdd_mcp
tests		tests
.gitignore		.gitignore
.python-version		.python-version
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

tinmancoding/tdd-mcp

Folders and files

Latest commit

History

Repository files navigation

TDD-MCP Server (Experimental)

What This MCP Server Does

⚠️ Important Considerations

Quickstart Guide

1. Configure the MCP Server

2. Start a New Agent Chat

3. Initialize TDD-MCP

4. Plan Your Session

5. Start Your TDD Session

6. Follow the Red-Green-Refactor Flow

7. Add Logs Anytime

8. End the Session

🎉 You're Ready!

How It Works

TDD Phase Management

State Persistence

File Access Guidance

When to Use TDD-MCP?

Available MCP Tools & Prompts

🚀 Session Management Tools

start_session(goal, test_files, implementation_files, run_tests, custom_rules)

update_session(...)

pause_session() / resume_session(session_id)

end_session()

🔄 Workflow Control Tools

get_current_state()

next_phase(evidence_description)

rollback(reason)

📝 Logging & History Tools

log(message)

history()

🧭 Guidance & Help

initialize (Prompt)

start_session_wizard(goal) (Prompt)

quick_help()

How Session Management Works

State Persistence

Session Lifecycle

File Access Guidance

Development

Prerequisites

Setup

Running Tests

Development Workflow

Project Structure

Building and Publishing

Architecture

Event Sourcing

Repository Pattern

MCP Integration

Configuration

Environment Variables

Session Structure

Contributing

License

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

`start_session(goal, test_files, implementation_files, run_tests, custom_rules)`

`update_session(...)`

`pause_session()` / `resume_session(session_id)`

`end_session()`

`get_current_state()`

`next_phase(evidence_description)`

`rollback(reason)`

`log(message)`

`history()`

`initialize` (Prompt)

`start_session_wizard(goal)` (Prompt)

`quick_help()`

Packages