npm package: @olupdev/jujutsu-mcp-server
Description: A Model Context Protocol server
Latest version: 0.1.0

# Jujutsu MCP Server

A comprehensive Model Context Protocol (MCP) server that provides access to Jujutsu VCS operations. This server enables AI assistants to interact with Jujutsu repositories through a standardized interface.

## Installation

### Prerequisites

- [Jujutsu VCS](https://github.com/jj-vcs/jj) must be installed and available in your PATH
- Node.js 18+ 

### Installation for Popular MCP Clients

#### Claude Desktop

1. Install the server globally:
   ```bash
   npm install -g jujutsu-mcp-server
   ```

2. Add this to your Claude Desktop configuration:

   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

   ```json
   {
     "mcpServers": {
       "jujutsu": {
         "command": "jujutsu-mcp-server"
       }
     }
   }
   ```

#### Cursor

1. Install the server using npx (no global installation needed):
   ```bash
   npx jujutsu-mcp-server --version
   ```

2. In Cursor, go to **Settings** → **Features** → **Model Context Protocol**

3. Add the server configuration:
   ```json
   {
     "jujutsu": {
       "command": "npx",
       "args": ["jujutsu-mcp-server"]
     }
   }
   ```

#### Cline (VS Code Extension)

1. Install the server using npx (no global installation needed):
   ```bash
   npx jujutsu-mcp-server --version
   ```

2. In VS Code, open Cline settings (Cmd/Ctrl + Shift + P → "Cline: Open Settings")

3. Add to the MCP servers configuration:
   ```json
   {
     "mcpServers": {
       "jujutsu": {
         "command": "npx",
         "args": ["jujutsu-mcp-server"]
       }
     }
   }
   ```

#### Continue (VS Code Extension)

1. Install globally or use npx:
   ```bash
   npm install -g jujutsu-mcp-server
   # OR use npx (no installation needed)
   npx jujutsu-mcp-server --version
   ```

2. Add to your `~/.continue/config.json`:
   ```json
   {
     "mcpServers": {
       "jujutsu": {
         "command": "jujutsu-mcp-server"
       }
     }
   }
   ```
   
   Or if using npx:
   ```json
   {
     "mcpServers": {
       "jujutsu": {
         "command": "npx",
         "args": ["jujutsu-mcp-server"]
       }
     }
   }
   ```

#### Other MCP Clients

This server follows the standard MCP protocol and should work with any compatible client. You can use either:
- Global installation: `npm install -g jujutsu-mcp-server` then use `jujutsu-mcp-server` as command
- Via npx: Use `npx` as command with `["jujutsu-mcp-server"]` as args

## Features

- **Complete Jujutsu Command Coverage**: Access to all major jj commands including bookmarks, commits, rebasing, and more
- **Repository Information as Resources**: Get real-time repository status, configuration, and history
- **Safe Command Execution**: Proper error handling and command validation
- **Automatic Repository Detection**: Finds Jujutsu repositories by looking for `.jj` directories
- **Modern MCP Implementation**: Built with the latest MCP SDK patterns and best practices

## Available Tools

The server provides comprehensive access to Jujutsu commands through MCP tools:

### Repository Information
- `jj_status` - Show repository status including working copy changes and conflicts
- `jj_log` - Show revision history with optional filtering and formatting
- `jj_show` - Show commit description and changes in a specific revision
- `jj_diff` - Compare file contents between revisions
- `jj_root` - Show workspace root directory
- `jj_version` - Display Jujutsu version information

### Bookmark Operations
- `jj_bookmark_list` - List bookmarks and their targets
- `jj_bookmark_create` - Create new bookmarks
- `jj_bookmark_set` - Update existing bookmarks
- `jj_bookmark_delete` - Delete bookmarks (marked as dangerous)
- `jj_bookmark_move` - Move bookmarks between revisions

### Working Copy Operations
- `jj_new` - Create new, empty changes
- `jj_edit` - Set working-copy revision
- `jj_describe` - Update change descriptions and metadata
- `jj_commit` - Update description and create new change on top

### Change Operations
- `jj_squash` - Move changes from one revision to another
- `jj_split` - Split a revision into two
- `jj_duplicate` - Create copies of existing changes

### Rebase Operations
- `jj_rebase` - Move revisions to different parents
- `jj_abandon` - Abandon revisions (marked as dangerous)

### Git Integration
- `jj_git_fetch` - Fetch from Git remotes
- `jj_git_push` - Push to Git remotes
- `jj_git_clone` - Clone Git repositories

### File Operations
- `jj_file_list` - List files in revisions
- `jj_file_show` - Show file contents

### Conflict Resolution
- `jj_resolve` - Resolve conflicts with merge tools

### Operation Log
- `jj_operation_log` - Show operation history
- `jj_operation_undo` - Undo operations (marked as dangerous)

### Workspace Management
- `jj_workspace_list` - List workspaces
- `jj_workspace_add` - Add new workspaces

### Configuration
- `jj_config_list` - List configuration variables
- `jj_config_get` - Get configuration values
- `jj_config_set` - Set configuration values

## Available Resources

The server exposes repository information as MCP resources accessible via `jj://` URIs:

- `jj://repository/status` - Current repository status
- `jj://repository/config` - Repository configuration
- `jj://repository/log` - Recent commit history
- `jj://repository/bookmarks` - List of bookmarks
- `jj://repository/remotes` - Git remotes
- `jj://repository/operation-log` - Recent operations
- `jj://repository/workspaces` - Available workspaces

## Usage Examples

### Basic Repository Operations

Ask your AI assistant to:
- "Show me the current status of the repository"
- "Display the recent commit history"
- "List all bookmarks in the repository"

### Working with Changes

- "Create a new change with message 'Fix bug in parser'"
- "Show the diff between the current change and its parent"
- "Squash the current change into its parent"

### Bookmark Management

- "Create a bookmark called 'feature-branch' on the current change"
- "List all remote bookmarks"
- "Move the 'main' bookmark to revision abc123"

### Git Integration

- "Fetch changes from the origin remote"
- "Push the current bookmark to origin"
- "Clone the repository from https://github.com/example/repo.git"

## Safety Features

Commands marked as "dangerous" in the tool definitions (like `jj_abandon`, `jj_bookmark_delete`, `jj_operation_undo`) will be clearly identified. The AI assistant should warn users before executing these operations.

## Error Handling

The server includes comprehensive error handling:
- Validates that Jujutsu is installed before starting
- Automatically detects Jujutsu repository roots
- Provides clear error messages for failed operations
- Handles command timeouts (60 seconds default)

## Development

If you want to contribute or modify the server:

1. Clone the repository
2. Install dependencies:
   ```bash
   pnpm install
   ```
3. Build the server:
   ```bash
   pnpm run build
   ```
4. Test locally:
   ```bash
   pnpm test
   ```

For development with auto-rebuild:
```bash
pnpm run watch
```

### Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
pnpm run inspector
```

The Inspector will provide a URL to access debugging tools in your browser.

### Adding New Commands

To add support for additional Jujutsu commands:

1. Add the command definition to the `getJJCommands()` method
2. Add argument parsing logic in `buildCommandArgs()`
3. Test the command with the MCP Inspector
4. Update this README with the new functionality

## Troubleshooting

### "jj is not installed or not in PATH"

Make sure Jujutsu VCS is installed and available in your system PATH. You can test this by running `jj --version` in your terminal.

### "Not in a Jujutsu repository"

The server automatically detects Jujutsu repositories by looking for `.jj` directories. Make sure you're working within a Jujutsu repository or create one with `jj git clone` or `jj init`.

### Server not responding

Check that the server configuration in your MCP client points to the correct command (`jujutsu-mcp-server` for global install or `npx` with `["jujutsu-mcp-server"]` args).

## Contributing

Contributions are welcome! Please ensure:
- New commands include proper input validation
- Error handling follows existing patterns
- Documentation is updated for new features
- Commands that can modify repository state are clearly marked

## License

This project is open source under the MIT License. See the LICENSE file for details.