# Devin MCP Server

A Python MCP (Model Context Protocol) server that wraps **all three Devin API versions** (v1, v2, v3beta1) with multi-organisation support.

## Features

- **All API versions**: v1 (org-scoped), v2 (enterprise admin), v3beta1 (RBAC/service users)
- **Multi-org**: Route requests to different organisations via the `org` parameter
- **Config-driven**: JSON config file for PAT tokens (excluded from source control)
- **Conditional registration**: Only registers tools for API versions you have tokens for

## Setup

### 1. Install dependencies

```bash
cd devin-mcp
pip install -e .
# or
pip install -r requirements.txt
```

### 2. Create config file

Copy the example and fill in your tokens:

```bash
cp config.example.json config.json
```

Edit `config.json`:

```json
{
  "default_org": "my-org",
  "organizations": {
    "my-org": {
      "description": "Primary organisation",
      "tokens": {
        "v1": "apk_user_YOUR_V1_TOKEN",
        "v2": "apk_user_YOUR_V2_ENTERPRISE_ADMIN_TOKEN",
        "v3": "cog_YOUR_V3_SERVICE_USER_TOKEN"
      }
    },
    "other-org": {
      "description": "Secondary organisation",
      "tokens": {
        "v1": "apk_YOUR_OTHER_ORG_TOKEN"
      }
    }
  }
}
```

> **Note**: `config.json` is in `.gitignore` and will not be committed.

You can also set `DEVIN_MCP_CONFIG=/path/to/config.json` to use a config file from any location.

### 3. Configure your MCP client

#### VS Code / Copilot

Add to your MCP settings (`settings.json` or `.vscode/mcp.json`):

```json
{
  "mcpServers": {
    "devin": {
      "command": "python",
      "args": ["-m", "devin_mcp.server"],
      "cwd": "/path/to/devin-mcp/src"
    }
  }
}
```

#### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "devin": {
      "command": "python",
      "args": ["-m", "devin_mcp.server"],
      "cwd": "/path/to/devin-mcp/src"
    }
  }
}
```

Or using the installed entry point:

```json
{
  "mcpServers": {
    "devin": {
      "command": "devin-mcp"
    }
  }
}
```

## Available Tools

### v1 Tools (Org-Scoped)

| Tool | Description |
|------|-------------|
| `create_session` | Create a new Devin session |
| `get_session` | Get session details by ID |
| `list_sessions` | List sessions |
| `send_session_message` | Send a message to an active session |
| `update_session_tags` | Update session tags |
| `upload_attachment` | Upload a file for use in sessions |
| `list_secrets` | List org secret metadata |
| `create_secret` | Create a secret |
| `delete_secret` | Delete a secret |
| `list_knowledge` | List knowledge items |
| `create_knowledge` | Create a knowledge item |
| `delete_knowledge` | Delete a knowledge item |
| `list_playbooks` | List playbooks |
| `create_playbook` | Create a playbook |
| `delete_playbook` | Delete a playbook |

### v2 Tools (Enterprise Admin)

| Tool | Description |
|------|-------------|
| `enterprise_list_organizations` | List organisations |
| `enterprise_create_organization` | Create an organisation |
| `enterprise_list_members` | List members |
| `enterprise_invite_members` | Invite members |
| `enterprise_session_insights` | Get session insights |
| `enterprise_consumption_cycles` | Get billing cycles |
| `enterprise_audit_logs` | Get audit logs |
| `enterprise_metrics` | Get analytics metrics |
| `enterprise_list_api_keys` | List service API keys |
| `enterprise_list_groups` | List IdP groups |
| `enterprise_list_playbooks` | List enterprise playbooks |
| `enterprise_set_git_permission` | Set git repo permissions |

### v3 Tools (RBAC / Service Users)

| Tool | Description |
|------|-------------|
| `v3_get_self` | Get authenticated service user info |
| `v3_list_organizations` | List organisations |
| `v3_get_organization` | Get organisation details |
| `v3_list_sessions` | List org sessions |
| `v3_get_session` | Get session details |
| `v3_create_session` | Create a session |
| `v3_send_session_message` | Message a session |
| `v3_terminate_session` | Terminate a session |
| `v3_archive_session` | Archive a session |
| `v3_list_enterprise_service_users` | List enterprise service users |
| `v3_create_enterprise_service_user` | Create enterprise service user |
| `v3_list_org_service_users` | List org service users |
| `v3_audit_logs` | Get audit logs |
| `v3_consumption_cycles` | Get billing cycles |
| `v3_consumption_daily` | Get daily consumption |
| `v3_list_enterprise_notes` | List enterprise knowledge |
| `v3_list_org_notes` | List org knowledge |
| `v3_list_enterprise_playbooks` | List enterprise playbooks |
| `v3_list_org_playbooks` | List org playbooks |
| `v3_list_org_secrets` | List org secrets |
| `v3_list_git_connections` | List git connections |
| `v3_list_git_permissions` | List git permissions |
| `v3_list_enterprise_users` | List enterprise users |
| `v3_list_org_users` | List org users |
| `v3_list_enterprise_idp_groups` | List IdP groups |
| `v3_list_roles` | List roles |
| `v3_usage_metrics` | Get usage metrics |
| `v3_queue_status` | Get queue status |
| `v3_list_org_tags` | List org session tags |

## Multi-Organisation Usage

Every tool accepts an optional `org` parameter. When omitted, the `default_org` from config is used.

```
"Create a Devin session in my-org to review PR #42"
→ Uses default org token

"List sessions in other-org"
→ Routes to other-org's token
```

## Token Types

| API Version | Token Prefix | Type |
|-------------|-------------|------|
| v1 | `apk_user_` or `apk_` | Personal or Service API Key |
| v2 | `apk_user_` | Enterprise Admin Personal Key |
| v3 | `cog_` | Service User Credential |