# Implementation Plan: Security-Focused CWD-Only Operations
## Overview
This document outlines the implementation plan for converting the Commit Helper MCP to a security-focused architecture that only operates on the current working directory. This is a breaking change that removes all `repo_path` parameters and environment variable support.
## Phase 1: Create Secure Repository Manager
### 1.1 Create CWD Context Model
**File**: `src/commit_helper_mcp/security/models.py`
```python
from dataclasses import dataclass, field
import os
@dataclass
class CWDContext:
"""Current working directory context."""
cwd_path: str = field(default_factory=os.getcwd)
is_valid_directory: bool = field(default=False)
is_git_repository: bool = field(default=False)
validation_error: Optional[str] = field(default=None)
```
### 1.2 Create Secure Repository Manager
**File**: `src/commit_helper_mcp/security/manager.py`
```python
import os
from .models import CWDContext
class SecureRepositoryManager:
"""Repository manager that only operates on CWD."""
def __init__(self):
self._context = CWDContext()
self._validate_cwd()
def get_repository_path(self) -> str:
"""Always returns current working directory."""
return os.getcwd()
def _validate_cwd(self):
"""Validate current working directory."""
# Implementation as designed
```
### 1.3 Create Validation Functions
**File**: `src/commit_helper_mcp/security/validation.py`
```python
def validate_cwd_for_operation() -> Tuple[bool, Optional[Dict[str, Any]]]:
"""Validate CWD is suitable for operations."""
# Implementation as designed
def validate_cwd_for_git_operation() -> Tuple[bool, Optional[Dict[str, Any]]]:
"""Validate CWD is a git repository."""
# Implementation as designed
```
## Phase 2: Remove Path Parameters from Tools
### 2.1 Update Message Tools
**File**: `src/commit_helper_mcp/server/message_tools.py`
Remove all `repo_path` parameters:
```python
# Before
@mcp.tool()
def generate_commit_message(
type: str,
subject: str,
repo_path: Optional[str] = None
) -> Dict[str, Any]:
# Implementation
# After
@mcp.tool()
def generate_commit_message(
type: str,
subject: str
) -> Dict[str, Any]:
"""Generate commit message for current directory."""
# Validate CWD
is_valid, error = validate_cwd_for_git_operation()
if not is_valid:
return error
# Always use CWD
service = CommitzenService(repo_path=os.getcwd())
# Rest of implementation
```
### 2.2 Update Git Tools
**File**: `src/commit_helper_mcp/server/git_tools.py`
Remove all `repo_path` parameters from all 7 git tools.
### 2.3 Update Enhanced Tools
**File**: `src/commit_helper_mcp/server/enhanced_tools.py`
Remove all `repo_path` parameters from all 5 enhanced tools.
## Phase 3: Update Service Layer
### 3.1 Update Repository Manager Service
**File**: `src/commit_helper_mcp/services/repository_manager.py`
Replace with simplified version:
```python
class RepositoryManager:
"""Simplified repository manager for CWD only."""
def get_repository_path(self) -> str:
"""Always returns current working directory."""
return os.getcwd()
# Remove all path resolution logic
# Remove environment variable handling
```
### 3.2 Update Service Initialization
Update all services to remove path parameters from constructors:
```python
# Before
class CommitzenService:
def __init__(self, repo_path: str):
self.repo_path = repo_path
# After
class CommitzenService:
def __init__(self):
self.repo_path = os.getcwd()
```
## Phase 4: Remove Environment Variable Support
### 4.1 Remove from Settings
**File**: `src/commit_helper_mcp/config/settings.py`
Remove all references to `COMMITIZEN_REPO_PATH` and similar environment variables.
### 4.2 Update Configuration
Remove any configuration related to repository paths.
## Phase 5: Update Tests
### 5.1 Create Security Tests
**File**: `tests/unit/security/test_secure_repository_manager.py`
```python
class TestSecureRepositoryManager:
"""Test security-focused repository manager."""
def test_always_uses_cwd(self):
"""Test manager always returns CWD."""
manager = SecureRepositoryManager()
assert manager.get_repository_path() == os.getcwd()
```
### 5.2 Update Existing Tests
Remove all tests that:
- Pass `repo_path` parameters
- Test environment variable handling
- Test path resolution logic
### 5.3 Add Migration Tests
**File**: `tests/integration/security/test_breaking_changes.py`
```python
def test_repo_path_parameter_removed():
"""Test that repo_path parameter is no longer accepted."""
with pytest.raises(TypeError):
get_git_status(repo_path="/some/path")
```
## Phase 6: Update Documentation
### 6.1 Update README
Add prominent breaking change notice:
```markdown
## ⚠️ BREAKING CHANGE in v2.0.0
For security reasons, all operations now work ONLY on the current working directory:
- Removed all `repo_path` parameters from tools
- Removed `COMMITIZEN_REPO_PATH` environment variable support
- You must `cd` to your repository before using tools
### Migration Guide
```
### 6.2 Update Tool Documentation
Update all tool documentation to remove `repo_path` parameters.
### 6.3 Create Migration Guide
**File**: `MIGRATION_v2.md`
Detailed guide for users migrating from v1.x to v2.0.
### 6.4 Add Dev Dependency Documentation
**File**: `journal/context-provider/13-dev-dependency-approach.md`
Document the recommended approach of installing as a dev dependency for MCP integration.
## Implementation Timeline
### Day 1-2: Core Changes
- [ ] Create secure repository manager
- [ ] Create validation functions
- [ ] Update repository manager service
### Day 3-4: Tool Updates
- [ ] Remove parameters from message tools (4 tools)
- [ ] Remove parameters from git tools (7 tools)
- [ ] Remove parameters from enhanced tools (5 tools)
- [ ] Remove parameters from workflow tools (3 tools)
### Day 5-6: Service Updates
- [ ] Update all service constructors
- [ ] Remove environment variable handling
- [ ] Update configuration system
### Day 7-8: Testing
- [ ] Create security-focused tests
- [ ] Update existing tests
- [ ] Add migration tests
- [ ] Run full test suite
### Day 9-10: Documentation
- [ ] Update README with breaking changes
- [ ] Update all tool documentation
- [ ] Create comprehensive migration guide
- [ ] Update examples
## Migration Guide for Users
### Before (v1.x)
```python
# Using explicit path
result = commit_helper.get_git_status(repo_path="/path/to/repo")
# Using environment variable
export COMMITIZEN_REPO_PATH=/path/to/repo
result = commit_helper.get_git_status()
```
### After (v2.0)
```python
# Must change directory first
os.chdir("/path/to/repo")
result = commit_helper.get_git_status()
# Or in shell
cd /path/to/repo
commit_helper get_git_status
```
### Multi-Repository Scripts
```bash
#!/bin/bash
# Old way
commit_helper get_git_status --repo-path /repo1
commit_helper get_git_status --repo-path /repo2
# New way
cd /repo1 && commit_helper get_git_status
cd /repo2 && commit_helper get_git_status
```
## Risk Assessment
### Breaking Changes
- **Impact**: All existing code using `repo_path` will break
- **Mitigation**: Clear migration guide and error messages
### User Experience
- **Impact**: Less convenient for multi-repository workflows
- **Mitigation**: Document scripting patterns for common use cases
### Security Benefits
- **Gain**: Eliminate path traversal vulnerabilities
- **Gain**: Prevent accidental operations on wrong directories
- **Gain**: Simpler, more secure codebase
## Success Metrics
1. **Security**: Zero path-related vulnerabilities
2. **Simplicity**: 30%+ reduction in codebase size
3. **Performance**: No regression in operation speed
4. **Testing**: 100% coverage of security validations
5. **Documentation**: Clear migration path for all users
## Rollback Plan
If critical issues arise:
1. Tag v2.0.0 as experimental
2. Maintain v1.x branch for security fixes only
3. Document known security risks in v1.x
4. Encourage migration to v2.0
## Conclusion
This implementation plan transforms the Commit Helper MCP into a security-focused tool that eliminates entire categories of vulnerabilities by restricting all operations to the current working directory. While this is a breaking change, the security and simplicity benefits justify the migration effort.
