hg-mcp 0.8.2

MCP server for Mercurial repository interaction

HG MCP Server

A Model Context Protocol (MCP) server for Mercurial repository interaction, written in Python 3.10+ with AsyncIO.

Features

Core Version Control Operations

• Status & Diff: View working directory status and uncommitted changes (equivalent to git status and git diff)
• Commit Management: Add files, commit changes with messages, and remove files from version control
• History Navigation: View commit history with configurable limits, update to any revision (like git checkout/git switch)
• Branch Management: Create, list, and switch between branches; supports both permanent branches and lightweight bookmarks

Advanced Branching with Topics

• Topic Support: Create and manage lightweight branches (topics) using the evolve extension
• Topic Tracking: List all topics and identify the currently active topic
• Bookmark Integration: Seamless bookmark management for Git-like branch workflows

Remote Synchronization

• Push/Pull: Push changes to remote repositories and pull from remote sources
• Remote Configuration: Support for named remotes and direct URLs

History Rewriting (Requires Extensions)

• Rebase: Move or combine changesets onto different revisions (like git rebase)
• Strip: Permanently remove changesets (like git reset --hard)
• Histedit: Interactive history editing (like git rebase -i)
• Transplant: Cherry-pick changesets from other branches (like git cherry-pick)
• Evolve: Track how changesets have been rewritten over time

Merge & Conflict Resolution

• Merge: Combine changes from different branches
• Conflict Management: List and track files with unresolved merge conflicts
• Revert: Discard uncommitted changes and restore files to last committed state

Large File Support

• Largefiles Extension: List and manage large files stored outside normal history with size information

Git Integration (hg-git)

• Git Remote Detection: Automatically detect if repository is Git-backed
• Branch Mapping: View how bookmarks map to Git branches
• Configuration Insights: Display hg-git settings and branch bookmark suffix configuration

Configuration & Diagnostics

• Extension Detection: List all enabled Mercurial extensions
• Repository Validation: Verify Mercurial repository status and configuration
• Built-in Help: Access Mercurial command documentation and concepts

Performance & Reliability

• Async I/O: Asynchronous command execution for responsive operations
• JSON Output Support: Automatic JSON formatting for supported commands (status, log, bookmarks, topics, config, resolve, tags, heads, id, parents, children, outgoing, incoming, paths, annotate, files, verify, identify)
• Optional Performance Boost: Support for uvloop (Unix/macOS) and winloop (Windows) for enhanced performance
• Smart Error Handling: Helpful error messages with hints for missing extensions
• Path Validation: Automatic repository detection even when working in subdirectories
• Comprehensive Testing: Full pytest test suite with isolated repository fixtures (uses tmpfs on Linux for ~10-100x faster I/O)

Installation

# Clone the repository
git clone <repository-url>
cd hg-mcp

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode
pip install -e .

# Optional: Install with performance enhancements
pip install uvloop  # On Unix/macOS
pip install winloop  # On Windows

Usage

# Activate your virtual environment first
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
hg-mcp

This starts the MCP server that can be used with MCP clients like Claude for Desktop, Qwen-Coder, Gemini-CLI, and OpenCode.

Tools

Core Commands

• hg_status: Show working directory status with JSON output (like git status)
• hg_log: Show commit history with JSON output (like git log)
• hg_diff: Show uncommitted changes (like git diff)
• hg_commit: Commit changes with a message; auto-syncs to Git if hg-git enabled
• hg_add: Add files to version control (like git add)
• hg_remove: Remove files (like git rm)
• hg_amend: Amend current commit; auto-syncs to Git if hg-git enabled
• hg_cat: Show file content at specific revision
• hg_rename: Rename/move files (like git mv)

Branch & Navigation

• hg_update: Update to a revision (like git checkout/git switch)
• hg_branch: Show or create branches
• hg_bookmark: Show or create bookmarks; auto-syncs to Git if hg-git enabled
• hg_bookmarks: List bookmarks with JSON output (lightweight branches, like Git branches in hg-git)
• hg_topic: Create a topic (lightweight branch)
• hg_topics: List all topics with JSON output
• hg_topic_current: Show current topic (JSON-parsed)

Remote Sync

• hg_push: Push changes to remote (like git push). Shows available remotes if destination doesn't exist
• hg_pull: Pull changes from remote (like git fetch)
• hg_paths: List configured paths/remotes with JSON output

History Rewriting (Extensions Required)

