How do I use TDD-MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TDD-MCP Start a TDD session for a password validator checking min 8 chars and uppercase." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

TDD-MCP

by tinmancoding

Overview Schema Related Servers Score Discussions

Python

Local

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

Related MCP server: Software Planning Tool

⚠️ 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!

Available Tools

11 tools

end_sessionA

End the current active session and return summary.

Returns: Summary of the completed session

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that the tool ends the session and returns a summary, but does not mention side effects such as whether the session is permanently ended, if data is saved, or if it can be undone. No annotations are provided to compensate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two short sentences that convey the essential action and return value. No extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the tool has an output schema (not shown) reducing the need to explain returns, the description lacks context on prerequisites (e.g., must have an active session), consequences (e.g., irreversible), and error states. Given the simplicity, it is adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, and the input schema coverage is 100% trivially. Per the rubric, 0 parameters baseline is 4. The description does not need to add parameter meaning since none exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool ends the current active session and returns a summary. It distinguishes from sibling tools like pause_session (which suspends) and next_phase (which advances), making its purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus alternatives like pause_session or resume_session. The usage is implied by the name and description, but no when-not-to-use or context of alternatives is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_current_stateA

Get current state of the active session.

Returns: Current session state with all properties calculated

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`session_id`	Yes
`current_phase`	Yes
`cycle_number`	Yes
`goal`	Yes
`test_files`	Yes
`implementation_files`	Yes
`run_tests`	Yes
`custom_rules`	Yes

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description lacks disclosure of side effects (none expected) or requirements (e.g., active session). Does not confirm read-only nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, zero waste. Front-loaded with purpose and return info.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a zero-param tool with output schema. Could mention session activity requirement or that it is non-destructive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%. Description adds no extra parameter info, but none is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb 'Get' and specific resource 'current state of the active session'. Distinguishes from sibling tools like start_session or end_session which modify state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use vs other read tools like history or log. No context about prerequisites or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

historyB

Get formatted session history for the current active session.

Returns: List of formatted history entries

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only says 'Get', implying a read-only operation, but does not explicitly state idempotency, side effects, or data freshness. Since there are no annotations, the description lacks necessary behavioral clarity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, consisting of two short sentences that front-load the core purpose. It avoids unnecessary details. However, it could be slightly improved by including a usage hint in the same concise manner.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and the presence of an output schema, the description is sufficiently complete for a simple retrieval tool. It states the action and the return type. It does not cover edge cases like empty history, but that is minor for this context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the input schema requires no description for parameters. Per guidelines, 0 parameters yields a baseline of 4. The description does not need to add parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and resource 'formatted session history for the current active session'. It specifies that it returns a list of formatted history entries, which distinguishes it from sibling tools like 'get_current_state' (current state) and 'log' (logging). However, it does not explicitly differentiate from other history-related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives like 'log' or 'get_current_state'. There are no instructions about prerequisites, limitations, or contextual cues for invoking 'history'. The description simply states what it does without any usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

logA

Add a log entry to the current session without affecting workflow state.

Args: message: Log message to add to session history

Returns: True if log entry was successfully added

ParametersJSON Schema

Name	Required	Description	Default
`message`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It clearly states the tool does not affect workflow state and indicates the return value (True). It lacks details on potential side effects like log storage limits or visibility, but for a simple logging tool, it is sufficiently transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: a single key sentence followed by a brief args/returns section. Every part is essential, and the most important information (purpose and behavioral trait) is at the beginning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (1 parameter, no enums, simple boolean return), the description covers the essential aspects: purpose, behavior, parameter meaning, and return value. It lacks information on error conditions or logging limitations, but overall it is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides basic semantics for the 'message' parameter: 'Log message to add to session history.' Given 0% schema coverage, it adds meaning beyond the schema's type string. However, it does not specify constraints like max length or acceptable formats, so it partially compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Add a log entry to the current session without affecting workflow state.' The verb 'Add' and specific resource 'log entry' clearly define its function. It also distinguishes from sibling tools like 'update_session' which modify state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by emphasizing 'without affecting workflow state,' guiding agents to use it for logging without side effects. However, it does not explicitly state when not to use it or mention alternatives like 'history' for retrieval.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

next_phaseA

Move to the next phase in the TDD cycle.

Args: evidence_description: Description of what was accomplished to justify transition

Returns: New session state after phase transition

ParametersJSON Schema

