Mercurial MCP Server

A Model Context Protocol server for Mercurial repository interaction and automation. This server provides tools to read, search, and manipulate Mercurial repositories via Large Language Models, with a focus on topic-based development workflows.

Features

Core Operations

• hg_status - Shows working directory status
• hg_diff - Shows uncommitted changes
• hg_diff_staged - Shows all uncommitted changes (Mercurial has no staging area)
• hg_diff_rev - Shows changes introduced by a specific changeset
• hg_commit - Records changes to the repository
• hg_add - Adds new files to version control
• hg_remove - Removes files from version control
• hg_move - Moves or renames files
• hg_revert - Reverts uncommitted changes
• hg_log - Shows commit history

Topic-Based Development (Recommended)

• hg_topic - Creates a new topic
• hg_topics - Lists all topics
• hg_topic_current - Shows the current topic
• hg_update - Updates to a different topic, branch, or revision
• hg_stack - Shows the current topic stack

Advanced Operations

• hg_rebase - Rebases changes onto a destination (preferred over merge)
• hg_evolve - Evolves the repository to resolve instabilities

Installation

From source

git clone <repository>
cd mcp-mercurial-server
npm install
npm run build
npm link

Configuration

Claude Desktop

If you installed from source:

{
  "mcpServers": {
    "mercurial": {
      "command": "mcp-server-mercurial"
    }
  }
}

Usage Examples

Basic Workflow

1. Check status: hg_status
2. View changes: hg_diff
3. Add new files: hg_add (files: ["file1.cpp"])
4. Remove files: hg_remove (files: ["file3.cpp"])
5. Move/rename files: hg_move (source: "file2.cpp", destination: "file4.cpp")
6. Commit with detailed message and explicit files:
   hg_commit (
     message: "Your commit message\n\n- Added a #1 file\n- Got rid of a file named 3 because it was useless\n- Fixed naming of file 4",
     files: ["file1.cpp", "file3.cpp", "file4.cpp"]
   )

Checking Current State

# Get the current topic
hg_topic_current

# See the last 5 commits (default)
hg_log

# Get topic name using template
hg_log (max_count: 1, template: "{topic}")

Topic-Based Development

1. Create topic: hg_topic (topic_name: "feature-xyz")
2. Work on changes...
3. Commit to topic: hg_commit (message: "Implement feature XYZ", files: ["feature.cpp"])
4. Rebase topic: hg_rebase (destination: "default")

Requirements

• Node.js 18 or higher
• Mercurial installed and available in PATH
• Mercurial extensions (recommended):
  • topics extension for topic-based workflows
  • evolve extension for history management

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

# Format
npm run format

Debugging

Use the MCP inspector to debug the server:

npx @modelcontextprotocol/inspector npx mcp-server-mercurial

Key Differences from Git

1. No Staging Area: All changes are committed directly
2. Topics: Lightweight branches for feature development
3. Rebase Preferred: Use rebase instead of merge for cleaner history
4. Evolve: Safe history editing with the evolve extension

Best Practices

1. Always list files explicitly in commits - Don't rely on implicit file selection

2. Use multi-line commit messages with bullet points for clarity:

   Main description
   
   - First change detail
   - Second change detail
   - Third change detail
   

3. Prefer topics over branches for feature development

4. Check current topic before starting work: hg_topic_current

5. Review recent commits with hg_log (defaults to last 5)

License

MIT