• hg_rebase: Rebase changesets (like git rebase, requires 'rebase' extension)
• hg_strip: Remove changesets (like git reset --hard, requires 'strip' extension)
• hg_histedit: Interactive history editing (like git rebase -i, requires 'histedit')
• hg_evolve: Show evolution history (requires 'evolve' extension)
• hg_transplant: Cherry-pick changesets (like git cherry-pick, requires 'transplant')

Merge & Conflict Resolution

• hg_merge: Merge branches (like git merge)
• hg_resolve: List merge conflicts with JSON output
• hg_revert: Discard uncommitted changes (like git checkout -- / git restore)

Large Files

• hg_largefiles: List large files (requires 'largefiles' extension)

Configuration & Help

• hg_config: Show Mercurial configuration with JSON output (check for hg-git extension)
• hg_extensions: List enabled extensions
• hg_git: Check hg-git extension status and Git remote configuration
• hg_help: Get help on Mercurial commands and concepts
• hg_paths: List configured paths/remotes with JSON output
• hg_tags: List all tags with JSON output
• hg_tag: Create or remove a tag (like git tag)

Repository Inspection

• hg_annotate: Show changeset info by line for each file (like git blame)
• hg_files: List all tracked files in current revision
• hg_summary: Summarize working directory state (branch, parent, phases)
• hg_verify: Verify repository integrity
• hg_identify: Get changeset ID and branch info for working directory

Patch Management

• hg_export: Export changesets as patch files
• hg_import: Import ordered set of patches

Remote Operations

• hg_heads: List branch heads with JSON output
• hg_incoming: Preview changesets to pull from remote
• hg_outgoing: Preview changesets to push to remote

History Operations

• hg_backout: Reverse effect of earlier changeset (with --no-commit by default)

Integration with AI Assistants

To use this MCP server with your AI coding assistant, you need to configure it in your assistant's MCP settings. The key is pointing to the correct executable path in your virtual environment.

Step 1: Find Your Virtual Environment Path

First, determine where your virtual environment is located:

If using Poetry:

# Get the virtual environment path
poetry env info --path
# Example output: /home/user/.cache/pypoetry/virtualenvs/hg-mcp-xxxxx-py3.10

If using pip/venv:

# The path is typically: /path/to/hg-mcp/.venv
# Or if created elsewhere: echo $VIRTUAL_ENV

Step 2: Configure Your AI Assistant

The executable will be located at:

• Unix/macOS: <venv-path>/bin/hg-mcp
• Windows: <venv-path>\Scripts\hg-mcp.exe

Replace <venv-path> with your actual virtual environment path from Step 1.

---

Qwen-Coder & Gemini-CLI

Both use identical configuration format:

Configuration files:

• Qwen-Coder: ~/.qwen/settings.json
• Gemini-CLI: ~/.gemini/settings.json

{
  "mcpServers": {
    "hg-mcp": {
      "command": "/path/to/your/venv/bin/hg-mcp"
    }
  }
}

---

OpenCode

Configuration file: ~/.config/opencode/opencode.json

{
  "mcp": {
    "hg-mcp": {
      "type": "local",
      "command": ["/path/to/your/venv/bin/hg-mcp"],
      "enabled": true
    }
  }
}

Note: When you use repo_path="." (default), it resolves to OpenCode's current working directory, so the tools will work in whatever project directory you're currently in.

---

Claude Desktop

Configuration file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hg-mcp": {
      "command": "/path/to/your/venv/bin/hg-mcp"
    }
  }
}

---

Other MCP-Compatible Clients

Command: /path/to/your/venv/bin/hg-mcp

Verifying Your Setup

After configuration, restart your AI assistant and verify the MCP server is connected. You can test by asking your assistant to run a Mercurial command like "show the status of this repository" or "list recent commits".

Requirements

• Python 3.10+
• Mercurial installed and available in PATH
• MCP-compatible client

Development

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run specific test file
pytest tests/test_core_tools.py -v

# Run with coverage
pytest --cov=hg_mcp --cov-report=html

Test Fixtures

The test suite provides isolated Mercurial repositories with controlled extension configurations:

• hg_repo: Clean repo with NO extensions enabled
• hg_repo_with_commits: Repo with 5 sample commits
• hg_repo_with_extensions: Repo with configurable extensions (e.g., rebase, evolve)
• hg_repo_with_branches: Multi-branch setup
• hg_repo_with_bookmarks: Repo with bookmarks at different revisions
• hg_repo_with_tags: Repo with tagged revisions
• hg_repo_with_remote: Repo with remote configured

Code Quality

# Run linting
./scripts/lint-check-and-fix.sh

# Run type checking
./scripts/type-check.sh

# Run formatter
./scripts/code-format.sh

Acknowledgments

This project is inspired by mcp-server-mercurial.