Commit Helper MCP

# Commit Helper MCP Setup Guide This guide shows how to set up Commit Helper MCP with Cline for automated commit message generation and git operations. ## Quick Setup (Recommended) ### Automated Global Setup Run the global configuration script for one-time setup across ALL projects: ```bash cd /Users/jcarroll/Projects/commit-helper-mcp python configure_cline.py ``` This script will: - ✅ Check dependencies (uv, Python 3.8+) - ✅ Test MCP server functionality - ✅ Configure global MCP server in Cline - ✅ Create global Cline rules for commit workflows - ✅ Verify the complete setup **Then restart Cline** (close and reopen the panel or restart VSCode). ### Manual Setup (Alternative) If you prefer manual configuration or the script doesn't work: 1. **Test the Server**: ```bash cd /Users/jcarroll/Projects/commit-helper-mcp uv run python main.py ``` 2. **Configure Cline MCP Server**: - Press `Cmd/Ctrl + Shift + P` → "Cline: Open Settings" - In MCP Servers section, add: ```json { "name": "commit-helper-mcp", "command": "uv", "args": ["run", "python", "main.py"], "cwd": "/Users/jcarroll/Projects/commit-helper-mcp" } ``` 3. **Restart Cline** ## Verify Setup Navigate to any git repository and ask Cline: ``` Use the health_check tool to verify the Commitizen MCP server is working ``` ## What Gets Configured ### Global MCP Server - **Location**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) - **Scope**: Available to ALL projects automatically - **No per-project setup needed** ### Global Cline Rules (Automated Setup Only) - **Location**: `~/Documents/Cline/Rules/commitizen-workflow.md` - **Purpose**: Standardized commit workflow practices across all projects - **Includes**: Safety guidelines, tool usage patterns, best practices ## Available Tools Once configured, these tools are available in ANY git repository: ### Core Workflow Tools - **`get_git_status`** - Check repository status and staged files - **`generate_commit_message`** - Create conventional commit messages - **`preview_git_commit`** - Preview commits safely (dry-run) - **`execute_git_commit`** - Execute commits with force_execute confirmation - **`validate_commit_readiness`** - Comprehensive readiness validation ### Advanced Workflow Tools - **`generate_and_commit`** - Complete workflow in one step - **`stage_files_and_commit`** - Selective file commits - **`commit_workflow_step`** - Multi-step workflow with approval gates ### Validation & Configuration Tools - **`validate_commit_message`** - Check existing messages against project rules - **`get_commit_types`** - See available commit types for current project - **`get_commit_questions`** - Get guided questions for commit creation - **`health_check`** - Verify server status - **`refresh_configuration`** - Reload Commitizen configuration ## Usage Examples ### Basic Commit Workflow ``` 1. Stage your changes: git add . 2. Ask Cline: "Check git status and generate a commit message for the authentication feature I added" 3. Ask Cline: "Preview the commit before executing" 4. Ask Cline: "Execute the commit" ``` ### Complete Workflow ``` Ask Cline: "Check if the repository is ready for commit, generate an appropriate commit message, preview it, and then commit the changes" ``` ### Selective File Commit ``` Ask Cline: "Stage only the authentication files and commit them with a feat message" ``` ## Project Requirements ### Required - Valid git repository - Staged changes for commit operations ### Recommended (Optional) Add Commitizen configuration to `pyproject.toml`: ```toml [tool.commitizen] name = "cz_conventional_commits" tag_format = "v$version" version_scheme = "semver" version_provider = "pep621" update_changelog_on_bump = true ``` Or create `.cz.toml`: ```toml [tool.commitizen] name = "cz_conventional_commits" ``` ## Safety Features The connector includes comprehensive safety mechanisms: - **Preview Mode Default**: All git operations show what will happen first - **Explicit Confirmation**: Actual commits require `force_execute=True` - **Repository Validation**: Prevents operations in invalid git repositories - **Message Validation**: Ensures commit messages follow conventional commit format - **Dry-run Defaults**: Most operations show what would happen without executing ## Troubleshooting ### Server Won't Connect ```bash # Check server starts correctly cd /Users/jcarroll/Projects/commit-helper-mcp uv run python main.py # Re-run configuration (automated setup) python configure_cline.py # Restart Cline ``` ### Tools Not Available in Project 1. Ensure you're in a git repository 2. Check that Cline has been restarted after configuration 3. Verify MCP server is configured in Cline settings ### Commit Operations Fail 1. Ensure you have staged changes: `git add .` 2. Use `validate_commit_readiness` to check repository state 3. Check git repository permissions ### Invalid Commit Messages 1. Use `health_check` to verify configuration 2. Check your project's Commitizen configuration 3. Use `get_commit_types` to see available types ## Advanced Usage ### Multi-step Workflow Use `commit_workflow_step` for complex workflows: 1. **Generate**: Create commit message from parameters 2. **Preview**: Show git preview with staged files 3. **Approve**: Validate readiness and get user approval 4. **Execute**: Perform actual commit ### Custom Global Rules (Automated Setup) Edit the global rules file: ```bash open ~/Documents/Cline/Rules/commitizen-workflow.md ``` ## Benefits ### ✅ **Global Availability** - Works in ANY git repository automatically - No per-project configuration needed (with automated setup) ### ✅ **Safety First** - Preview operations before execution - Explicit confirmation for destructive operations ### ✅ **Consistent Practices** - Same commit workflow across all projects - Standardized conventional commit format ### ✅ **Automatic Detection** - Finds Commitizen configuration automatically - Adapts to project-specific commit rules ## Maintenance ### Re-run Global Setup ```bash cd /Users/jcarroll/Projects/commit-helper-mcp python configure_cline.py ``` ### Health Checks Test the setup regularly: ```bash # Verify setup programmatically python -c "from configure_cline import verify_global_setup; verify_global_setup()" ``` ## Next Steps 1. **Run setup**: Use automated (`python configure_cline.py`) or manual configuration 2. **Restart Cline**: Close and reopen the panel 3. **Test connection**: Use `health_check` tool in any git repository 4. **Start using**: Begin using commit workflow tools in your projects The setup ensures consistent, safe, and conventional commits across all your projects with comprehensive safety mechanisms.