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