Content
# TDD MCP Server v2.0
A complete Model Context Protocol (MCP) server providing **streamlined and powerful** Test-Driven Development (TDD) workflow support for AI coding assistants.
**Supported AI Tools:** Claude Desktop, Claude Code, Cursor, Codeium, and any MCP-compatible AI assistants.
## ✨ v2.0 New Features
### 🚀 Simplified Tool Architecture
- **Before**: 15 independent tools, complex to use
- **Now**: **3 main tools + subcommands**, concise and efficient
- **Backward Compatibility**: Supports old 15-tool system
### 🌐 Complete Internationalization Support
- **Chinese Priority**: Default Chinese interface, catering to domestic user habits
- **Bilingual Support**: Dynamic switching between Chinese and English
- **Localization**: All tool descriptions, parameter explanations, and error messages are localized
### 🔄 Session Automatic Management
- **Intelligent**: No need to manually create TDD sessions
- **Automatic Tracking**: RED→GREEN→REFACTOR cycle automatic management
- **State Awareness**: Intelligent identification of TDD development stages
## 🛠️ Core Tools (3 Main Tools)
### 1. `tdd` - TDD Core Workflow Tool
One-stop solution for Test-Driven Development:
- **Default Behavior**: Execute complete TDD process (recommended)
- **Subcommands**:
- `generate` - Generate test cases
- `implement` - Generate implementation code based on tests
- `test` - Run tests
- `coverage` - Analyze code coverage
- `refactor` - Provide refactoring suggestions
- `validate` - Validate TDD cycle
### 2. `feature` - Feature Management Tool
Project feature and requirement management:
- **Default Behavior**: Create new feature
- **Subcommands**:
- `create` - Create new feature (default)
- `update` - Update feature status
- `link` - Link files to features
- `find` - Find similar features
### 3. `tracking` - Test Tracking Tool
Test method execution tracking:
- **Default Behavior**: Register test methods
- **Subcommands**:
- `register` - Register test methods (default)
- `result` - Update test execution results
- `status` - Update test method status
## 🌍 Language and Framework Support
| Programming Language | Testing Framework | Status |
|----------|---------|------|
| **TypeScript/JavaScript** | Jest, Mocha, Vitest | ✅ Full Support |
| **Python** | pytest, unittest | ✅ Full Support |
| **Java** | JUnit 5 | ✅ Full Support |
| **C#** | xUnit, NUnit | ✅ Full Support |
| **Go** | Go Test | ✅ Full Support |
| **Rust** | Cargo test | ✅ Full Support |
| **PHP** | PHPUnit | ✅ Full Support |
## 🚀 Quick Start
### Prerequisites
- Node.js 18.0.0+
- npm or yarn
### Installation Steps
```bash
# Clone repository
git clone https://github.com/laonayan/tdd-mcp-server.git
cd tdd-mcp-server
# Install dependencies
npm install
# Build project
npm run build
# Test installation
npm test
```
## 🔧 Configuration Guide
### Claude Code (Recommended)
#### Quick Configuration - v2.0 New Tool System (Recommended)
```bash
claude mcp add tdd-server-v2 node "/absolute/path/tdd-mcp-server/dist/server.js" \
-e USE_NEW_TOOLS=true \
-e DEFAULT_LOCALE=en \
-e PROJECT_PATH="."
```
#### Traditional Tool System Configuration
```bash
claude mcp add tdd-server-legacy node "/absolute/path/tdd-mcp-server/dist/server.js" \
-e USE_NEW_TOOLS=false \
-e DEFAULT_LOCALE=en \
-e PROJECT_PATH="."
```
#### Configuration Example
**English Interface Configuration (Recommended)**:
```bash
claude mcp add tdd-server-v2 node "/Users/username/tdd-mcp-server/dist/server.js" \
-e USE_NEW_TOOLS=true \
-e DEFAULT_LOCALE=en \
-e PROJECT_PATH="/Users/username/my-project"
```
**Chinese Interface Configuration**:
```bash
claude mcp add tdd-server-v2 node "/Users/username/tdd-mcp-server/dist/server.js" \
-e USE_NEW_TOOLS=true \
-e DEFAULT_LOCALE=zh \
-e PROJECT_PATH="/Users/username/my-project"
```
#### Manual Configuration File Method
Create `.claude.json` in the project root directory:
```json
{
"mcpServers": {
"tdd-server-v2": {
"command": "node",
"args": ["/absolute/path/tdd-mcp-server/dist/server.js"],
"env": {
"USE_NEW_TOOLS": "true",
"DEFAULT_LOCALE": "en",
"PROJECT_PATH": "."
}
}
}
}
```
### Other AI Tool Configurations
#### Claude Desktop
Edit configuration file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"tdd-server-v2": {
"command": "node",
"args": ["/absolute/path/tdd-mcp-server/dist/server.js"],
"env": {
"USE_NEW_TOOLS": "true",
"DEFAULT_LOCALE": "en",
"PROJECT_PATH": "/your/project/path"
}
}
}
}
```
#### Cursor IDE
Create `.cursor/mcp.json` in the project root directory:
```json
{
"servers": {
"tdd-server-v2": {
"command": "node",
"args": ["/absolute/path/tdd-mcp-server/dist/server.js"],
"env": {
"USE_NEW_TOOLS": "true",
"DEFAULT_LOCALE": "en",
"PROJECT_PATH": "."
}
}
}
}
```
## 🎯 Tutorial
### Basic Usage - v2.0 Simplified Commands
#### 1. One-Click Complete TDD Process (Most Recommended)
```javascript
// English environment - automatically execute complete TDD process
tdd({
requirements: "Implement user login functionality, including email verification, password encryption, and JWT token generation"
})
```
**Execution Result**:
```
Complete TDD process execution completed:
✅ Generated test cases
✅ Generated minimal implementation
✅ Ran tests
✅ Analyzed coverage
✅ Provided refactoring suggestions
```
#### 2. Step-by-Step TDD Process
**RED Stage - Generate Test Cases**:
```javascript
tdd({
command: "generate",
requirements: "User login functionality",
language: "typescript",
framework: "jest",
testType: "unit"
})
```
**GREEN Stage - Generate Implementation Code**:
```javascript
tdd({
command: "implement",
testCode: `
describe('UserLogin', () => {
test('should authenticate user with valid credentials', () => {
const loginService = new LoginService();
const result = loginService.authenticate('user@example.com', 'password123');
expect(result.success).toBe(true);
expect(result.token).toBeDefined();
});
});
`,
language: "typescript"
})
```
**REFACTOR Stage - Code Refactoring**:
```javascript
tdd({
command: "refactor",
sourceCode: "..."
})
```
#### 3. Feature Management
**Create New Feature**:
```javascript
feature({
name: "Password Reset Functionality",
description: "Allow users to reset passwords via email",
acceptanceCriteria: [
"Users can request password reset",
"System sends reset link to email",
"Reset link expires after 1 hour",
"Users can set new password"
],
priority: "high",
estimatedHours: 8
})
```
**Find Similar Features**:
```javascript
feature({
command: "find",
query: "user authentication login password"
})
```
#### 4. Test Tracking
**Register Test Methods**:
```javascript
tracking({
featureId: "user-auth-feature",
name: "test_user_login_success",
filePath: "./src/__tests__/auth.test.ts",
framework: "jest",
testType: "unit"
})
```
### Complete Usage Scenario Examples
#### Scenario 1: New Feature Complete TDD Development
```
User: I want to implement a user authentication system using TDD, including registration, login, and JWT token generation
AI Assistant: I'll help you implement a user authentication system using TDD. Using the v2.0 simplified tools:
1. First, create a feature:
feature({
name: "User Authentication System",
description: "Implement user registration, login, and JWT token management",
acceptanceCriteria: [
"Users can register using email and password",
"Users can login with valid credentials",
"Successful login returns JWT token",
"Invalid credentials return error messages"
]
})
2. Execute complete TDD process:
tdd({
requirements: "User authentication system: user registration, login verification, JWT token generation and verification"
})
This will automatically complete:
✅ Generated comprehensive test cases
✅ Generated minimal implementation code
✅ Ran tests and verified
✅ Analyzed code coverage
✅ Provided refactoring suggestions
```
#### Scenario 2: Existing Project Feature Extension
```
User: My project already has user management functionality, now I want to add password reset functionality
AI Assistant: Let me help you extend existing functionality:
1. Find similar features:
feature({
command: "find",
query: "password reset forgot password email verification"
})
2. Add new feature based on existing architecture:
feature({
name: "Password Reset Functionality",
description: "Extend user management with secure password reset process"
})
3. Perform TDD for new feature:
tdd({
requirements: "Password reset functionality: email verification, temporary token, password update",
language: "typescript",
framework: "jest"
})
```
#### Scenario 3: Code Quality Improvement
```
User: I want to improve the test coverage and code quality of existing code
AI Assistant: I'll help you analyze and improve code quality:
1. Analyze existing test coverage:
tdd({
command: "coverage",
projectPath: "./"
})
2. Generate tests for modules with low coverage:
tdd({
command: "generate",
requirements: "Generate comprehensive unit tests for existing PaymentService module",
language: "typescript",
testType: "unit"
})
3. Refactor code to improve quality:
tdd({
command: "refactor",
sourceCode: "...existing code..."
})
```
### Advanced Usage
#### Custom TDD Workflow
```javascript
// Generate tests only, without executing the complete process
tdd({
command: "generate",
requirements: "Payment processing functionality",
language: "python",
framework: "pytest",
testType: "integration"
})
// Run tests and coverage analysis only
tdd({
command: "coverage",
projectPath: "./"
})
// Validate TDD best practices
tdd({
command: "validate"
})
```
#### Feature Lifecycle Management
```javascript
// Update feature status
feature({
command: "update",
featureId: "feature-123",
status: "in_progress",
progress: {
testsWritten: 15,
testsPass: 12,
coveragePercentage: 85
}
})
// Link files to features
feature({
command: "link",
featureId: "feature-123",
filePaths: [
"./src/payment.service.ts",
"./src/__tests__/payment.test.ts"
],
fileType: "implementation"
})
```
#### Test Method Detailed Tracking
```javascript
// Update test execution results
tracking({
command: "result",
methodId: "test-456",
result: {
duration: 150,
passed: true,
coverage: 92
}
})
```
## 🔧 Environment Configuration
### Environment Variables
| Variable Name | Description | Default Value |
|-------|------|-------|
| `USE_NEW_TOOLS` | Enable v2.0 new tool system | `false` |
| `DEFAULT_LOCALE` | Default language (en/zh) | `en` |
| `PROJECT_PATH` | Project path | `process.cwd()` |
### Development Commands
```bash
npm run build # Build project
npm run dev # Development mode
npm run start # Production mode
npm run test # Run tests
npm run test:watch # Watch mode tests
npm run clean # Clean build files
```
### Testing and Verification
```bash
# Run integration tests
./integration-test.sh
# Run unit tests
npm test
# Check build
npm run build
```
## 📊 System Architecture Comparison
### v2.0 New Architecture (Recommended)
```
3 main tools + subcommand system
├── tdd (Test-Driven Development)
│ ├── Default: Complete TDD process
│ ├── generate: Generate tests
│ ├── implement: Generate implementation
│ ├── test: Run tests
│ ├── coverage: Coverage analysis
│ ├── refactor: Refactoring suggestions
│ └── validate: Validate TDD cycle
├── feature (Feature Management)
│ ├── Default: Create feature
│ ├── update: Update status
│ ├── link: Link files
│ └── find: Find similar features
└── tracking (Test Tracking)
├── Default: Register test methods
├── result: Update execution results
└── status: Update method status
```
### v1.0 Traditional Architecture (Backward Compatible)
```
15 independent tools
├── generate_test_cases
├── implement_from_tests
├── run_tests
├── analyze_coverage
├── refactor_code
├── validate_tdd_cycle
├── createFeature
├── updateFeatureStatus
├── linkFeatureFiles
├── findSimilarFeatures
├── createTDDSession
├── updateTDDStage
├── registerTestMethod
├── updateTestExecutionResult
└── updateTestMethodStatus
```
## 🛠️ Troubleshooting
### Frequently Asked Questions
#### Switch Tool System Version
```bash
# Use v2.0 new tool system (recommended)
USE_NEW_TOOLS=true node dist/server.js
# Use v1.0 traditional tool system
USE_NEW_TOOLS=false node dist/server.js
```
#### Language Switching
```bash
# English interface (default)
DEFAULT_LOCALE=en node dist/server.js
# Chinese interface
DEFAULT_LOCALE=zh node dist/server.js
```
#### Verify Configuration
```bash
# Check tool list in Claude Code
/mcp list
# Check specific server tools
/mcp tools tdd-server-v2
# Test tool connection
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
USE_NEW_TOOLS=true DEFAULT_LOCALE=en node dist/server.js
```
#### Integration Test Verification
```bash
# Run complete integration test
./integration-test.sh
```
# Manual Testing of New Tool System
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"tdd","arguments":{"requirements":""}}}' | \
USE_NEW_TOOLS=true DEFAULT_LOCALE=en node dist/server.js
### Performance Optimization
#### v2.0 System Advantages
- **Simplified API**: 3 tools replace 15 tools, reducing tool switching overhead
- **Intelligent Defaults**: Most parameters have reasonable default values, reducing configuration complexity
- **Automatic Session Management**: No need to manually manage TDD session status
- **Localization Support**: Automatically switch interface language based on configuration
## 📈 Latest Updates
### v2.0.0 (Current Version)
- ✅ **Simplified Architecture**: 15 tools merged into 3 main tools + subcommands
- ✅ **Internationalization**: Complete Chinese and English support, default Chinese interface
- ✅ **Automation**: Automatic session management, intelligent TDD process
- ✅ **Compatibility**: Maintain complete backward compatibility with the v1.0 tool system
- ✅ **Test Coverage**: 115 test cases, including 9 integration test scenarios
### Test Status
- **Unit Tests**: 111 passed ✅
- **Integration Tests**: 9 scenarios all passed ✅
- **Build Status**: No errors ✅
- **Compatibility**: Both new and old tool systems work normally ✅
## 🏗️ Project Structure
```
tdd-mcp-server/
├── src/
│ ├── handlers/
│ │ ├── tools.ts # v1.0 traditional 15-tool system
│ │ ├── new-tools.ts # v2.0 new 3-tool system
│ │ ├── resources.ts # File and report access
│ │ └── prompts.ts # TDD workflow prompts
│ ├── services/ # Core business logic
│ │ ├── storage.service.ts
│ │ ├── feature-management.service.ts
│ │ ├── test-generator.ts
│ │ ├── code-generator.ts
│ │ └── ...
│ ├── i18n.ts # Internationalization service
│ └── types/ # TypeScript type definitions
├── examples/
│ └── v2-usage-guide.md # v2.0 detailed usage guide
├── CLAUDE.md # Claude Code guidance document
├── integration-test.sh # Integration test script
└── dist/ # Build output
```
## 🤝 Contribution Guide
We welcome contributions! Especially:
### Priority Requirements
1. **New Test Framework Support** - Add more test frameworks
2. **Language Extension** - Support more programming languages
3. **AI Tool Integration** - Support more AI programming assistants
4. **Localization** - Support more language interfaces
### Development Environment Setup
```bash
git clone https://github.com/laonayan/tdd-mcp-server.git
cd tdd-mcp-server
npm install
npm run dev
npm run test:watch
```
## 📄 Open-Source License
MIT License - See [LICENSE](LICENSE) file for details.
## 🆘 Get Support
- 🐛 **Bug Report**: [GitHub Issues](https://github.com/laonayan/tdd-mcp-server/issues)
- 💬 **Feature Suggestion**: [GitHub Discussions](https://github.com/laonayan/tdd-mcp-server/discussions)
- 📖 **Usage Documentation**: [examples/v2-usage-guide.md](examples/v2-usage-guide.md)
---
**🎯 Get Started with v2.0 Simplified TDD Development!**
Transform your development workflow with intelligent test-driven development support across all major AI programming assistants. v2.0 brings a more concise, intelligent, and localized TDD experience.
