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

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

git clone <repository-url>
cd commit-helper-mcp

2. Install dependencies:

uv sync

3. Install the package:

uv pip install -e .

Usage

MCP Inspector (Development & Testing)

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

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:

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

{
  "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:

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:

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:

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:

[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

# 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

# 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

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