# Commitizen MCP Connector Refactoring Plan
## Overview
This directory contains the comprehensive refactoring plan for transforming the Commitizen MCP Connector from its current monolithic architecture to a maintainable, modular design.
## Current Problems
- **Monolithic Server**: 1000+ line `commitizen_server.py` with 19 MCP tools
- **Mixed Responsibilities**: Services handling multiple concerns
- **Scattered Configuration**: Config logic spread across classes
- **Inconsistent Error Handling**: Different patterns across tools
- **Test Organization**: 12 test files with some overlap
## Target Architecture
```
src/commit_helper_mcp/ # Phase 0: Renamed from commitizen_mcp_connector/
├── server/ # Phase 1: MCP Server Decomposition
│ ├── base_server.py # FastMCP setup and common utilities
│ ├── message_tools.py # 4 message-related MCP tools
│ ├── git_tools.py # 7 git operation MCP tools
│ ├── workflow_tools.py # 3 workflow MCP tools
│ ├── enhanced_tools.py # 5 enhanced analysis MCP tools
│ └── resources.py # 3 MCP resources
├── services/ # Phase 2: Service Layer Refactoring
│ ├── commitizen_core.py # Pure Commitizen operations
│ ├── gitpython_core.py # Pure GitPython operations (moved)
│ ├── commit_orchestrator.py # Git + Commitizen workflow orchestration
│ ├── repository_manager.py # Multi-repository handling
│ └── validation_service.py # Message validation logic
├── config/ # Phase 3: Configuration Management
│ ├── settings.py # Application settings
│ ├── repository_config.py # Repository-specific config
│ └── plugin_config.py # Plugin configuration management
├── errors/ # Phase 4: Error Handling Standardization
│ ├── exceptions.py # Custom exception hierarchy
│ ├── handlers.py # Error handling decorators/utilities
│ └── responses.py # Standardized error response formats
└── plugin_adapters.py # Keep as-is (already well structured)
```
## Implementation Phases
### Phase 0: Project Rename (High Priority - Prerequisite)
- **Goal**: Rename project from "commitizen-mcp-connector" to "commit-helper-mcp"
- **Target**: Complete project rename with updated references
- **Effort**: 15 minutes
- **Files**: [task-00-project-rename.md](task-00-project-rename.md)
### Phase 1: MCP Server Decomposition (High Priority)
- **Goal**: Break 1000+ line server into 6 focused modules (~150-200 lines each)
- **Target**: No file over 300 lines
- **Effort**: 15 minutes
- **Files**: [task-01-server-decomposition.md](task-01-server-decomposition.md)
### Phase 2: Service Layer Refactoring (Medium Priority)
- **Goal**: Single responsibility per service
- **Target**: Clean separation between core operations and workflows
- **Effort**: 15 minutes
- **Files**: [task-02-service-refactoring.md](task-02-service-refactoring.md)
### Phase 3: Configuration Management (Medium Priority)
- **Goal**: Unified configuration system
- **Target**: Centralized config with validation
- **Effort**: 15 minutes
- **Files**: [task-03-configuration-management.md](task-03-configuration-management.md)
### Phase 4: Error Handling Standardization (Low Priority)
- **Goal**: Consistent error experience
- **Target**: Unified exception hierarchy and response formats
- **Effort**: 15 minutes
- **Files**: [task-04-error-handling.md](task-04-error-handling.md)
### Phase 5: Test Reorganization (Low Priority)
- **Goal**: Maintainable test suite
- **Target**: Logical test structure with shared fixtures
- **Effort**: 15 minutes
- **Files**: [task-05-test-reorganization.md](task-05-test-reorganization.md)
## Migration Strategy
### Backward Compatibility
- **No breaking changes** to MCP client interface
- **All existing tests must pass** after refactoring
- **Gradual migration** with feature flags if needed
### Implementation Order
1. **Phase 0** (Project rename) - Must be completed first to avoid conflicts
2. **Phase 1** (Server decomposition) - Can be done incrementally, tool by tool
3. **Phase 2** (Service refactoring) - Internal changes, no external impact
4. **Phase 3** (Configuration) - Additive improvements
5. **Phase 4** (Error handling) - Enhancement, not breaking changes
6. **Phase 5** (Test reorganization) - Maintenance improvement
### Success Metrics
- **File Size**: No file over 300 lines
- **Maintainability**: Easier to add new features
- **Team Development**: Multiple developers can work in parallel
- **Test Coverage**: Maintained at 100% for critical paths
## Benefits
### Immediate Benefits
- **Maintainability**: Smaller, focused files
- **Testability**: Isolated components
- **Code Review**: Smaller, focused changes
- **Debugging**: Clear separation of concerns
### Long-term Benefits
- **Extensibility**: Easy to add new tools/features
- **Team Development**: Multiple developers can work in parallel
- **Performance**: Lazy loading of unused modules
- **Documentation**: Each module can have focused docs
## Getting Started
1. Review the current architecture in the memory bank files
2. Start with Phase 0: [task-00-project-rename.md](task-00-project-rename.md)
3. Follow the implementation order for subsequent phases
4. Ensure all tests pass after each phase completion
## Status
- **Planning**: ✅ Complete
- **Phase 0**: ✅ Complete (2025-07-10)
- **Phase 1**: ✅ Complete
- **Phase 2**: ✅ Complete
- **Phase 3**: ✅ Complete
- **Phase 4**: ✅ Complete
- **Phase 5**: ✅ Complete
