Add Kanboard page: service, API, claude bot user, agap-mcp tools

2026-06-04 07:22:30 +00:00
parent 9778392594
commit 08cd28a1c1

60
Kanboard.md Normal file

@@ -0,0 +1,60 @@
# Kanboard
Kanban task boards. Tasks can be assigned to **Claude**, which fetches, works,
comments and moves cards like a regular team member via the `agap-mcp` server.
## Service
- Image: `kanboard/kanboard:latest`, container `kanboard`
- Compose: `/home/alvis/agap_git/kanboard/docker-compose.yml`
- Port: `127.0.0.1:4800``:80` (reverse-proxied via Caddy externally)
- Storage: SQLite in the `kanboard_data` volume (`/var/www/app/data/db.sqlite`)
## API
JSON-RPC at `/jsonrpc.php`. Two auth modes:
- **App-wide (admin):** HTTP Basic `jsonrpc:<token>` — full access to every
project. Token lives in the DB `settings` table (`option='api_token'`) and is
stored in Vaultwarden as **`KANBOARD_TOKEN`**.
- **Per-user:** `<username>:<personal-token>` — scoped to that user.
```bash
curl -s -u "jsonrpc:$KANBOARD_TOKEN" http://localhost:4800/jsonrpc.php \
-d '{"jsonrpc":"2.0","method":"getAllProjects","id":1}'
```
## Claude bot user
- User `claude` (display **Claude**), role `app-admin`, web password in
Vaultwarden as **`KANBOARD_CLAUDE_PASSWORD`**.
- **Gotcha:** app-admin grants *visibility* only. To be **assignable** a user
must be a **project member**`claude` is added as `project-member` to every
project via `addProjectUser(project_id, user_id, "project-member")`.
- Assign a card to `claude` (in the UI or `kanboard_assign_task`) and it shows up
in `kanboard_my_tasks`.
## agap-mcp integration
Implemented in `agap-mcp` (`src/kanboard.js`, registered in `src/server.js`).
Authenticates with the app-wide `KANBOARD_TOKEN`; writes (comments, tasks,
subtasks) are authored as `claude` via `user_id`. Env: `KANBOARD_URL`,
`KANBOARD_BOT_USER=claude`.
Tools (`mcp__agap__kanboard_*`):
| Tool | Purpose |
|------|---------|
| `list_projects` / `get_project` | projects; columns + swimlanes |
| `list_tasks` / `my_tasks` | tasks in a project / assigned to claude (all projects) |
| `get_task` | task + subtasks + comments |
| `search_tasks` | Kanboard query syntax (`assignee:`, `status:`, `due:`) |
| `list_users` / `project_activity` | monitor users / activity stream |
| `create_task` / `update_task` | create / edit |
| `move_task` / `change_task_status` | move column / open-close |
| `assign_task` | (re)assign to a user |
| `add_comment` | comment as claude |
| `create_subtask` / `update_subtask` | track execution steps (0 todo/1 wip/2 done) |
| `remove_task` / `remove_comment` | delete (irreversible) |
Deleting whole projects is intentionally not exposed.