vikunja-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code when working in this repository.

How this file is organised — read this first. What lives here are RULES: short, imperative, binding. The evidence under them — measurements, constructed stands, refuted wordings, the per-card post-mortems — lives in docs/dossier/*.md, one file per subsystem, linked at the end of each section and from the module's own docstring.

Two consequences, both binding:

• Changing a module? Read its dossier first. The rule here is short precisely because the proof is there. This repo has repeatedly "fixed" a guard by reasoning instead of measuring, several rounds running; if a rule looks redundant or simplifiable, the answer is almost certainly in the dossier. The reviewer checks that it was read.
• A new card's post-mortem goes to the card and to the dossier, NOT here. This file enters EVERY session's context — the orchestrator's, every per-task agent's and every reviewer's; at wip_limit = 3 that is ~7 contexts per round. Edit here only when the RULE itself changed. The size of both rulebooks is pinned by tests/unit/test_rulebook_size.py, which is a ratchet: when it shrinks, lower the ceiling in the same commit.

What This Is

Workflow-level MCP server for a self-hosted Vikunja tracker — NOT a CRUD wrapper. The pipeline and its gates ARE the product:

Backlog → Queue → Design → Build → Review → [human] → Done
                     ↕        ↕
                  Your Call         (+ independent review of EVERY task in Review)

14 agent tools (next_task, claim, get_task, comment, advance, call_human, return_task, decompose, file_task, review_task, attach_file, download_attachment, handoff, transfer_task); agents can never move a task to Done — that transition is human-only by design. Gates are guardrails for agents; the real security boundary is the scoped API token.

Commands

uv sync                                   # env (Python 3.11+, uv)
uv run pytest tests/unit -q               # 500+ unit tests (FakeAPI, MockTransport)
uv run ruff check .                       # lint — wrap at 100, RED above 110 (see below)
uv run vikunja-mcp --version              # smoke
uv run vikunja-mcp claimable              # one JSON line: is there claimable work for this
                                          # token? (hgdev-acp hub's pre-launch idle check)

# integration — real Vikunja 2.3.0 in docker (skipped without VIKUNJA_TEST_URL):
docker run -d --name vikunja-test -p 3456:3456 \
  -e VIKUNJA_DATABASE_TYPE=sqlite -e VIKUNJA_DATABASE_PATH=/tmp/vikunja.db \
  -e VIKUNJA_FILES_BASEPATH=/tmp/files -e VIKUNJA_SERVICE_JWTSECRET=integration-test-secret \
  -e VIKUNJA_SERVICE_PUBLICURL=http://localhost:3456/ -e VIKUNJA_SERVICE_ENABLEREGISTRATION=true \
  vikunja/vikunja:2.3.0
until curl -sf http://localhost:3456/api/v1/info >/dev/null; do sleep 1; done
VIKUNJA_TEST_URL=http://localhost:3456 uv run pytest tests/integration -q
docker rm -f vikunja-test