# Devin MCP Server

An MCP server that enables Claude Code to delegate implementation tasks to Devin.

## Installation

### Option 1: Install from Local Path (Development)

If you have the `devin-mcp` repository cloned locally:

```bash
# Navigate to the devin-mcp directory
cd /path/to/devin-mcp

# Install with uv (creates venv automatically)
uv pip install -e .
```

### Option 2: Install from Git Repository

```bash
# Install directly from git (if repository is public)
uv pip install git+https://github.com/iainmck29/devin-mcp.git

# Or from a specific branch/tag
uv pip install git+https://github.com/iainmck29/devin-mcp.git@main
```

### Option 3: Install as a Published Package

```bash
# If published to PyPI (future)
uv pip install devin-mcp
```

**Note:** The MCP server needs to be installed in a location where `uv` can find it. If installing from a local path, use an absolute path or ensure the path is accessible.

## Configuration

Set your Devin API key and playbook ID as environment variables:

```bash
export DEVIN_API_KEY="your-api-key-here"
export DEVIN_PLAYBOOK_ID="your-playbook-id-here"
```

## Usage

### Running the Server

```bash
# Via module (using uv run to automatically use project venv)
uv run python -m devin_mcp.server

# Or via CLI entry point
uv run devin-mcp
```

### Claude Code Configuration

#### Step 1: Get Your Devin API Key

1. Sign in to [Devin](https://app.devin.ai)
2. Navigate to your account settings or API section
3. Generate or copy your API key

#### Step 2: Locate Claude Code Settings File

The MCP settings file location depends on your OS:

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

#### Step 3: Configure the MCP Server

Open the settings file and add the `devin` server configuration. If the file doesn't exist or is empty, create it with this structure:

```json
{
  "mcpServers": {
    "devin": {
      "command": "uv",
      "args": ["run", "python", "-m", "devin_mcp.server"],
      "env": {
        "DEVIN_API_KEY": "your-api-key-here",
        "DEVIN_PLAYBOOK_ID": "your-playbook-id-here"
      }
    }
  }
}
```

**Important Notes:**

- Replace `"your-api-key-here"` with your actual Devin API key
- Replace `"your-playbook-id-here"` with your Devin playbook ID
- If you installed from a local path, ensure `uv` is in your PATH
- The `uv` command must be able to find the installed `devin_mcp` package
- If you installed in a specific virtual environment, you may need to use the full path to `uv` or activate that environment

#### Step 4: Restart Claude Code

After saving the configuration file:

1. Completely quit Claude Code (not just close the window)
2. Reopen Claude Code
3. The MCP server should automatically start and connect

#### Step 5: Verify It's Working

1. Open Claude Code in any project
2. Check the MCP status indicator (usually in the bottom status bar)
3. Try asking Claude: "What MCP tools are available?" or "List the devin tools"
4. You should see the four Devin tools: `devin_run_phase`, `devin_await_completion`, `devin_get_status`, `devin_send_message`

#### Troubleshooting

**Server won't start:**

- Verify `uv` is installed: `which uv` or `uv --version`
- Check that `devin_mcp` is installed: `uv run python -c "import devin_mcp; print('OK')"`
- Check Claude Code logs for error messages

**API key errors:**

- Verify the API key is correct in the config file
- Ensure there are no extra quotes or whitespace around the key
- Test the API key manually: `export DEVIN_API_KEY="your-key" && uv run python -c "from devin_mcp.client import DevinClient; print('OK')"`

**Tools not appearing:**

- Restart Claude Code completely
- Check the MCP connection status in Claude Code
- Verify the config JSON is valid (no trailing commas, proper quotes)

## Available Tools

### `devin_run_phase`

Create a new Devin session with a playbook and prompt.

**Parameters:**

- `prompt` (string, required): The task prompt
- `playbook_id` (string, optional): The Devin playbook ID. Uses `DEVIN_PLAYBOOK_ID` env var if not provided.

**Returns:** `{ success, session_id, url }` or `{ success: false, error }`

### `devin_await_completion`

Poll a session until it reaches a terminal state.

**Parameters:**

- `session_id` (string, required): The session to monitor
- `timeout` (integer, optional): Max wait in seconds (default: 600)

**Returns:** Full session details or raises `DevinTimeoutError`

### `devin_get_status`

Quick, non-blocking status check.

**Parameters:**

- `session_id` (string, required): The session to check

**Returns:** `{ success, session_id, url, status_enum }` or `{ success: false, error }`

### `devin_send_message`

Send a follow-up message to a session.

**Parameters:**

- `session_id` (string, required): The session to message
- `message` (string, required): The message content

**Returns:** `{ success, detail }` or `{ success: false, error }`

## Example Workflow

```python
# 1. Start a phase (uses DEVIN_PLAYBOOK_ID from environment)
result = devin_run_phase(
    prompt="thoughts/shared/plans/2024-01-15-auth.md, phase 1, branch feature/auth"
)
# Or override with a specific playbook:
# result = devin_run_phase(prompt="...", playbook_id="pb_abc123")
session_id = result["session_id"]

# 2. Wait for completion
session = devin_await_completion(session_id, timeout=600)

# 3. Check result
if session["status_enum"] == "finished":
    print("Phase completed successfully!")
elif session["status_enum"] == "blocked":
    # Send clarification if needed
    devin_send_message(session_id, "Use the existing User model from src/models/user.py")
```

## Development

```bash
# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests (using uv run to ensure correct environment)
uv run pytest

# Type check
uv run mypy src/
```