vikunja-mcp

Was das ist

Die meisten Task-Tracker-Integrationen sind CRUD-Wrapper: Sie geben einem Agenten create_task, update_task, delete_task und hoffen, dass der Prompt ihn ehrlich hält. Dieses hier macht das Gegenteil. Es stellt zwölf schmale Tools bereit, und jedes einzelne verweigert die Schritte, die den Prozess brechen würden:

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

• Backlog und Done sind menschliches Territorium. Triage am einen Ende, Abnahme am anderen. Es gibt kein Argument für advance, das Done erreicht – ein Agent, der es versucht, bekommt gesagt: nur ein Mensch verschiebt eine Aufgabe nach der Überprüfung nach Done.

• Queue → Design → Build → Review ist die Agenten-Schleife. Eine Aufgabe übernehmen, einen Spec schreiben, um Design zu verlassen, ein Worklog und einen Evidence-SHA erstellen, um Build zu verlassen.

• Your Call ist der Seitenzweig für den Fall, dass ein Agent eine Entscheidung braucht, die er nicht allein treffen sollte. Es behält seine Zuweisung und seinen Kontext; der Mensch antwortet auf der Karte.

Tore sind Leitplanken für Agenten, keine Sicherheitsgrenze – die eigentliche Grenze ist das eingeschränkte API-Token, das Vikunja ausstellt. Siehe SECURITY.md.

Related MCP server: Accordo

Warum

Ein autonomer Agent, der gegen eine einfache Task-API läuft, driftet auf eine Weise ab, die einzeln betrachtet vernünftig und insgesamt nutzlos ist: Er markiert seine eigene Arbeit als erledigt, er beginnt das Nächste, bevor er das Aktuelle beendet, er „behebt“ einen Bug, indem er den Test löscht, und die einzige Aufzeichnung davon ist ein Chat-Log, das vor drei Stunden weggescrollt wurde.

Nichts davon wird durch einen längeren Prompt behoben. Der Prompt ist Ratschlag; der Tool-Aufruf ist der Entscheidungspunkt. Also wird der Prozess dort durchgesetzt, wo die Entscheidung passiert:

Was du zurückbekommst, ist ein Board, auf dem jede Karte ihre eigene Geschichte trägt – die Übernahme, den Plan, die Arbeit, das unabhängige Urteil – in der Reihenfolge, in der es passiert ist.

So sieht es in der Praxis aus

Eine Karte, die komplett durch die Schleife gelaufen ist. Hier wurde nichts von einem Menschen getippt: Die Marker, die Labels und die Stufe sind das, was die Tools geschrieben haben, als die Agenten sie bewegt haben.

Von oben nach unten gelesen ist das claim → advance(to="build", spec=…) → advance(to="review", worklog=…, evidence=…) → das review_task(verdict="approve", report=…) eines anderen Agenten. Das reviewed-Label ist das, was das Urteil hinterlassen hat; die Karte sitzt jetzt in Review und wartet darauf, dass ein Mensch sie absegnet. Jede Aufgabe bekommt diese Überprüfung, nicht nur Bugfixes – nur ein epic-Container ist ausgenommen, weil sein Code in seinen Kindern lebt.

Und wenn der Agent auf eine Entscheidung stößt, die nicht seine ist, parkt er die Karte, statt zu raten:

Die Karte behält ihren Bearbeiter, sodass sie zum selben Agenten zurückkommt, wenn du antwortest. Setze VIKUNJA_NOTIFY_WEBHOOK und du bekommst zusätzlich einen Slack-förmigen Ping mit einem Deep Link, sodass das Parken einer Frage nicht bedeutet, darauf zu warten, dass jemand ein Board bemerkt.

Schnellstart

1. Installieren – kein Klonen nötig, uvx führt es direkt aus dem Repo aus:

uvx --from git+https://github.com/ufna/vikunja-mcp@stable vikunja-mcp --version

2. Das Board erstellen. Mit einem Admin-Token erstellt dies das Projekt, falls es fehlt, und gleicht die sieben kanonischen Spalten ab (es migriert auch die Todo/Doing-Spalten eines Standard-Vikunja-Boards und gibt konfigurationsfertige Snippets aus):

