VersionControlHelperMCP

A Model Context Protocol (MCP) server providing version control operations as tools for AI coding agents. Built specifically for integration with LangChain deepagents and other MCP-compatible LLM workflows.

What is This?

This MCP server exposes Git version control operations as structured tools that Large Language Models (LLMs) and AI agents can invoke programmatically. Instead of executing raw git commands, an AI coding agent can call typed, validated tools like commit_all_changes, rollback_to_commit, or compare_commits through the standardized MCP protocol.

Why Use This?

Installation

Prerequisites

• Python 3.11+
• uv package manager
• Git installed on system

Setup

# Clone the repository
git clone https://github.com/your-repo/VersionControlHelperMCP.git
cd VersionControlHelperMCP

# Install dependencies with uv
uv sync

Running the Server

STDIO Mode (Default)

For local usage with LangChain or other MCP clients:

uv run version-control-helper-mcp

With Default Repository Path

Set REPO_PATH to avoid passing repo_path in every tool call:

REPO_PATH=/path/to/your/project uv run version-control-helper-mcp

Development/Debugging

Use the MCP inspector for testing:

uv run mcp dev src/version_control_helper_mcp/server.py

Available Tools

This server provides 10 tools for complete version control workflows.

1. initialize_repo

Purpose: Initialize a new git repository or verify an existing one.

Returns: Status message (e.g., "Initialized repository with initial commit: abc1234")

When to Use:

• Starting a new project from scratch
• Before any other git operations on a fresh directory
• Safe to call on already-initialized repos (will return "Already initialized")

Example:

{
  "tool": "initialize_repo",
  "arguments": {
    "repo_path": "/Users/dev/my-project",
    "initial_commit": true
  }
}

2. get_repo_status

Purpose: Check the current state of the repository.

Returns: JSON object with:

• is_initialized: Whether git is set up
• current_branch: Active branch name
• has_changes: Whether there are uncommitted changes
• staged_files: Files ready to commit
• modified_files: Changed but unstaged files
• untracked_files: New files not yet tracked

When to Use:

• Before committing, to see what will be included
• After making changes, to verify modifications
• To check which branch you're on

3. commit_all_changes

Purpose: Stage ALL changes and create a commit in one action.

Returns: Commit SHA (40-character hash) or "No changes to commit"

Behavior:

• Automatically runs git add -A (stages everything)
• Creates commit with provided message
• Lazy initialization: If repo isn't initialized, initializes it first

When to Use:

• After generating/modifying code, to save a checkpoint
• Before risky operations, to have a rollback point
• At logical milestones during development

Best Practices for Commit Messages:

• Use conventional format: feat:, fix:, docs:, refactor:, test:
• Be descriptive: "feat: add user authentication with JWT tokens"
• Reference the change: "fix: resolve null pointer in login handler"

4. list_commits

Purpose: Retrieve commit history with details.

Returns: JSON with array of commits, each containing:

• sha: Full 40-char commit hash
• short_sha: 7-char abbreviated hash
• message: Commit message
• author: Author name
• author_email: Author email
• timestamp: ISO timestamp

When to Use:

• To find a commit SHA for rollback
• To review what changes were made
• To compare two specific commits

5. rollback_to_commit

Purpose: Reset the repository to a previous commit.

Reset Modes Explained:

Returns: Message with new HEAD SHA

⚠️ WARNING: hard mode permanently deletes uncommitted changes!

When to Use:

• Agent generated bad code → rollback to last good commit
• Want to redo work differently → soft reset
• Experiment failed → hard reset to clean state

6. compare_commits

Purpose: Show detailed diff between any two commits.

Returns: JSON with:

• from_commit, to_commit: The compared SHAs
• files: Array of changed files, each with:
  • filename: Path to file
  • status: added, modified, deleted, or renamed
  • additions: Lines added
  • deletions: Lines removed
  • patch: Unified diff content
• total_additions, total_deletions: Summary counts
• summary: Human-readable summary

When to Use:

• Review what an agent changed in last iteration
• Debug regressions by comparing working vs broken states
• Understand evolution of code over time

7. create_branch

Purpose: Create a new git branch for isolated work.

Returns: Confirmation message with branch name

When to Use:

• Before experimental changes, create a feature branch
• Keep main branch stable while agent experiments
• Work on multiple features in parallel

Naming Conventions:

• feature/add-auth - New functionality
• fix/login-bug - Bug fixes
• experiment/new-algo - Experimental work

8. switch_branch

Purpose: Switch to a different branch.

Returns: Confirmation of current branch after switch

When to Use:

• Switch back to main after completing feature
• Move between different work streams
• Test code on different branches

9. list_branches

Purpose: Show all branches with current branch indicator.

Returns: Formatted list with * marking current branch:

* main (abc1234): Initial commit
  feature/auth (def5678): Add login page

10. generate_commit_message

Purpose: Auto-generate a commit message based on staged changes.

Returns: Suggested commit message with change summary

Styles:

• conventional: Uses prefixes like feat:, fix:, docs:
• simple: Plain descriptive message

Workflow Examples

Basic Agent Workflow

1. initialize_repo(repo_path="/project")     # Set up version control
2. [Agent generates code...]
3. commit_all_changes(message="feat: initial implementation")
4. [Agent makes more changes...]
5. commit_all_changes(message="fix: resolve edge case")
6. [Something breaks...]
7. list_commits(limit=5)                     # Find last good commit
8. rollback_to_commit(sha="abc1234")         # Restore working state

Safe Experimentation

1. create_branch(branch_name="experiment/new-algo")
2. switch_branch(branch_name="experiment/new-algo")
3. [Agent experiments with risky changes...]
4. commit_all_changes(message="experiment: try new approach")
5. [If successful]
   switch_branch(branch_name="main")
   # Merge logic here
6. [If failed]
   switch_branch(branch_name="main")        # Just abandon the branch

Debugging Workflow

1. list_commits(limit=10)                    # See recent history
2. compare_commits(from="abc", to="def")     # What changed?
3. [Identify the breaking commit]
4. rollback_to_commit(sha="abc", mode="soft")  # Go back, keep changes visible

Dependencies

Architecture

VersionControlHelperMCP/
├── pyproject.toml           # UV project configuration
├── src/version_control_helper_mcp/
│   ├── __init__.py
│   ├── server.py            # MCP server entry point
│   ├── tools.py             # Tool implementations
│   ├── git_utils.py         # GitPython wrapper
│   └── models.py            # Pydantic response models
└── README.md

Error Handling

All tools return clear error messages:

License

MIT