# 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:**
```json
// .vscode/mcp.json
{
"servers": {
"tdd-mcp": {
"type": "stdio",
"command": "uv",
"args": ["run", "python", "-m", "tdd_mcp.main"],
"cwd": "/path/to/tdd-mcp"
}
}
}
```
**Cursor:**
```json
// ~/.cursor/mcp.json
{
"mcpServers": {
"tdd-mcp": {
"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:
```python
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:
1. **π WRITE_TEST Phase**: You can only modify test files. Write ONE failing test that captures the next small increment of functionality.
2. **β
IMPLEMENT Phase**: You can only modify implementation files. Write the minimal code needed to make the failing test pass.
3. **π§ 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](https://github.com/astral-sh/uv) for dependency management
### Setup
```bash
# 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
```bash
# 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:
1. **Write failing tests first** for new functionality
2. **Implement minimal code** to make tests pass
3. **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
```bash
# 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:
```json
{
"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
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Follow TDD: Write tests first, then implement
4. Ensure all tests pass (`uv run pytest`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- **Issues**: [GitHub Issues](https://github.com/tinmancoding/tdd-mcp/issues)
- **Documentation**: See the [PRD](aidocs/PRD-initial.md) for detailed specifications
- **MCP Protocol**: [Model Context Protocol](https://modelcontextprotocol.io/)
---
**Practice what we preach**: This TDD-MCP server was built using the same TDD discipline it aims to enforce!
Raw data
{
"_id": null,
"home_page": null,
"name": "tdd-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "development-workflow, event-sourcing, mcp, tdd, test-driven-development, testing",
"author": null,
"author_email": "Tin Man <135335469+tinmancoding@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/50/ba/2ebcea2c4e6465e1e18a7eb0c1c7a7e64849cbe2ef8f0fe0484e04a4c49b/tdd_mcp-0.0.1.tar.gz",
"platform": null,
"description": "# TDD-MCP Server (Experimental)\n\nA 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.\n\n## What This MCP Server Does\n\n**TDD-MCP acts as your TDD coach**, guiding you through proper Test-Driven Development cycles by:\n\n- **\ud83d\udd04 Enforcing the 3-phase TDD cycle**: Write failing test \u2192 Implement \u2192 Refactor \u2192 Repeat\n- **\ud83c\udfaf Maintaining focus on one goal at a time** with clear success criteria\n- **\ud83d\udcdd Tracking your progress** through persistent session state\n- **\ud83d\udee1\ufe0f Guiding against TDD violations** like implementing before writing tests\n- **\ud83e\udded Providing contextual guidance** at every step\n\n## \u26a0\ufe0f Important Considerations\n\n**Token Usage Warning**\nThis 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.\n\n**Not Ideal For:**\n- Large-scale refactoring or architectural changes\n- Simple CRUD operations or boilerplate code\n- When you need to generate many files quickly\n- Prototyping or exploratory development phases\n\n## Quickstart Guide\n\nGet up and running with TDD-MCP in minutes:\n\n### 1. Configure the MCP Server\n\nChoose your AI editor and add TDD-MCP to your configuration:\n\n**VS Code with Copilot Chat:**\n```json\n// .vscode/mcp.json\n{\n \"servers\": {\n \"tdd-mcp\": {\n \"type\": \"stdio\",\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"-m\", \"tdd_mcp.main\"],\n \"cwd\": \"/path/to/tdd-mcp\"\n }\n }\n}\n```\n\n**Cursor:**\n```json\n// ~/.cursor/mcp.json\n{\n \"mcpServers\": {\n \"tdd-mcp\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"-m\", \"tdd_mcp.main\"],\n \"cwd\": \"/path/to/tdd-mcp\"\n }\n }\n}\n```\n\n### 2. Start a New Agent Chat\n\nOpen your AI editor and start a new conversation. The TDD-MCP server will automatically connect.\n\n### 3. Initialize TDD-MCP\n\nTeach your AI editor the basics of TDD-MCP by using the built-in initialize prompt:\n\n**In VS Code with Copilot Chat:**\n```\n@tdd-mcp.initialize\n```\n\n**In other editors, paste this:**\n\nSome 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.\n\n\n### 4. Plan Your Session\n\nStart planning with the session wizard:\n\n```\nI want to implement a password validator function. \nPlease use the start_session_wizard prompt to help me set up the session parameters.\n```\n\nOr directly ask your AI:\n\n```\nHelp me start a TDD session for implementing a password validator that checks:\n- Minimum 8 characters\n- At least one uppercase letter\n- At least one number\n```\n\n### 5. Start Your TDD Session\n\nYour AI will call `start_session()` with the planned parameters:\n\n```python\nstart_session(\n goal=\"Implement password validator with length, uppercase, and number requirements\",\n test_files=[\"tests/test_password_validator.py\"],\n implementation_files=[\"src/password_validator.py\"],\n run_tests=[\"pytest tests/test_password_validator.py -v\"]\n)\n```\n\n### 6. Follow the Red-Green-Refactor Flow\n\nWork with your AI through the TDD cycle:\n\n**\ud83d\udd34 Red Phase (Write Failing Test):**\n```\nLet's write our first failing test for minimum length validation.\n```\n\n**\ud83d\udfe2 Green Phase (Make Test Pass):**\n```\nNow let's implement the minimal code to make this test pass.\n```\n\n**\ud83d\udd35 Refactor Phase (Improve Code):**\n```\nLet's refactor to improve the code quality while keeping tests green.\n```\n\n### 7. Add Logs Anytime\n\nCapture your thoughts during development:\n\n```\nLog: \"Considering if we should validate empty strings separately\"\n```\n\n```\nLog: \"Found a good pattern for chaining validation rules\"\n```\n\n### 8. End the Session\n\nWhen you've reached your goal:\n\n```\nWe've successfully implemented the password validator with all requirements. \nPlease call end_session() to complete our TDD session.\n```\n\nYou'll get a summary of what was accomplished during the session.\n\n### \ud83c\udf89 You're Ready!\n\nYou now have:\n- \u2705 A working TDD workflow with AI guidance\n- \u2705 Complete session history and audit trail\n- \u2705 Disciplined test-first development\n- \u2705 Evidence-based phase transitions\n\n## How It Works\n\n### TDD Phase Management\nThe server maintains strict control over the TDD workflow:\n\n1. **\ud83d\udcdd WRITE_TEST Phase**: You can only modify test files. Write ONE failing test that captures the next small increment of functionality.\n\n2. **\u2705 IMPLEMENT Phase**: You can only modify implementation files. Write the minimal code needed to make the failing test pass.\n\n3. **\ud83d\udd27 REFACTOR Phase**: You can modify both test and implementation files. Improve code quality without changing behavior.\n\nEach phase transition requires **evidence** - you must describe what you accomplished to justify moving to the next phase.\n\n### State Persistence\n- Sessions persist across server restarts\n- Complete audit trail of all actions through event sourcing\n- Pause/resume functionality for long-running projects\n- Session history shows your TDD journey\n\n### File Access Guidance\nThe server provides guidance on which files to modify based on your current TDD phase:\n- **WRITE_TEST**: Only test files specified in your session\n- **IMPLEMENT**: Only implementation files specified in your session\n- **REFACTOR**: Both test and implementation files\n\n*Note: This is guidance for your AI assistant - the server doesn't enforce file system restrictions.*\n\n## When to Use TDD-MCP?\n\n**\ud83c\udfaf Mission-Critical Features**\n- Use when building components where bugs have serious consequences\n- Perfect for core business logic, security features, or data integrity functions\n- When you need rock-solid reliability and comprehensive test coverage\n\n**\ud83d\udccf Small, Focused Goals**\n- Best for goals that fit within a single context window\n- Ideal for individual functions, classes, or small modules\n- When you can clearly define \"done\" in a few sentences\n\n**\ud83e\udde0 Learning TDD Discipline**\n- Excellent for developers new to Test-Driven Development\n- Helps build muscle memory for the Red-Green-Refactor cycle\n- Provides structured guidance when working with AI assistants\n\n**\ufffd Complex Logic Development**\n- When you need to think through edge cases step by step\n- For algorithms or business rules that benefit from incremental development\n- When you want to document your thought process through tests\n\n\n## Available MCP Tools & Prompts\n\nWhen you connect to the TDD-MCP server, you get access to these tools and prompts:\n\n### \ud83d\ude80 Session Management Tools\n\n#### `start_session(goal, test_files, implementation_files, run_tests, custom_rules)`\nStart a new TDD session with:\n- **goal**: Clear, testable objective with definition of done\n- **test_files**: List of test files you're allowed to modify (e.g., `[\"tests/test_auth.py\"]`)\n- **implementation_files**: List of implementation files you're allowed to modify (e.g., `[\"src/auth.py\"]`)\n- **run_tests**: Commands to run your tests (e.g., `[\"pytest tests/test_auth.py -v\"]`)\n- **custom_rules**: Additional TDD rules specific to your project (optional)\n\nReturns: Session ID string\n\n#### `update_session(...)` \nUpdate any session parameters as your project evolves. Returns `True` if successful.\n\n#### `pause_session()` / `resume_session(session_id)`\nPause your current session and resume it later (even after server restart). \n- `pause_session()` returns the session ID\n- `resume_session(session_id)` returns a `TDDSessionState` object\n\n#### `end_session()`\nComplete your session and get a summary of what was accomplished. Returns summary string.\n\n### \ud83d\udd04 Workflow Control Tools\n\n#### `get_current_state()`\n**Use this frequently!** Returns a `TDDSessionState` object with your current TDD phase, cycle number, allowed files, and suggested next actions.\n\n#### `next_phase(evidence_description)`\nMove to the next TDD phase by providing evidence of what you accomplished. Returns a `TDDSessionState` object with the new phase:\n- From WRITE_TEST \u2192 IMPLEMENT: \"wrote failing test for user login validation\"\n- From IMPLEMENT \u2192 REFACTOR: \"implemented basic login function, test now passes\"\n- From REFACTOR \u2192 WRITE_TEST: \"refactored login code for better error handling\"\n\n#### `rollback(reason)`\nGo back to the previous phase if you made a mistake. Returns a `TDDSessionState` object with the previous phase:\n- \"realized I implemented too much functionality in one test\"\n- \"need to write a better test first\"\n\n### \ud83d\udcdd Logging & History Tools\n\n#### `log(message)`\nAdd notes to your session without affecting workflow state. Returns `True` if successful:\n- \"considering edge case for empty passwords\"\n- \"found useful pattern in existing codebase\"\n\n#### `history()`\nView your complete TDD journey - all phase transitions, logs, and evidence. Returns a list of formatted history strings.\n\n### \ud83e\udded Guidance & Help\n\n#### `initialize` (Prompt)\nGet comprehensive instructions for using TDD-MCP effectively. **Use this first** when starting with the server.\n\n#### `start_session_wizard(goal)` (Prompt)\nGet personalized guidance for setting up your TDD session. Analyzes your workspace and suggests optimal session parameters.\n\n#### `quick_help()`\nGet context-aware help and shortcuts based on your current phase and session state. Returns a dictionary with available actions and reminders.\n\n\n## How Session Management Works\n\n### State Persistence\nYour TDD sessions are automatically saved and persist across server restarts:\n\n**\ud83d\udd04 Event Sourcing**\n- Every action you take is recorded as an event\n- Your session state is calculated from these events\n- Complete audit trail of your TDD journey\n- Rollback capability to previous phases\n\n**\ud83d\udcbe Automatic Saving**\n- Sessions are saved to `.tdd-mcp/sessions/` directory\n- Each session gets a unique JSON file\n- No manual save/load required\n- Safe concurrent access with file locking\n\n**\u23f8\ufe0f Pause & Resume**\n- Pause your session anytime with `pause_session()`\n- Resume later with `resume_session(session_id)`\n- Perfect for long-running projects\n- Session state preserved exactly as you left it\n\n### Session Lifecycle\n\n```\n\ud83d\udccb PLANNING\n\u251c\u2500\u2500 Use start_session_wizard prompt for guided setup\n\u251c\u2500\u2500 Review suggested parameters\n\u2514\u2500\u2500 Call start_session() to begin (returns session ID)\n\n\ud83d\udd04 ACTIVE TDD CYCLES\n\u251c\u2500\u2500 Phase: WRITE_TEST \u2192 write failing test\n\u251c\u2500\u2500 Phase: IMPLEMENT \u2192 make test pass \n\u251c\u2500\u2500 Phase: REFACTOR \u2192 improve code quality\n\u2514\u2500\u2500 Repeat cycles until goal achieved\n\n\u23f8\ufe0f PAUSE/RESUME (Optional)\n\u251c\u2500\u2500 Call pause_session() to save state (returns session ID)\n\u251c\u2500\u2500 Server can restart, system can reboot\n\u2514\u2500\u2500 Call resume_session() to continue (returns TDDSessionState)\n\n\u2705 COMPLETION\n\u251c\u2500\u2500 Call end_session() when goal achieved (returns summary)\n\u2514\u2500\u2500 Get summary of what was accomplished\n```\n\n### File Access Guidance\n\nThe server provides guidance on which files should be modified based on your current TDD phase:\n\n- **\ud83d\udcdd WRITE_TEST Phase**: Only your specified test files should be modified\n- **\u2705 IMPLEMENT Phase**: Only your specified implementation files should be modified \n- **\ud83d\udd27 REFACTOR Phase**: Both test and implementation files can be modified\n\n*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.*\n\n\n## Development\n\n### Prerequisites\n\n- Python 3.12+\n- [uv](https://github.com/astral-sh/uv) for dependency management\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/tinmancoding/tdd-mcp.git\ncd tdd-mcp\n\n# Install dependencies\nuv sync\n\n# Install development dependencies\nuv sync --group dev\n```\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=tdd_mcp\n\n# Run specific test file\nuv run pytest tests/domain/test_session.py\n\n# Run tests in watch mode\nuv run pytest-watch\n```\n\n### Development Workflow\n\nThe project itself follows TDD principles:\n\n1. **Write failing tests first** for new functionality\n2. **Implement minimal code** to make tests pass\n3. **Refactor** for code quality while keeping tests green\n\n### Project Structure\n\n```\nsrc/tdd_mcp/\n\u251c\u2500\u2500 main.py # FastMCP server entry point\n\u251c\u2500\u2500 handlers/ # MCP tool handlers\n\u2502 \u251c\u2500\u2500 session_handlers.py # start_session, update_session, etc.\n\u2502 \u251c\u2500\u2500 workflow_handlers.py # next_phase, rollback, get_current_state\n\u2502 \u251c\u2500\u2500 logging_handlers.py # log, history\n\u2502 \u2514\u2500\u2500 guidance_handlers.py # initialize, quick_help\n\u251c\u2500\u2500 domain/ # Core business logic\n\u2502 \u251c\u2500\u2500 session.py # TDDSession class\n\u2502 \u251c\u2500\u2500 events.py # Event schemas and TDDEvent\n\u2502 \u2514\u2500\u2500 exceptions.py # Custom exception classes\n\u251c\u2500\u2500 repository/ # Data persistence layer\n\u2502 \u251c\u2500\u2500 base.py # Abstract TDDSessionRepository\n\u2502 \u2514\u2500\u2500 filesystem.py # FileSystemRepository implementation\n\u2514\u2500\u2500 utils/ # Supporting utilities\n \u251c\u2500\u2500 config.py # Environment variable handling\n \u2514\u2500\u2500 logging.py # Logging configuration\n```\n\n### Building and Publishing\n\n```bash\n# Build the package\nuv build\n\n# Install locally for testing\nuv pip install -e .\n\n# Publish to PyPI (maintainers only)\nuv publish\n```\n\n## Architecture\n\n### Event Sourcing\n- **Complete Audit Trail**: Every action, phase change, and log entry preserved\n- **Rollback Capability**: Navigate backward through phases when needed\n- **State Consistency**: Current state calculated from authoritative event stream\n- **Future-Proof**: New event types can be added without breaking existing sessions\n\n### Repository Pattern\n- **Pluggable Storage**: Abstract repository interface with filesystem implementation\n- **Concurrency Safety**: Lock file mechanism prevents concurrent session access\n- **Session Persistence**: JSON event streams survive server restarts\n\n### MCP Integration\n- **FastMCP V2**: Built on the latest MCP framework\n- **Rich Tool Set**: 12 comprehensive tools for session and workflow management\n- **Error Handling**: Structured error responses with recovery suggestions\n\n## Configuration\n\n### Environment Variables\n\n- **`TDD_MCP_SESSION_DIR`**: Custom session storage directory (default: `.tdd-mcp/sessions/`)\n- **`TDD_MCP_LOG_LEVEL`**: Logging verbosity - `debug|info|warn|error` (default: `info`)\n- **`TDD_MCP_USE_MEMORY_REPOSITORY`**: Use in-memory storage for testing (default: `false`)\n\n### Session Structure\n\nSessions are stored as JSON event streams:\n\n```json\n{\n \"schema_version\": \"1.0\",\n \"events\": [\n {\n \"timestamp\": \"2025-07-11T10:30:00Z\",\n \"event_type\": \"session_started\",\n \"data\": {\n \"goal\": \"Implement user authentication\",\n \"test_files\": [\"tests/test_auth.py\"],\n \"implementation_files\": [\"src/auth.py\"],\n \"run_tests\": [\"pytest tests/test_auth.py -v\"]\n }\n }\n ]\n}\n```\n\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Follow TDD: Write tests first, then implement\n4. Ensure all tests pass (`uv run pytest`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/tinmancoding/tdd-mcp/issues)\n- **Documentation**: See the [PRD](aidocs/PRD-initial.md) for detailed specifications\n- **MCP Protocol**: [Model Context Protocol](https://modelcontextprotocol.io/)\n\n---\n\n**Practice what we preach**: This TDD-MCP server was built using the same TDD discipline it aims to enforce!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Model Context Protocol (MCP) server that enforces disciplined Test-Driven Development workflows",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://github.com/tinmancoding/tdd-mcp",
"Issues": "https://github.com/tinmancoding/tdd-mcp/issues",
"Repository": "https://github.com/tinmancoding/tdd-mcp"
},
"split_keywords": [
"development-workflow",
" event-sourcing",
" mcp",
" tdd",
" test-driven-development",
" testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "29ad48fb63818676204c43de1a6261312b125e8ea31ee3920f7be49797924d4c",
"md5": "f3d49cf65b78e033f7b0092abc50a23b",
"sha256": "05af4bc0149fa8893c14d1a63ca9cfe2bc4ef802007021f0756c034371b91aaa"
},
"downloads": -1,
"filename": "tdd_mcp-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f3d49cf65b78e033f7b0092abc50a23b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 27082,
"upload_time": "2025-07-12T16:52:05",
"upload_time_iso_8601": "2025-07-12T16:52:05.419407Z",
"url": "https://files.pythonhosted.org/packages/29/ad/48fb63818676204c43de1a6261312b125e8ea31ee3920f7be49797924d4c/tdd_mcp-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "50ba2ebcea2c4e6465e1e18a7eb0c1c7a7e64849cbe2ef8f0fe0484e04a4c49b",
"md5": "4032983eec1c3bdfbea1b522255d26c4",
"sha256": "99002d9fb325bffeb1fc73067366d7e5b0f4f1dcd74806125545c1294dbd6ad3"
},
"downloads": -1,
"filename": "tdd_mcp-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "4032983eec1c3bdfbea1b522255d26c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 73080,
"upload_time": "2025-07-12T16:52:07",
"upload_time_iso_8601": "2025-07-12T16:52:07.037685Z",
"url": "https://files.pythonhosted.org/packages/50/ba/2ebcea2c4e6465e1e18a7eb0c1c7a7e64849cbe2ef8f0fe0484e04a4c49b/tdd_mcp-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 16:52:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tinmancoding",
"github_project": "tdd-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tdd-mcp"
}
JSON
