# 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "iflow-mcp_commit-helper-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "commit, commitizen, fastmcp, git, mcp",
"author": null,
"author_email": "MCP Connector Team <team@example.com>",
"download_url": "https://files.pythonhosted.org/packages/0a/b4/628063c20eb6d5c3eb00563c12043e25c466da354b60bedb35af4c6869a7/iflow_mcp_commit_helper_mcp-0.6.0.tar.gz",
"platform": null,
"description": "# Commit Helper MCP\n\nA 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.\n\n## Features\n\n### Core Functionality\n- **Generate Commit Messages**: Create conventional commit messages with validation\n- **Validate Messages**: Check existing commit messages against Commitizen rules\n- **Interactive Questions**: Get commit questions for guided message creation\n- **Commit Types**: Access available commit types and their descriptions\n- **Configuration Access**: View current Commitizen configuration and schema\n- **Plugin Support**: Works with any Commitizen plugin (conventional commits, custom plugins)\n- **Health Monitoring**: Built-in health checks and configuration refresh\n\n### \ud83d\ude80 Enhanced Git Integration with GitPython\nCommit Helper MCP now supports GitPython for enhanced git operations:\n\n- **Repository Health Analysis**: Comprehensive repository metrics and scoring\n- **Smart Commit Suggestions**: AI-powered commit message suggestions based on file patterns\n- **Detailed Diff Analysis**: Line-by-line change analysis with statistics\n- **Branch Management**: Comprehensive branch and remote analysis\n- **Performance Improvements**: 2x faster operations, thread-safe execution\n- **Advanced Git Operations**: Enhanced commit previews, repository analytics, and batch operations\n\n### \ud83d\udce6 GitPython Installation\n```bash\n# GitPython is automatically installed\nuv sync\n\n# Or install manually\nuv add \"GitPython>=3.1.40\"\n```\n\n### \ud83d\udd04 Automatic Fallback\nThe system automatically selects the best available implementation:\n- **GitPython** (preferred): Enhanced features and performance\n- **commitizen.git** (fallback): Basic functionality, full compatibility\n\n### \ud83d\udcca Feature Comparison\n| Feature | Basic | Enhanced (GitPython) |\n|---------|-------|---------------------|\n| Repository status | \u2705 | \u2705 Rich metadata |\n| Commit preview | \u2705 | \u2705 Diff analysis |\n| Smart suggestions | \u274c | \u2705 AI-powered |\n| Repository health | \u274c | \u2705 Comprehensive |\n| Performance | Standard | 2x faster |\n\nSee [GitPython Integration Guide](docs/GITPYTHON_INTEGRATION.md) for complete documentation.\n\n## Installation\n\n### Prerequisites\n\n- Python 3.13 or higher\n- [uv](https://docs.astral.sh/uv/) package manager\n- Git repository (for Commitizen configuration detection)\n\n### Install from Source\n\n1. Clone the repository:\n```bash\ngit clone <repository-url>\ncd commit-helper-mcp\n```\n\n2. Install dependencies:\n```bash\nuv sync\n```\n\n3. Install the package:\n```bash\nuv pip install -e .\n```\n\n## Usage\n\n### MCP Inspector (Development & Testing)\n\nUse the MCP Inspector to test and explore the server's capabilities:\n\n```bash\nuv run mcp dev main.py\n```\n\nThis will start an interactive session where you can:\n- Test all available tools\n- Explore resources\n- Debug server functionality\n- View tool schemas and documentation\n\n### Claude Desktop Integration\n\nTo use with Claude Desktop, install the server:\n\n```bash\nuv run mcp install main.py\n```\n\nThis will add the server to your Claude Desktop configuration, making the tools available in your conversations.\n\n### Manual Configuration\n\nAdd to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n \"mcpServers\": {\n \"commit-helper-mcp\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"/path/to/commit-helper-mcp/main.py\"],\n \"cwd\": \"/path/to/commit-helper-mcp\"\n }\n }\n}\n```\n\n## Available Tools\n\n### `generate_commit_message`\nGenerate a commit message with validation using provided parameters.\n\n**Parameters:**\n- `type` (required): Commit type (e.g., 'feat', 'fix', 'docs')\n- `subject` (required): Commit subject/description\n- `body` (optional): Detailed description\n- `scope` (optional): Scope of the change\n- `breaking` (optional): Whether this is a breaking change\n- `footer` (optional): Footer (e.g., issue references)\n\n**Example:**\n```python\ngenerate_commit_message(\n type=\"feat\",\n subject=\"add user authentication\",\n scope=\"auth\",\n body=\"Implement JWT-based authentication system with login and logout functionality\"\n)\n```\n\n### `create_commit_message`\nGenerate a commit message from a complete answers dictionary.\n\n**Parameters:**\n- `answers_dict`: Dictionary containing all answers to commit questions\n\n**Example:**\n```python\ncreate_commit_message({\n \"type\": \"fix\",\n \"subject\": \"resolve memory leak in data processing\",\n \"body\": \"Fixed memory leak caused by unclosed file handles\",\n \"scope\": \"core\"\n})\n```\n\n### `validate_commit_message`\nValidate an existing commit message against current plugin rules.\n\n**Parameters:**\n- `message`: The commit message to validate\n\n**Example:**\n```python\nvalidate_commit_message(\"feat(auth): add user login functionality\")\n```\n\n### `get_commit_types`\nGet list of available commit types from the current plugin.\n\n**Returns:** List of commit types with descriptions\n\n### `get_commit_questions`\nGet interactive questions for commit message generation.\n\n**Returns:** List of questions that can be used to build commit messages\n\n### `health_check`\nCheck the health and status of the Commitizen service.\n\n**Returns:** Service health information and configuration details\n\n### `refresh_configuration`\nRefresh the Commitizen configuration and reinitialize the service.\n\n**Returns:** Status of configuration refresh\n\n## Available Resources\n\n### `commitizen://config`\nCurrent Commitizen configuration including:\n- Active plugin information\n- Configuration settings\n- Available capabilities\n- Message pattern\n\n### `commitizen://schema`\nCommit message schema showing:\n- Required fields\n- Field types and constraints\n- Validation rules\n\n### `commitizen://example`\nExample commit message demonstrating the expected format for the current plugin configuration.\n\n## Configuration\n\nThe server automatically detects and uses your project's Commitizen configuration from:\n- `pyproject.toml` (recommended)\n- `.cz.toml`\n- `.cz.json`\n- `setup.cfg`\n\n### Example Configuration\n\nAdd to your `pyproject.toml`:\n\n```toml\n[tool.commitizen]\nname = \"cz_conventional_commits\"\ntag_format = \"v$version\"\nversion_scheme = \"semver\"\nversion_provider = \"pep621\"\nupdate_changelog_on_bump = true\n```\n\n## Supported Commitizen Plugins\n\nThe server works with any Commitizen plugin, including:\n\n- **cz_conventional_commits** (default): Standard conventional commits\n- **cz_jira**: Jira integration\n- **cz_customize**: Custom commit formats\n- **Third-party plugins**: Any plugin following Commitizen's plugin interface\n\n## Troubleshooting\n\n### Server Won't Start\n\n1. **Check Python version**: Ensure Python 3.13+ is installed\n2. **Verify dependencies**: Run `uv sync` to install dependencies\n3. **Check Commitizen config**: Ensure valid Commitizen configuration exists\n4. **View logs**: Check console output for specific error messages\n\n### Invalid Commit Messages\n\n1. **Check plugin**: Verify correct Commitizen plugin is configured\n2. **Validate config**: Use `health_check` tool to verify configuration\n3. **Refresh config**: Use `refresh_configuration` tool after config changes\n4. **Check pattern**: View `commitizen://config` resource for expected pattern\n\n### MCP Connection Issues\n\n1. **Verify installation**: Ensure server is properly installed\n2. **Check paths**: Verify file paths in Claude Desktop configuration\n3. **Test with inspector**: Use `uv run mcp dev main.py` to test locally\n4. **Restart Claude**: Restart Claude Desktop after configuration changes\n\n### Common Error Messages\n\n- **\"No Commitizen configuration found\"**: Add Commitizen config to your project\n- **\"Plugin not found\"**: Install the specified Commitizen plugin\n- **\"Invalid message format\"**: Check message against plugin's expected pattern\n- **\"Service initialization failed\"**: Check Python environment and dependencies\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=src/commit_helper_mcp\n\n# Run specific test file\nuv run pytest tests/test_integration.py\n```\n\n### Code Formatting\n\n```bash\n# Format code\nuv run black src/ tests/\n\n# Check formatting\nuv run black --check src/ tests/\n\n# Lint code\nuv run ruff check src/ tests/\n```\n\n### Local Development Server\n\n```bash\n# Run server directly\npython main.py\n\n# Run with MCP inspector\nuv run mcp dev main.py\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Support\n\nFor issues and questions:\n1. Check the troubleshooting section above\n2. Search existing issues in the repository\n3. Create a new issue with detailed information about your problem\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and changes.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for Commitizen integration with direct API access",
"version": "0.6.0",
"project_urls": null,
"split_keywords": [
"commit",
" commitizen",
" fastmcp",
" git",
" mcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "530553001709ce8ad3793a7091c015114c0800860295408c331c103a35614fcd",
"md5": "3f323e152a73da1e88baec8f81cbef91",
"sha256": "5c4c03ac71a48d896e222a0b8f1025d26e33b23b8559dc8129d9bef33aeb5825"
},
"downloads": -1,
"filename": "iflow_mcp_commit_helper_mcp-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3f323e152a73da1e88baec8f81cbef91",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 53760,
"upload_time": "2025-10-31T03:28:58",
"upload_time_iso_8601": "2025-10-31T03:28:58.078214Z",
"url": "https://files.pythonhosted.org/packages/53/05/53001709ce8ad3793a7091c015114c0800860295408c331c103a35614fcd/iflow_mcp_commit_helper_mcp-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0ab4628063c20eb6d5c3eb00563c12043e25c466da354b60bedb35af4c6869a7",
"md5": "0a80f04dcc4886c5e789a4d4829e2a96",
"sha256": "f1c849ad47f0d5a3875cb043327bc562785f34529c37bfec5c95e0a1dc5d8a8e"
},
"downloads": -1,
"filename": "iflow_mcp_commit_helper_mcp-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "0a80f04dcc4886c5e789a4d4829e2a96",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 798631,
"upload_time": "2025-10-31T03:29:00",
"upload_time_iso_8601": "2025-10-31T03:29:00.639387Z",
"url": "https://files.pythonhosted.org/packages/0a/b4/628063c20eb6d5c3eb00563c12043e25c466da354b60bedb35af4c6869a7/iflow_mcp_commit_helper_mcp-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-31 03:29:00",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "iflow-mcp_commit-helper-mcp"
}
JSON