VIKUNJA_TOKEN=<admin token> uvx --from git+https://github.com/ufna/vikunja-mcp@stable \
  vikunja-mcp setup --project "My Project" --share agent-bot:write --url https://vikunja.example.com

3. Das Repo darauf ausrichten. Committe .vikunja-mcp.toml; halte das Token daraus heraus:

[tracker]
url = "https://vikunja.example.com"
project_id = 12
wip_limit = 3          # how many Design/Build tasks one token may claim into at once
language = "en"        # "en" | "ru" — what language cards are written in

# .vikunja-mcp.env — same directory, gitignored, NEVER committed
VIKUNJA_TOKEN=tk_xxxxxxxxxxxx

4. Den Server registrieren bei Claude Code (.mcp.json) oder opencode (opencode.json). Beide abonnieren den beweglichen stable-Branch, sodass Releases beim nächsten Session-Start ohne pro-Repo-Anpassungen ausgerollt werden:

{ "mcpServers": { "tracker": {
    "command": "uvx",
    "args": ["--refresh-package", "vikunja-mcp",
             "--from", "git+https://github.com/ufna/vikunja-mcp@stable", "vikunja-mcp"]
} } }

{ "$schema": "https://opencode.ai/config.json", "mcp": { "tracker": {
    "type": "local",
    "command": ["uvx", "--refresh-package", "vikunja-mcp",
      "--from", "git+https://github.com/ufna/vikunja-mcp@stable", "vikunja-mcp"],
    "enabled": true
} } }

5. Dem Agenten den Prozess beibringen – vikunja-mcp install-skill installiert den gepackten Tracker-Skill (Queue-Disziplin, wann zu eskalieren ist, was ein Worklog einem Reviewer schuldet) für sowohl Claude Code als auch opencode. Für Claude Code richtet es außerdem einen bedingten SessionStart-Hook ein, sodass innerhalb eines tracker-konfigurierten Projekts ein nacktes /loop die Queue leert, anstatt auf den generischen Standard „starte keine Arbeit von dir aus“ zurückzufallen. Außerhalb eines solchen Projekts gibt der Hook nichts aus.

Dann führe die Schleife aus. /loop 10m für unbeaufsichtigte Arbeit, einfaches /loop, wenn du zusiehst.

Die zwölf Tools

Über die Tools hinaus

Drei Befehle runden die Schleife ab; keiner von ihnen spricht MCP, und das SDK wird lazy importiert, sodass sie nicht dafür zahlen.

vikunja-mcp claimable – eine JSON-Zeile, die die Frage beantwortet „Gibt es gerade beanspruchbare Arbeit für dieses Token?“, Exit 0, wenn die Prüfung lief. Es ruft das echte next_task() auf, kann also nicht von den Toren abweichen, und ist vertraglich schreibgeschützt. Entwickelt für einen Supervisor, der sonst bei jedem Poll-Tick eine kostenpflichtige Agenten-Session starten würde, nur um festzustellen, dass es nichts zu tun gibt.

vikunja-mcp workspace <id> — ein Git-Worktree pro Aufgabe auf einem Wegwerf-Zweig task/<id>, damit mehrere Agenten die Warteschlange parallel abarbeiten können, ohne sich um einen Checkout zu streiten. --release pusht und räumt auf; --gc erntet verwaiste Worktrees und führt deinen Haupt-Checkout per Fast-Forward. Seine Sicherheitsregel ist eine Zeile: Push OK → entfernen, Push fehlgeschlagen → behalten. Schmutzige, nicht gepushte oder unerreichbare Arbeit wird gemeldet, nie zerstört. (Eine echte Ausnahme, dokumentiert statt übertüncht: git-ignorierte Dateien sind für den Schmutz-Check unsichtbar. Bringe Screenshots aus dem Worktree, bevor du ihn freigibst — siehe das Dossier.)

vikunja-mcp setup / install-skill — idempotente Board-Abgleichung und die oben beschriebene agentenorientierte Skill-Installation. Beide können gefahrlos erneut ausgeführt werden; der MCP-Server heilt den installierten Skill auch beim Start selbst, sodass ein sich bewegendes stable ihn automatisch aktualisiert.

Konfiguration

Vier Ebenen, höchste Priorität zuerst:

