# Dev Dependency Approach for MCP Integration
## Overview
This document describes the approach of installing commit-helper-mcp as a development dependency in each project, which provides a clean solution for MCP server integration while maintaining the security-focused CWD-only architecture.
## The Challenge
When configuring MCP servers, there are several approaches:
1. **Global Installation**: Install the package globally
2. **Tool Installation**: Use `uv tool install` or `uvx`
3. **Dev Dependency**: Add as a development dependency to each project
The security-focused architecture requires that the MCP server has proper access to the git repository in the current working directory, which makes the dev dependency approach particularly suitable.
## Dev Dependency Solution
### Benefits
1. **Proper Git Access**: When installed as a dev dependency, the package runs in the project context with full access to the git repository
2. **Security Model Preserved**: Maintains the CWD-only restriction for all operations
3. **Project-Specific Configuration**: Each project can have its own version and configuration
4. **No Permission Issues**: Avoids permission problems that might occur with global installations
5. **Version Control**: Dependencies are tracked in the project's version control
### Implementation
#### 1. Add to Project Dependencies
In your project's `pyproject.toml`:
```toml
[project.optional-dependencies]
dev = [
# Other dev dependencies...
"commit-helper-mcp>=0.7.0",
]
```
Or if using a different dependency management system:
```toml
# For Poetry
[tool.poetry.group.dev.dependencies]
commit-helper-mcp = "^0.7.0"
# For Pipenv
[dev-packages]
commit-helper-mcp = ">=0.7.0"
```
#### 2. Install the Dependency
```bash
# Using uv
uv pip install -e ".[dev]"
# Using pip
pip install -e ".[dev]"
# Using Poetry
poetry install --with dev
# Using Pipenv
pipenv install --dev
```
#### 3. Configure MCP Server
In your MCP client configuration (e.g., Claude Desktop or Cline):
```json
{
"mcpServers": {
"commit-helper-mcp": {
"command": "uv",
"args": ["run", "python", "-m", "commit_helper_mcp.main"]
}
}
}
```
Alternative configurations for different tools:
```json
// Using Python directly
{
"command": "python",
"args": ["-m", "commit_helper_mcp.main"]
}
// Using Poetry
{
"command": "poetry",
"args": ["run", "python", "-m", "commit_helper_mcp.main"]
}
// Using Pipenv
{
"command": "pipenv",
"args": ["run", "python", "-m", "commit_helper_mcp.main"]
}
```
## Comparison with Other Approaches
### Global Installation
**Pros:**
- Install once, use everywhere
- No need to add to each project
**Cons:**
- Potential permission issues
- Version conflicts between projects
- May not have proper access to project directory
### Tool Installation (`uvx`)
**Pros:**
- Easy to run without installation
- Isolated environment
**Cons:**
- Isolated from project (no git access)
- Not suitable for tools that need project context
- Temporary environments may cause issues
### Dev Dependency (Recommended)
**Pros:**
- Full access to project and git repository
- Version controlled with project
- Works with security-focused architecture
- Clear dependency relationship
**Cons:**
- Must be added to each project
- Slightly more setup per project
## Integration with Security-Focused Architecture
The dev dependency approach aligns perfectly with the security-focused CWD-only architecture:
1. **CWD Access**: The package runs in the project's environment with natural access to the current working directory
2. **No Path Parameters**: No need for `--directory` flags or path specifications
3. **Git Repository Access**: Full access to `.git` directory and git operations
4. **Security Preserved**: Operations remain restricted to the current working directory
## Best Practices
### 1. Version Pinning
Consider pinning to specific versions for consistency:
```toml
"commit-helper-mcp==0.7.0" # Exact version
"commit-helper-mcp>=0.7.0,<1.0.0" # Compatible version
```
### 2. Documentation
Document the requirement in your project's README:
```markdown
## Development Setup
This project uses commit-helper-mcp for standardized commit messages.
Install development dependencies:
```bash
uv pip install -e ".[dev]"
```
```
### 3. CI/CD Integration
Include in your CI/CD setup:
```yaml
# GitHub Actions example
- name: Install dependencies
run: |
uv pip install -e ".[dev]"
- name: Validate commit message
run: |
uv run python -m commit_helper_mcp validate_commit_message
```
### 4. Team Onboarding
Create a setup script for new team members:
```bash
#!/bin/bash
# setup-dev.sh
echo "Installing development dependencies..."
uv pip install -e ".[dev]"
echo "Configuring MCP server..."
# Add any additional setup steps
echo "Development environment ready!"
```
## Migration from Other Approaches
### From Global Installation
1. Uninstall global package: `uv tool uninstall commit-helper-mcp`
2. Add to project dependencies
3. Update MCP configuration to use `uv run`
### From Tool Installation
1. Remove from tool installations
2. Add to project dependencies
3. Update MCP configuration to remove isolation flags
## Troubleshooting
### Common Issues
1. **Module not found**: Ensure you've installed dev dependencies
2. **Permission denied**: Check that you're using the project's Python environment
3. **Git access issues**: Verify you're not using `--no-project` or isolation flags
### Verification Steps
```bash
# Verify installation
uv run python -c "import commit_helper_mcp; print('✓ Installed')"
# Test MCP server
uv run python -m commit_helper_mcp.main
# Check git access
uv run python -m commit_helper_mcp get_git_status
```
## Conclusion
The dev dependency approach provides the best balance of:
- Security (CWD-only operations)
- Functionality (full git access)
- Maintainability (version controlled)
- Compatibility (works with existing architecture)
While it requires adding the dependency to each project, this explicit approach ensures proper integration with the security-focused architecture and provides clear dependency management.