# Mercurial MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/mcp-server-mercurial.svg)](https://badge.fury.io/js/mcp-server-mercurial)

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

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

## Configuration

### Claude Desktop

If you installed from source:

```json
{
  "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

```bash
# 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:

```bash
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