Commit Helper MCP

# Commit Helper MCP A Model Context Protocol (MCP) server that provides Commitizen functionality through MCP tools and resources, enabling AI assistants to generate, validate, and work with conventional commit messages. ## Features ### Core Functionality - **Generate Commit Messages**: Create conventional commit messages with validation - **Validate Messages**: Check existing commit messages against Commitizen rules - **Interactive Questions**: Get commit questions for guided message creation - **Commit Types**: Access available commit types and their descriptions - **Configuration Access**: View current Commitizen configuration and schema - **Plugin Support**: Works with any Commitizen plugin (conventional commits, custom plugins) - **Health Monitoring**: Built-in health checks and configuration refresh ### 🚀 Enhanced Git Integration with GitPython Commit Helper MCP now supports GitPython for enhanced git operations: - **Repository Health Analysis**: Comprehensive repository metrics and scoring - **Smart Commit Suggestions**: AI-powered commit message suggestions based on file patterns - **Detailed Diff Analysis**: Line-by-line change analysis with statistics - **Branch Management**: Comprehensive branch and remote analysis - **Performance Improvements**: 2x faster operations, thread-safe execution - **Advanced Git Operations**: Enhanced commit previews, repository analytics, and batch operations ### 📦 GitPython Installation ```bash # GitPython is automatically installed uv sync # Or install manually uv add "GitPython>=3.1.40" ``` ### 🔄 Automatic Fallback The system automatically selects the best available implementation: - **GitPython** (preferred): Enhanced features and performance - **commitizen.git** (fallback): Basic functionality, full compatibility ### 📊 Feature Comparison | Feature | Basic | Enhanced (GitPython) | |---------|-------|---------------------| | Repository status | ✅ | ✅ Rich metadata | | Commit preview | ✅ | ✅ Diff analysis | | Smart suggestions | ❌ | ✅ AI-powered | | Repository health | ❌ | ✅ Comprehensive | | Performance | Standard | 2x faster | See [GitPython Integration Guide](docs/GITPYTHON_INTEGRATION.md) for complete documentation. ## Installation ### Prerequisites - Python 3.13 or higher - [uv](https://docs.astral.sh/uv/) package manager - Git repository (for Commitizen configuration detection) ### Install from Source 1. Clone the repository: ```bash git clone <repository-url> cd commit-helper-mcp ``` 2. Install dependencies: ```bash uv sync ``` 3. Install the package: ```bash uv pip install -e . ``` ## Usage ### MCP Inspector (Development & Testing) Use the MCP Inspector to test and explore the server's capabilities: ```bash uv run mcp dev main.py ``` This will start an interactive session where you can: - Test all available tools - Explore resources - Debug server functionality - View tool schemas and documentation ### Claude Desktop Integration To use with Claude Desktop, install the server: ```bash uv run mcp install main.py ``` This will add the server to your Claude Desktop configuration, making the tools available in your conversations. ### Manual Configuration Add to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "mcpServers": { "commit-helper-mcp": { "command": "uv", "args": ["run", "python", "/path/to/commit-helper-mcp/main.py"], "cwd": "/path/to/commit-helper-mcp" } } } ``` ## Available Tools ### `generate_commit_message` Generate a commit message with validation using provided parameters. **Parameters:** - `type` (required): Commit type (e.g., 'feat', 'fix', 'docs') - `subject` (required): Commit subject/description - `body` (optional): Detailed description - `scope` (optional): Scope of the change - `breaking` (optional): Whether this is a breaking change - `footer` (optional): Footer (e.g., issue references) **Example:** ```python generate_commit_message( type="feat", subject="add user authentication", scope="auth", body="Implement JWT-based authentication system with login and logout functionality" ) ``` ### `create_commit_message` Generate a commit message from a complete answers dictionary. **Parameters:** - `answers_dict`: Dictionary containing all answers to commit questions **Example:** ```python create_commit_message({ "type": "fix", "subject": "resolve memory leak in data processing", "body": "Fixed memory leak caused by unclosed file handles", "scope": "core" }) ``` ### `validate_commit_message` Validate an existing commit message against current plugin rules. **Parameters:** - `message`: The commit message to validate **Example:** ```python validate_commit_message("feat(auth): add user login functionality") ``` ### `get_commit_types` Get list of available commit types from the current plugin. **Returns:** List of commit types with descriptions ### `get_commit_questions` Get interactive questions for commit message generation. **Returns:** List of questions that can be used to build commit messages ### `health_check` Check the health and status of the Commitizen service. **Returns:** Service health information and configuration details ### `refresh_configuration` Refresh the Commitizen configuration and reinitialize the service. **Returns:** Status of configuration refresh ## Available Resources ### `commitizen://config` Current Commitizen configuration including: - Active plugin information - Configuration settings - Available capabilities - Message pattern ### `commitizen://schema` Commit message schema showing: - Required fields - Field types and constraints - Validation rules ### `commitizen://example` Example commit message demonstrating the expected format for the current plugin configuration. ## Configuration The server automatically detects and uses your project's Commitizen configuration from: - `pyproject.toml` (recommended) - `.cz.toml` - `.cz.json` - `setup.cfg` ### Example Configuration Add to your `pyproject.toml`: ```toml [tool.commitizen] name = "cz_conventional_commits" tag_format = "v$version" version_scheme = "semver" version_provider = "pep621" update_changelog_on_bump = true ``` ## Supported Commitizen Plugins The server works with any Commitizen plugin, including: - **cz_conventional_commits** (default): Standard conventional commits - **cz_jira**: Jira integration - **cz_customize**: Custom commit formats - **Third-party plugins**: Any plugin following Commitizen's plugin interface ## Troubleshooting ### Server Won't Start 1. **Check Python version**: Ensure Python 3.13+ is installed 2. **Verify dependencies**: Run `uv sync` to install dependencies 3. **Check Commitizen config**: Ensure valid Commitizen configuration exists 4. **View logs**: Check console output for specific error messages ### Invalid Commit Messages 1. **Check plugin**: Verify correct Commitizen plugin is configured 2. **Validate config**: Use `health_check` tool to verify configuration 3. **Refresh config**: Use `refresh_configuration` tool after config changes 4. **Check pattern**: View `commitizen://config` resource for expected pattern ### MCP Connection Issues 1. **Verify installation**: Ensure server is properly installed 2. **Check paths**: Verify file paths in Claude Desktop configuration 3. **Test with inspector**: Use `uv run mcp dev main.py` to test locally 4. **Restart Claude**: Restart Claude Desktop after configuration changes ### Common Error Messages - **"No Commitizen configuration found"**: Add Commitizen config to your project - **"Plugin not found"**: Install the specified Commitizen plugin - **"Invalid message format"**: Check message against plugin's expected pattern - **"Service initialization failed"**: Check Python environment and dependencies ## Development ### Running Tests ```bash # Run all tests uv run pytest # Run with coverage uv run pytest --cov=src/commit_helper_mcp # Run specific test file uv run pytest tests/test_integration.py ``` ### Code Formatting ```bash # Format code uv run black src/ tests/ # Check formatting uv run black --check src/ tests/ # Lint code uv run ruff check src/ tests/ ``` ### Local Development Server ```bash # Run server directly python main.py # Run with MCP inspector uv run mcp dev main.py ``` ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests for new functionality 5. Ensure all tests pass 6. Submit a pull request ## License MIT License - see LICENSE file for details. ## Support For issues and questions: 1. Check the troubleshooting section above 2. Search existing issues in the repository 3. Create a new issue with detailed information about your problem ## Changelog See [CHANGELOG.md](CHANGELOG.md) for version history and changes.