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

Clone the repository:

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

Install dependencies:

uv sync

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

Check Python version: Ensure Python 3.13+ is installed
Verify dependencies: Run uv sync to install dependencies
Check Commitizen config: Ensure valid Commitizen configuration exists
View logs: Check console output for specific error messages

Invalid Commit Messages

Check plugin: Verify correct Commitizen plugin is configured
Validate config: Use health_check tool to verify configuration
Refresh config: Use refresh_configuration tool after config changes
Check pattern: View commitizen://config resource for expected pattern

MCP Connection Issues

Verify installation: Ensure server is properly installed
Check paths: Verify file paths in Claude Desktop configuration
Test with inspector: Use uv run mcp dev main.py to test locally
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

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

Check the troubleshooting section above
Search existing issues in the repository
Create a new issue with detailed information about your problem

Changelog

See CHANGELOG.md for version history and changes.

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - not found

quality - confirmed to work

How are these scores calculated?

Tools

View all tools

A Model Context Protocol server that provides Commitizen functionality, enabling AI assistants to generate, validate, and work with conventional commit messages.

Related MCP Servers

aira-mcp-server
Sunwood-ai-labs
A
security
A
license
A
quality
A Model Context Protocol server for creating commit messages from git staged files.
Last updated -
2
1
MIT License
MCP Toolkit
zxfgds
-
security
F
license
-
quality
A comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.
Last updated -
7
1
Meeting BaaS MCP Server
Meeting-BaaS
-
security
A
license
-
quality
A Model Context Protocol server that enables AI assistants to manage meeting data, including creating meeting bots, searching transcripts, and organizing calendar events.
Last updated -
19
MIT License
Docs MCP Server
probelabs
A
security
A
license
A
quality
A flexible Model Context Protocol server that makes documentation or codebases searchable by AI assistants, allowing users to chat with code or docs by simply pointing to a git repository or folder.
Last updated -
1
23
54
MIT License

View all related MCP servers