From 4363130163dba9590dca2fcbc86593f18ce11224 Mon Sep 17 00:00:00 2001 From: Alvis Date: Sat, 4 Jul 2026 13:25:21 +0000 Subject: [PATCH] Add Kanboard CLAUDE.md and list it in parent service table Document how to work with Kanboard, especially finding tasks assigned to the claude bot user via kanboard_my_tasks / search_tasks. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2 --- CLAUDE.md | 1 + kanboard/CLAUDE.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 kanboard/CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md index 645e425..2a82c83 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,6 +14,7 @@ This repository manages Docker Compose configurations for the **Agap** self-host | `gitea/` | Gitea (git hosting) + Postgres | 3000, 222 | Standalone compose | | `openai/` | Open WebUI + Ollama (AI chat) | 3125 | Requires NVIDIA GPU | | `vaultwarden/` | Vaultwarden (password manager) | 8041 | Backup script in `vaultwarden/backup.sh` | +| `kanboard/` | Kanboard (kanban board) | 4800 | Tasks assignable to the `claude` bot user — see `kanboard/CLAUDE.md` | ## Common Commands diff --git a/kanboard/CLAUDE.md b/kanboard/CLAUDE.md new file mode 100644 index 0000000..8c826f9 --- /dev/null +++ b/kanboard/CLAUDE.md @@ -0,0 +1,82 @@ +# CLAUDE.md — Kanboard + +Guidance for Claude Code when working with the Kanboard service on the Agap server. + +## Overview + +Kanboard is the kanban board for Agap. Tasks can be **assigned to the `claude` bot user**, and Claude acts on them via the `mcp__agap__kanboard_*` MCP tools (server `agap`). This directory holds only the Docker Compose config; the board data lives in a Docker volume. + +- Container `kanboard`, image `kanboard/kanboard:latest`, port `127.0.0.1:4800:80` +- Storage: SQLite in the `data` volume (`/var/www/app/data/db.sqlite`) +- JSON-RPC API at `/jsonrpc.php`; app-wide admin auth = HTTP Basic `jsonrpc:` +- App token stored in Vaultwarden as `KANBOARD_TOKEN` + +### The `claude` bot user + +- User `claude` = id **2**, role `app-admin`, web password in Vaultwarden `KANBOARD_CLAUDE_PASSWORD` +- **Gotcha:** `app-admin` only grants *visibility*. To be **assignable** as a task owner, a user must be a **project member**. `claude` is added as `project-member` to every project. Any *new* project needs this too, or assigning/creating tasks owned by `claude` returns `false`. Add via JSON-RPC `addProjectUser(project_id, 2, "project-member")`. + +## Finding tasks assigned to Claude + +**Primary method — use the dedicated MCP tool.** It lists tasks owned by the `claude` bot user across *all* projects in one call: + +``` +mcp__agap__kanboard_my_tasks(status="open") # default: open tasks +mcp__agap__kanboard_my_tasks(status="all") # open + closed +mcp__agap__kanboard_my_tasks(status="closed") +``` + +Returned tasks have `owner_id: 2` (claude) and include `project_id`, `project_name`, `column_id`, `title`, etc. Use `mcp__agap__kanboard_get_task(task_id=)` for full detail (description, subtasks, comments). + +**Per-project search** — Kanboard query syntax, scoped to one project: + +``` +mcp__agap__kanboard_search_tasks(project_id=, query="assignee:claude status:open") +``` + +Useful query filters: `assignee:claude`, `status:open`, `due:today`, `color:red`. + +## Working a task + +Typical flow once a task is found: + +1. `kanboard_get_task(task_id)` — read full detail +2. `kanboard_change_task_status` / `kanboard_move_task` — mark in-progress / move column +3. `kanboard_add_comment` — record progress or findings +4. `kanboard_change_task_status` — close when done + +Discover the board layout with `kanboard_list_projects` and `kanboard_get_project(project_id)` (returns columns + swimlanes, needed to move cards). + +## Full MCP toolset (`mcp__agap__kanboard_*`) + +`list_projects`, `get_project`, `list_users`, `list_tasks`, `my_tasks`, `get_task`, +`search_tasks`, `project_activity`, `create_task`, `update_task`, `move_task`, +`assign_task`, `change_task_status`, `add_comment`, `remove_comment`, +`create_subtask`, `update_subtask`, `remove_task`. + +Writes are authored as `claude` (via `user_id`) using the app-wide `KANBOARD_TOKEN`. + +## Common Commands + +```bash +docker compose up -d # start +docker compose restart # restart +docker compose logs -f # logs + +# Read the API token from the DB (matches Vaultwarden KANBOARD_TOKEN) +docker exec kanboard php -r '$db=new PDO("sqlite:/var/www/app/data/db.sqlite"); echo $db->query("SELECT value FROM settings WHERE option=\"api_token\"")->fetch()[0];' +``` + +## MCP server + +The `kanboard_*` tools are implemented in `agap-mcp` (`/home/alvis/agap_git/agap-mcp`, `src/kanboard.js`, port 3100, tool name `agap`). Env: `KANBOARD_URL`, `KANBOARD_TOKEN`, `KANBOARD_BOT_USER=claude`. After editing the server: + +```bash +cd /home/alvis/agap_git/agap-mcp && docker compose build && docker compose up -d +``` + +New/changed tools appear after Claude reconnects to the MCP. + +## Gitea wiki + +Kanboard is documented on the AgapHost wiki `Kanboard` page (`http://localhost:3000/alvis/AgapHost/wiki`). Update it when the setup changes — see the parent `../CLAUDE.md` for wiki edit instructions.