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?

Problem	Solution
AI agents generate code without version history	Every code change can be committed automatically
Bad AI-generated code breaks the project	Rollback to any previous commit instantly
No visibility into what the agent changed	Compare any two commits to see exact diffs
Risk of losing work during agent iterations	Branching allows safe experimentation

---

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.

Parameter	Type	Required	Default	Description
repo_path	string	✅	-	Absolute path to repository directory
initial_commit	boolean	❌	true	Create initial commit with README

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.

Parameter	Type	Required	Description
repo_path	string	✅	Absolute path to 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.

Parameter	Type	Required	Description
repo_path	string	✅	Absolute path to repository
message	string	✅	Commit message describing changes

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.

Parameter	Type	Required	Default	Description
repo_path	string	✅	-	Absolute path to repository
branch	string	❌	"HEAD"	Branch name or "HEAD" for current
limit	integer	❌	50	Maximum commits to return

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.

Parameter	Type	Required	Default	Description
repo_path	string	✅	-	Absolute path to repository
commit_sha	string	✅	-	SHA of target commit (full or short)
mode	string	❌	"soft"	Reset mode: soft, mixed, or hard

Reset Modes Explained:

Mode	Staged Changes	Working Directory	Use Case
soft	✅ Preserved	✅ Preserved	Undo last commit, keep changes staged
mixed	❌ Unstaged	✅ Preserved	Undo commit, keep files but unstage
hard	❌ Deleted	❌ Deleted	DANGEROUS: Completely discard all changes

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.

Parameter	Type	Required	Description
repo_path	string	✅	Absolute path to repository
from_commit	string	✅	Source commit SHA (older)
to_commit	string	✅	Target commit SHA (newer)

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.

Parameter	Type	Required	Default	Description
repo_path	string	✅	-	Absolute path to repository
branch_name	string	✅	-	Name for new branch
from_ref	string	❌	Current HEAD	Commit/branch to branch from

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.

Parameter	Type	Required	Description
repo_path	string	✅	Absolute path to repository
branch_name	string	✅	Branch to switch to

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.

Parameter	Type	Required	Description
repo_path	string	✅	Absolute path to repository

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.

Parameter	Type	Required	Default	Description
repo_path	string	✅	-	Absolute path to repository
style	string	❌	"conventional"	conventional or simple

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

Package	Version	Purpose
mcp	≥1.26.0	MCP Python SDK for server/tools
gitpython	≥3.1.46	Git repository operations
pygithub	≥2.8.1	GitHub API (future remote ops)
pydantic	≥2.0.0	Structured data models

---

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:

Scenario	Error Message
Git not initialized	"Git repository not initialized. Call initialize_repo first."
Invalid commit SHA	"Invalid commit SHA: [sha]"
Branch not found	"Branch '[name]' not found"
No changes to commit	"No changes to commit"

---

License

MIT