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

🔄 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

See GitPython Integration Guide for complete documentation.

Installation

Prerequisites

• Python 3.13 or higher

• uv package manager

• Git repository (for Commitizen configuration detection)

Install from Source

1. Clone the repository:

2. Install dependencies:

3. Install the package:

Usage

MCP Inspector (Development & Testing)

Use the MCP Inspector to test and explore the server's capabilities:

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:

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):

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:

create_commit_message

Generate a commit message from a complete answers dictionary.

Parameters:

• answers_dict: Dictionary containing all answers to commit questions

Example:

validate_commit_message

Validate an existing commit message against current plugin rules.

Parameters:

• message: The commit message to validate

Example:

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:

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

Code Formatting

Local Development Server

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 for version history and changes.