# ActiveCollab MCP Server

Local MCP (Model Context Protocol) server for ActiveCollab API integration. Allows Claude Code to access ActiveCollab data without exposing API tokens to external services.

## Architecture

```
Claude Code (CLI)
       │
       ▼
┌──────────────────┐
│   MCP Server     │  ← Python, runs locally
│   (stdio)        │
└──────────────────┘
       │
       ▼
┌──────────────────┐
│ ActiveCollab API │  ← HTTPS
└──────────────────┘
```

## Requirements

- Python 3.8+
- pip

## Setup

### 1. Ensure Python is available

On some Linux distributions, `python` command may not exist (only `python3`). Fix with:

```bash
# Ubuntu/Debian (recommended)
sudo apt install python-is-python3

# Or manually create symlink
sudo ln -s /usr/bin/python3 /usr/bin/python
```

### 2. Install dependencies

```bash
pip install -r requirements.txt
```

### 3. Generate API token

Run the token generator script:

```bash
python generate_token.py
```

The script will prompt you for:
- **ActiveCollab URL** - Your self-hosted instance URL (e.g., `https://collab.yourcompany.com`)
- **Email** - Your ActiveCollab login email
- **Password** - Your ActiveCollab password (hidden input)

```
=== ActiveCollab API Token Generator (Self-Hosted) ===

ActiveCollab URL (e.g., https://collab.inchoo.net): https://collab.yourcompany.com
Email: your.email@company.com
Password: ********

Generating token...

==================================================
SUCCESS! Here are your credentials:

API URL: https://collab.yourcompany.com/api/v1
API Token: 1-aBcDeFgHiJkLmNoPqRsTuVwXyZ123456789
==================================================

Save to config.json now? (y/n): y
Saved to config.json!
```

**How it works:**
1. Makes a POST request to `/api/v1/issue-token` with your credentials
2. ActiveCollab returns a permanent API token for the "Claude MCP Server" client
3. Token is saved to `config.json`

**Alternative:** Manually create config.json:

```bash
cp config.json.example config.json
# Edit config.json with your API URL and token
```

### 4. Configure MCP server

```bash
cp .mcp.json.example .mcp.json
# Edit .mcp.json - update "cwd" to your absolute path
```

### 5. Restart Claude Code

## Available Tools

| Tool | Parameters | Description |
|------|------------|-------------|
| `list_projects` | - | List all projects |
| `get_project` | `project_id` | Get project details |
| `list_tasks` | `project_id`, `status` (all/open/completed) | List tasks for a project |
| `get_task` | `project_id`, `task_id` | Get task details |
| `my_tasks` | - | Get tasks assigned to current user |
| `get_task_comments` | `task_id` | Get comments on a task |
| `get_task_time_records` | `project_id`, `task_id` | Get time records for a task |
| `get_project_time_records` | `project_id` | Get all time records for a project |
| `get_notifications` | - | Get recent notifications for current user |
| `get_subtasks` | `project_id`, `task_id` | Get subtasks for a task |
| `get_overdue_tasks` | `project_id` | Get tasks with overdue deadlines |
| `get_tasks_with_deadlines` | `project_id` | Get open tasks sorted by due date |
| `get_labels` | - | Get all global task labels |
| `get_tasks_by_label` | `project_id`, `label_id` | Get tasks with specific label |
| `get_task_lists` | `project_id` | Get all task lists in a project |
| `get_tasks_by_list` | `project_id`, `task_list_id` | Get tasks in a specific list |
| `get_users` | - | Get all team members (not clients) |
| `get_tasks_by_assignee` | `project_id`, `user_id` | Get tasks assigned to a user |

## Usage Examples

```
> List all projects
> Show open tasks for project 5
> Get details of task 123
> Show my tasks
> Get comments for task 456
> Show time records for task 61735 in project 489
> Get all time records for project 489
> Show my notifications
> Get subtasks for task 61735 in project 489
> Show overdue tasks for project 489
> Show tasks with deadlines for project 489
> List all labels
> Show tasks with STORY label (272) in project 489
> Show task lists for project 489
> Show tasks in IN PROGRESS list (31231) for project 489
> List all team members
> Show tasks assigned to Željko (1090) in project 489
```

## Project Structure

```
activeMCP/
├── src/
│   ├── __init__.py
│   ├── server.py           # MCP server with tool definitions
│   ├── api/
│   │   ├── __init__.py
│   │   └── client.py       # ActiveCollab API client
│   └── utils/
│       ├── __init__.py
│       └── config.py       # Configuration loader
├── generate_token.py       # API token generator script
├── config.json             # API credentials (gitignored)
├── config.json.example     # Template for config.json
├── .mcp.json               # MCP server config (gitignored)
├── .mcp.json.example       # Template for .mcp.json
├── run_server.sh           # Server launcher script
├── requirements.txt
└── README.md
```

## Dependencies

- Python 3.8+ (ensure `python` command is available, see Setup step 1)
- `mcp>=1.0.0` - Model Context Protocol SDK
- `httpx>=0.25.0` - HTTP client (optional, using urllib)

## Implementation Status

- [x] Phase 1: Basic infrastructure (config, client, auth)
- [x] Phase 2: MCP server skeleton
- [x] Phase 3: Projects module (list, get)
- [x] Phase 4: Tasks module (list, get, filter by status)
- [x] Phase 5: Time tracking module (read only)
- [x] Phase 6: Comments module (read only)
- [x] Phase 7: Notifications module (read only)
- [x] Phase 8: Subtasks module (read only)
- [x] Phase 9: Deadlines module (overdue tasks, tasks with deadlines)
- [x] Phase 10: Labels module (list labels, filter tasks by label)
- [x] Phase 11: Task lists module (list task lists, filter tasks by list)
- [x] Phase 12: Users module (list users, filter tasks by assignee)
- [ ] Phase 13: Write operations (create/update tasks, add comments, log time)