Name	Required	Description	Default
`evidence_description`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`session_id`	Yes
`current_phase`	Yes
`cycle_number`	Yes
`goal`	Yes
`test_files`	Yes
`implementation_files`	Yes
`run_tests`	Yes
`custom_rules`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It mentions the return value (new session state) but does not disclose side effects, constraints (e.g., whether a session must be active), or behavior if the phase cannot transition.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise with no wasted words. The args/returns section provides clear structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity (one param, no nested objects, output schema present), the description covers the essential purpose, parameter, and return. Minor gap: no mention of session dependency or TDD cycle details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description adds meaning by explaining evidence_description is a justification for transition, going beyond the schema's type-only info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool moves to the next phase in the TDD cycle, which distinguishes it from siblings like start_session or rollback that manage session state rather than progressing phases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives (e.g., rollback, log), nor any prerequisites or conditions for using it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pause_sessionB

Pause the current active session.

Returns: Session ID of the paused session

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavioral traits. It only states the action and return value (Session ID), but does not discuss whether the operation is destructive, reversible, or what happens to ongoing processes. This is insufficient for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences, front-loading the purpose and including the return value. Every word is necessary with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with zero parameters and a clear action, the description is mostly complete, stating purpose and return value. It could benefit from additional behavioral context (e.g., idempotency) but remains adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters (schema coverage 100% as empty), so the description does not need to add parameter meaning. Baseline for zero parameters is 4, and the description meets this expectation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Pause') and resource ('current active session'), distinguishing it from siblings like 'resume_session' and 'end_session'. However, it does not explicitly differentiate the semantics of 'pause' versus 'end' or 'resume', which could be clarified.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as 'end_session' or 'resume_session'. The description lacks any context for appropriate usage or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

quick_helpA

Provide context-aware shortcuts and help based on current session state.

Returns: Dictionary with context-aware help and shortcuts

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and description does not disclose behavioral traits such as read-only nature, side effects, or any state modifications. Only states it returns a dictionary.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no unnecessary words. Efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, existing output schema, and sibling tools, the description is adequate but vague. Lacks specifics on what 'context-aware' means and how shortcuts are provided.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so baseline is 4. Description adds no parameter meaning, but with no schema coverage needed, the score is reasonable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides context-aware help and shortcuts. It distinctly differentiates from sibling tools which are session management and logging operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use or when not to use this tool compared to alternatives like get_current_state. Only implied by 'provide help'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resume_sessionA

Resume an existing session by session ID.

Args: session_id: Unique identifier for the session to resume

Returns: Current state of the resumed session

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`session_id`	Yes
`current_phase`	Yes
`cycle_number`	Yes
`goal`	Yes
`test_files`	Yes
`implementation_files`	Yes
`run_tests`	Yes
`custom_rules`	Yes

TDQS

A3.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose behavior. It only mentions resuming and returning state, but omits prerequisites (session must exist and be paused), side effects, or error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with action and result, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with output schema mentioned, the description covers the core functionality but could mention that the session must be in a resumable state for clarity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The parameter session_id is described as 'Unique identifier for the session to resume', adding value beyond the schema's type-only definition. Schema coverage is 0%, so description compensates well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool resumes an existing session by ID, and this purpose is distinct from siblings like start_session, pause_session, end_session which handle different session lifecycle actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied (resume when you have a session ID), but no explicit guidance on when to use versus alternatives like start_session for new sessions or pause_session before resume.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rollbackC

Rollback to the previous phase.

Args: reason: Reason for rolling back

Returns: New session state after rollback

ParametersJSON Schema

Name	Required	Description	Default
`reason`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`session_id`	Yes
`current_phase`	Yes
`cycle_number`	Yes
`goal`	Yes
`test_files`	Yes
`implementation_files`	Yes
`run_tests`	Yes
`custom_rules`	Yes

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, and the description only says 'Rollback to the previous phase' without disclosing if the operation is destructive, what happens to the current state, or if there are side effects. The return of 'New session state after rollback' is mentioned but without behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise, using a clear Args/Returns structure. However, it may be too terse, sacrificing useful details for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's role (rollback) and the presence of an output schema, the description should explain the effect of rollback on the session state. It does not, leaving gaps about when and why to rollback compared to siblings like 'history' or 'next_phase'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one required parameter 'reason' of type string. The description restates it as 'reason: Reason for rolling back', adding no extra meaning or constraints beyond the schema. Schema description coverage is 0%, but the parameter is simple; still, the description does not enhance understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Rollback to the previous phase', which is a specific verb+resource and clearly distinguishes from sibling 'next_phase'. However, it lacks any additional detail about what rollback entails.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'next_phase' or 'end_session'. There is no mention of prerequisites, when-not to use, or examples.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_sessionA

Start a new TDD session.

Args: goal: High-level session objective and definition of done test_files: Files where agent can write tests (explicit paths) implementation_files: Files where agent can write implementation run_tests: Commands/instructions for running test suite custom_rules: Additional rules appended to global TDD rules

Returns: Session ID of the created session

ParametersJSON Schema