1. Umgebung — VIKUNJA_URL, VIKUNJA_TOKEN, VIKUNJA_PROJECT_ID, VIKUNJA_NOTIFY_WEBHOOK

2. .vikunja-mcp.env — repo-lokale KEY=VALUE-Datei neben der TOML, git-ignoriert. Das projektspezifische Token für eine Maschine, die über mehrere Repos arbeitet.

3. .vikunja-mcp.toml — eingecheckt, wird vom aktuellen Arbeitsverzeichnis aus aufwärts gesucht. Sicher zu committen, da es keine Geheimnisse enthält.

4. ~/.config/vikunja-mcp/env — der übliche Ort für ein persönliches VIKUNJA_TOKEN (chmod 600).

Zwei Regeln machen diese Aufteilung wichtig, und sie laufen in entgegengesetzte Richtungen:

• Ein Geheimnis wird niemals aus der TOML gelesen. Weder das Token noch die Webhook-URL. So kann die eingecheckte Datei selbst versehentlich keines leaken.

• Teamrichtlinie wird niemals aus der Umgebung gelesen. wip_limit, require_review_independence und language sind nur in der TOML, weil sie beschreiben, wie das Projekt funktioniert, nicht auf welcher Maschine du bist. Nicht gesetzt, ist wip_limit 3 — nicht „unbegrenzt“; wip_limit = 0 ist ein Konfigurationsfehler, weil „keine Begrenzung“ bewusst nicht ausdrückbar ist. Nicht gesetzt, ist language "en", und ein nicht erkannter Wert ist ein Konfigurationsfehler aus demselben Grund.

worktree_root liegt auf der Maschinenseite dieser Linie, also gewinnt dort die Umgebung.

language regelt mehr als nur die eigene Ausgabe des Tools. Die Spezifikation, das Arbeitsprotokoll und der Review-Bericht machen den Großteil des Textes einer Karte aus, und das Tool schreibt sie nicht — der Agent tut das —, also steckt der Wert auch in jeder next_task-Antwort, und das mitgelieferte Regelwerk sagt dem Agenten, darin zu schreiben. Was es nie berührt, sind die Kommentar-Marker ([worklog], [review], …): zwei von ihnen werden mit startswith abgeglichen, um zu entscheiden, ob eine Karte zum Review angeboten wird, also sind sie in jeder Sprache eingefroren.

Vollständige Begründung, einschließlich warum das WIP-Limit einen Übergang begrenzt, anstatt eine Anzahl zu überwachen: docs/dossier/config.md.

Veröffentlichungen

Konsumenten abonnieren den sich bewegenden stable-Zweig. Jeder grüne Push auf main erhöht automatisch die Patch-Version, taggt vX.Y.Z und bewegt stable darauf — so erreicht ein Fix jedes konsumierende Repo beim nächsten Sitzungsstart, ohne PR-Bots und ohne versionsspezifische Bumps pro Repo. Unveränderliche Tags bleiben die Historie und die Rollback-Punkte:

git branch -f stable vX.Y.Z && git push -f origin stable   # rollback to a known-good tag

Minor- und Major-Bumps sind ein manuell bearbeiteter Commit; CI setzt das automatische Patchen ab der neuen Basis fort. docs/dossier/releases.md enthält die Rennanalyse hinter dem atomaren Push und dem Nur-Forward-Kanal.

Entwicklung

uv sync
uv run ruff check .
uv run pytest tests/unit -q

Integrationstests laufen gegen einen echten Vikunja-Container und überspringen sich selbst ohne VIKUNJA_TEST_URL — das Rezept steht in CONTRIBUTING.md, zusammen mit den Hausregeln, die weniger offensichtlich sind, als sie aussehen (warum die Zeilenlänge zwei Zahlen ist und warum ein Mutations-Sweep ohne Kontrollrunde nichts misst).

Dokumentation

docs/ — die Regeln leben in CLAUDE.md; die Beweise leben in neun Dossiers, eines pro Subsystem. Wenn du eine Schutzmaßnahme ändern willst, ist ihr Dossier der Ort, an dem die Messung, die sie dorthin gebracht hat, niedergeschrieben ist.

Lizenz

MIT — siehe LICENSE.