# hop-mcp

An MCP server for managing parallel Git worktrees. Work on multiple tickets simultaneously without stashing, switching branches, or losing context.

## The Problem

You're deep in JIRA-456 when a critical bug comes in. Traditional workflow:

```
git stash
git checkout main
git checkout -b hotfix-789
# fix the bug
git checkout feature/JIRA-456
git stash pop   # hope nothing conflicts
```

With hop:

```
hop start HOTFIX-789
# fix the bug in isolated directory
hop to JIRA-456
# back to your original work, exactly as you left it
```

Each ticket gets its own directory. No stashing. No branch switching. No context loss.

## Tools

| Tool | Description |
|------|-------------|
| `hop_list` | List all worktrees with path, branch, commit, and dirty status |
| `hop_start` | Create a new worktree for a ticket (supports `dryRun` to preview) |
| `hop_to` | Switch to an existing worktree |
| `hop_current` | Get current worktree context (branch, ticket, dirty status) |
| `hop_open` | Open a worktree in Cursor IDE |
| `hop_end` | Remove a worktree (checks for uncommitted changes, supports `dryRun`) |
| `hop_clean` | Delete scratch files in a worktree |

All tools also available as `git_worktree_*` aliases.

## How It Works

Git worktrees create separate working directories that share the same `.git` object store:

```
my-project/                    # main worktree (your original clone)
my-project/.worktrees/
├── JIRA-123/                  # worktree for ticket JIRA-123
├── JIRA-456/                  # worktree for ticket JIRA-456
└── HOTFIX-789/                # worktree for hotfix
```

Benefits:
- **Low disk usage** — only working files are duplicated, git objects are shared
- **Instant switching** — just `cd` to another directory
- **Full isolation** — each worktree has its own node_modules, build cache, etc.
- **No conflicts** — uncommitted changes stay exactly where they are

## Requirements

- Git 2.5+ (for worktree support)
- Node.js 20+

## Install

```bash
npm install
npm run build
```

## Setup

### Claude Code

Add to `~/.claude.json` under `projects.<your-project>.mcpServers`:

```json
{
  "hop": {
    "type": "stdio",
    "command": "node",
    "args": ["/path/to/hop-mcp/dist/index.js"]
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "hop": {
      "command": "node",
      "args": ["/path/to/hop-mcp/dist/index.js"]
    }
  }
}
```

## Configuration

Config is merged from (highest precedence first):

1. Per-repo: `.hop-mcp.json` at repository root
2. Global: `~/.config/hop-mcp/config.json` (macOS/Linux) or `%APPDATA%\hop-mcp\config.json` (Windows)
3. Built-in defaults

Example `.hop-mcp.json`:

```json
{
  "worktreesDir": ".worktrees",
  "defaultBaseBranch": "develop",
  "defaultBranchTemplate": "feature/<ticket>-<slug>",
  "defaultBranchTemplateNoSlug": "feature/<ticket>",
  "scratchGlobs": [".cursor/plans/**", "**/*.plan.md"]
}
```

## Usage Examples

```bash
# See all active worktrees
hop list

# Start work on a new ticket
hop start JIRA-123

# Start with a descriptive slug
hop start JIRA-123 --slug fix-auth-timeout

# Preview what would be created (dry run)
hop start JIRA-123 --dry-run

# Switch to an existing ticket
hop to JIRA-123

# Check where you are
hop current

# Open ticket in Cursor
hop open JIRA-123

# Preview removal (shows dirty status)
hop end JIRA-123 --dry-run

# Remove when done (fails if uncommitted changes)
hop end JIRA-123

# Force remove with uncommitted changes
hop end JIRA-123 --force
```

## License

MIT