Name	Required	Description	Default
`goal`	Yes
`test_files`	Yes
`implementation_files`	Yes
`run_tests`	Yes
`custom_rules`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes starting a session and returning a session ID, but lacks details on side effects like whether it ends existing sessions or requires a clean state. No annotations provided to compensate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Docstring format with clear Args and Returns sections. First sentence states purpose immediately. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all necessary parameters and return value for starting a session. Could mention potential conflicts (e.g., only one active session), but overall sufficient given the tool's role.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the Arg section adds meaningful descriptions for each parameter, explaining their roles. However, it lacks details on format constraints or expected content.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Start a new TDD session', giving a specific verb and resource. Differentiates from sibling tools like end_session, pause_session, and resume_session.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is used to initiate a session, but it doesn't explicitly state when to use it or when not to, nor does it mention alternatives. Usage is clear by context but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_sessionC

Update an existing active session.

Args: goal: Updated session objective (optional) test_files: Updated test files (optional) implementation_files: Updated implementation files (optional) run_tests: Updated test commands (optional) custom_rules: Updated custom rules (optional)

Returns: True if update was successful

ParametersJSON Schema

Name	Required	Description	Default
`goal`	No
`test_files`	No
`implementation_files`	No
`run_tests`	No
`custom_rules`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description mentions it returns True on success but lacks details on error behavior, idempotency, or what happens if the session is not active. With no annotations, more behavioral detail is needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is fairly concise but repeats parameter names that are already in the schema. The Args/Returns format is clean.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 optional parameters at 0% schema coverage and no annotations, the description is insufficient. It does not cover validation, side-effects, or relationship to other session management tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Parameters are listed with their names and optionality, but no additional meaning beyond the schema (which has 0% coverage). For example, 'goal' is not explained beyond 'Updated session objective'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool updates an existing active session and lists the updatable fields. However, it does not differentiate from sibling tools like end_session or pause_session.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 start_session or pause_session. No prerequisites or contextual advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

11 tool updatesv0.0.1May 30, 2026
- First observedend_session
- First observedget_current_state
- First observedhistory
- First observedlog
- First observednext_phase
- First observedpause_session
- First observedquick_help
- First observedresume_session
- First observedrollback
- First observedstart_session
- First observedupdate_session

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose covering session lifecycle, state queries, phase transitions, and logging. No two tools overlap in functionality.

Naming Consistency3/5

Most tools follow verb_noun pattern but 'history', 'log', 'rollback', 'next_phase', and 'quick_help' break the pattern. However, naming is still readable and generally predictable.

Tool Count5/5

With 11 tools covering session management, phase control, and auxiliary helpers, the count is well-suited to the domain—neither sparse nor bloated.

Completeness4/5

Core session lifecycle (start, end, pause, resume, update, phase transitions) is fully covered. Missing a 'list_sessions' tool but this is a minor gap.

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

PAPI: Persistent Adaptive Project IntelligenceOAuth
io.github.getpapi
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
Coding Agents Autonomous Agents
27
Conducted MCP A
io.github.Mostov82
Stateless advisor + validator for Conducted Development: kickoff, artifact validation, rule checks.
Developer Tools
721
OolkinOAuth
com.oolkin
AI colleagues that keep your standards, your project and their reasoning between sessions
Knowledge & Memory Project Management Developer Tools
1
Norma by Quality CloudsOAuth
ai.qualityclouds
Deterministic AI code review, with an audit record. Governance inside the agent loop.
Code Analysis Developer Tools
11

Related MCP Servers

BusyBee
Coding Agents Autonomous Agents Developer Tools
nonibytes
F
license
Not graded
quality
Not graded
maintenance
Autonomous TDD coding agent that converts specifications into feature lists and implements them using test-driven development with pause/resume capabilities, live progress monitoring, and automatic git commits.
Updated 9 months ago (2025-12-13 03:28 UTC)
-
Software Planning Tool
Developer Tools Project Management
PhilippMT
A
license
A
quality
D
maintenance
Facilitates software development planning through interactive sessions that break down projects into manageable tasks with complexity scoring, code examples, and implementation plan management.
Updated a year ago (2025-03-14 09:36 UTC)
6
20
MIT
spec-driver-mcp
Developer Tools Project Management
linanwanttodo
A
license
A
quality
C
maintenance
Enables AI coding tools to follow a structured spec-driven development workflow with three phases: requirements, design, and tasks, ensuring approval before advancing.
Updated 3 months ago (2026-06-18 17:15 UTC)
10
MIT
SpecFlow MCP Server
Developer Tools Project Management
lyz530
A
license
Not graded
quality
D
maintenance
Provides an AI-driven four-stage software development workflow with role management, enabling structured requirements analysis, design, implementation, and testing.
Updated a year ago (2025-07-30 06:28 UTC)
1
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tinmancoding/tdd-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

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

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

`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()`