# Planka MCP — Hermes MCP server untuk Planka Kanban

MCP server yang menghubungkan Hermes ke Planka (kanban self-hosted BTD) via REST API.

## 13 Tools

| Tool | Fungsi |
|---|---|
| `list_projects` | List semua project |
| `create_project` | Buat project (private/shared) |
| `get_project` | Detail project + boards |
| `create_board` | Buat board di project |
| `get_board` | Detail board + lists |
| `create_list` | Buat list/kolom di board |
| `list_cards` | List card dalam list |
| `create_card` | Buat card |
| `get_card` | Detail card + members |
| `list_users` | List semua user |
| `create_user` | Buat user (admin/projectOwner/boardUser) |
| `add_board_member` | Assign user ke board (WAJIB sebelum card) |
| `add_card_member` | Assign user ke card — **multi-assignee** (panggil berulang utk tim) |

## Setup

```bash
cd ~/planka-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt   # mcp==1.29.0, requests
```

## Register Hermes

```bash
yes | hermes mcp add planka \
  --command /home/dedieko/planka-mcp/venv/bin/python3 \
  --env PLANKA_BASE_URL=http://127.0.0.1:13370 PLANKA_EMAIL=admin@ugm.ac.id PLANKA_PASSWORD='<pass>' \
  --args /home/dedieko/planka-mcp/run_planka_mcp.py
```

⚠️ Semua env dalam SATU `--env` (dipisah spasi). Restart gateway untuk aktif.

## Auth Flow (terms-aware)

1. `POST /api/access-tokens` {emailOrUsername, password}
2. Jika `pendingToken` → `GET /api/terms` → signature = **sha256(isi terms)** → `POST /api/access-tokens/accept-terms`

## Struktur Data

```
project (type: private)
 └── boards (type: trello, position)
      └── lists (type: active, position)
           └── cards (type: project)
                └── card-memberships (multi-user)
```

## Assign Member (2-step, wajib)

1. `POST /api/boards/:id/board-memberships` {userId, role: editor} — tanpa ini "User not found"
2. `POST /api/cards/:id/card-memberships` {userId} — panggil per anggota tim

## Repo Terkait

- Deploy: https://github.com/dedieko-priyadi/planka
- Planka: https://planka.app / https://github.com/plankanban/planka