From 73ebe6408daea13af6d5194737d5f8bbbd5f8672 Mon Sep 17 00:00:00 2001 From: Alvis Date: Sun, 5 Jul 2026 06:28:11 +0000 Subject: [PATCH] Trim kanboard/CLAUDE.md to a pointer at the new consolidated kanboard repo Kanboard service docs, orchestration rules, quota script, and a reference copy of the MCP tool implementation have been consolidated into a new dedicated repo (alvis/kanboard, cloned to /home/alvis/kanboard). This directory now documents only the live docker-compose config that stays here. --- kanboard/CLAUDE.md | 79 +++++++--------------------------------------- 1 file changed, 11 insertions(+), 68 deletions(-) diff --git a/kanboard/CLAUDE.md b/kanboard/CLAUDE.md index 8c826f9..4797176 100644 --- a/kanboard/CLAUDE.md +++ b/kanboard/CLAUDE.md @@ -2,59 +2,19 @@ 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. +This directory holds only the **live** Docker Compose config for the `kanboard` +container (board data lives in a Docker volume). Everything else Kanboard-related — +service docs, the task-orchestration ruleset, the `claude-usage` quota script, and a +reference copy of the `kanboard_*` MCP tool implementation — has been consolidated into +its own repo: **`/home/alvis/kanboard`** (Gitea: `alvis/kanboard`). Read +`/home/alvis/kanboard/CLAUDE.md` before working with Kanboard or the orchestration +pipeline. - 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`. +- The MCP server implementing `mcp__agap__kanboard_*` (`src/kanboard.js`) lives in + `agap-mcp` (`/home/alvis/agap_git/agap-mcp`) — shared with other tool sets (`vw_*`, + `gitea_*`, `ha_*`, `zabbix_*`, `radicale_*`), so it stays here rather than moving to + the kanboard repo. ## Common Commands @@ -62,21 +22,4 @@ Writes are authored as `claude` (via `user_id`) using the app-wide `KANBOARD_TOK 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.