AgapHost/kanboard/CLAUDE.md

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:<token>
• 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=<id>) for full detail (description, subtasks, comments).

Per-project search — Kanboard query syntax, scoped to one project:

mcp__agap__kanboard_search_tasks(project_id=<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

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:

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.