vikunja-mcp

これは何か

ほとんどのタスクトラッカー統合はCRUDラッパーです。エージェントにcreate_task、update_task、delete_taskを渡し、プロンプトが正直さを保ってくれることを願います。これはその逆です。12個の狭いツールを公開し、それぞれがプロセスを壊す動きを拒否します。

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

• BacklogとDoneは人間の領域です。 一方の端でトリアージ、もう一方の端で承認。advanceにDoneに到達する引数はありません。試みるエージェントにはレビュー後にタスクをDoneに移動できるのは人間だけと伝えられます。

• Queue → Design → Build → Reviewはエージェントのループです。 タスクをクレームし、Designを離れるためのスペックを書き、Buildを離れるためのワークログとエビデンスshaを生成します。

• **Your Call**は、エージェントが単独で下すべきでない決定が必要なときのサイドブランチです。割り当てとコンテキストを保持し、人間がカード上で回答します。

ゲートはエージェントのためのガードレールであり、セキュリティ境界ではありません。実際の境界はVikunjaが発行するスコープ付きAPIトークンです。SECURITY.mdを参照してください。

Related MCP server: Accordo

なぜ

素のタスクAPIに対して自律エージェントを動かし続けると、個々には合理的でも全体としては役に立たない方向に漂流します。自分の作業を完了とマークし、これを終える前に次のことを始め、テストを削除してバグを「修正」し、その記録は3時間前にスクロールして消えたチャットログだけです。

それのどれも、より長いプロンプトでは修正されません。プロンプトはアドバイスであり、ツール呼び出しが決定ポイントです。だからプロセスは決定が行われる場所で強制されます。

得られるのは、各カードが独自の履歴（クレーム、計画、作業、独立した判定）を発生順に保持するボードです。

実際の様子

ループを一巡したカードです。ここにあるものは人間が入力したものはありません。マーカー、ラベル、ステージは、エージェントがカードを移動させたときにツールが書いたものです。

上から下に読むと、claim → advance(to="build", spec=…) → advance(to="review", worklog=…, evidence=…) → 別のエージェントのreview_task(verdict="approve", report=…)です。reviewedラベルは判定が残したもので、カードは現在Reviewにあり、人間の承認を待っています。すべてのタスクがそのレビューを受けます。バグ修正だけではありません。epicコンテナだけは例外で、そのコードは子に存在するからです。

そして、エージェントが自分が下すべきでない決定に直面したとき、推測する代わりにカードを駐車します。

カードは割り当て先を保持するので、あなたが回答すると同じエージェントに戻ります。VIKUNJA_NOTIFY_WEBHOOKを設定すると、ディープリンク付きのSlack形式のpingも受け取れます。質問を駐車しても、誰かがボードに気づくのを待つ必要はありません。

クイックスタート

1. インストール — クローンは不要、uvxがリポジトリから直接実行します：

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

2. ボードを作成。 管理者トークンを使用すると、プロジェクトが存在しない場合は作成し、7つの標準列を調整します（デフォルトのVikunjaボードのTodo/Doing列も移行し、コミット可能な設定スニペットを出力します）：

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. リポジトリをそれに向けます。 .vikunja-mcp.tomlをコミットし、トークンはその外に保持します：

[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. サーバーを登録 Claude Code (.mcp.json) または opencode (opencode.json) で。両方とも移動するstableブランチにサブスクライブするため、リリースは次回のセッション開始時にリポジトリごとのバンプなしで展開されます：

{ "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. エージェントにプロセスを教える — vikunja-mcp install-skillは、Claude Codeとopencodeの両方にパッケージ化されたトラッカースキル（キュー規律、いつエスカレーションするか、ワークログがレビュアーに何を負うか）をインストールします。Claude Codeでは、条件付きSessionStartフックもプロビジョニングし、トラッカー設定済みプロジェクト内では、裸の/loopが「自分で作業を始めない」という一般的なデフォルトにフォールバックする代わりにキューを排出します。そのようなプロジェクトの外では、フックは何も出力しません。

次にループを実行します。無人作業には/loop 10m、見ているときは素の/loop。

12のツール

ツールを超えて

3つのコマンドがループを完成させます。どれもMCPを話さず、SDKは遅延インポートされるため、そのコストを支払いません。

vikunja-mcp claimable — 「このトークンに対して今クレーム可能な作業はあるか？」に答える1行のJSON。チェックが実行された場合は終了コード0。実際のnext_task()を呼び出すため、ゲートから逸脱できず、契約上読み取り専用です。ポーリングのたびに有料エージェントセッションを起動して何もすることがないと発見するだけのスーパーバイザーのために作られました。

vikunja-mcp workspace <id> — 使い捨ての task/<id> ブランチ上にタスクごとの git worktree を作成します。これにより、複数のエージェントが1つのチェックアウトを奪い合うことなく、並行してキューを処理できます。--release はプッシュしてクリーンアップし、--gc は孤立した worktree を回収してメインのチェックアウトを fast-forward します。安全ルールは1行です: プッシュ成功 → 削除、プッシュ失敗 → 保持。 汚れた作業、未プッシュの作業、到達不能な作業は報告され、決して破棄されません。(実際の例外が1つあり、隠蔽ではなく文書化されています: git で 無視 されたファイルは汚れチェックでは見えません。リリースする前に worktree からスクリーンショットを取り出してください — 資料 を参照。)

vikunja-mcp setup / install-skill — 冪等なボード調整と、前述のエージェント向けスキルインストールです。どちらも再実行しても安全で、MCP サーバーは起動時にインストール済みスキルを自己修復するため、移動する stable があれば自動的に更新されます。

設定

4つのレイヤーがあり、優先度が高い順に:

1. 環境変数 — VIKUNJA_URL、VIKUNJA_TOKEN、VIKUNJA_PROJECT_ID、VIKUNJA_NOTIFY_WEBHOOK

2. .vikunja-mcp.env — toml の隣にあるリポジトリローカルの KEY=VALUE ファイルで、gitignore されています。複数のリポジトリで作業するマシン用のプロジェクト別トークンを置く場所です。

3. .vikunja-mcp.toml — コミットされ、cwd から上方向に探索して見つかります。秘密情報を含まないためコミットしても安全です。

4. ~/.config/vikunja-mcp/env — 個人の VIKUNJA_TOKEN を置く通常の場所です(chmod 600)。

この分割が重要になる理由は2つのルールにあり、それらは逆方向に働きます:

• 秘密情報は toml から読み取られることはありません。 トークンも webhook URL もです。したがって、コミットされたファイルが偶発的に秘密情報を漏らすことはありません。

• チームの方針は環境変数から読み取られることはありません。 wip_limit、require_review_independence、language は toml のみです。なぜなら、これらは プロジェクト がどう動くかを記述するものであり、どのマシンにいるかではないからです。未設定の場合、wip_limit は 3 であり、「無制限」ではありません。wip_limit = 0 は設定エラーです。「制限なし」が意図的に表現不可能だからです。未設定の場合、language は "en" であり、認識できない値は同じ理由で設定エラーです。

worktree_root はその線のマシン側にあるため、そこでは環境変数が優先されます。

language はツール自身の出力だけでなく、より多くのものを管理します。仕様、作業ログ、レビューレポートはカードのテキストの大部分を占めますが、ツールはそれらを書きません — エージェントが書きます — したがって、この値はすべての next_task レスポンスにも含まれ、パッケージ化されたルールブックはエージェントにその言語で書くよう指示します。決して触れないのはコメントマーカー([worklog]、[review]、…)です。そのうち2つは startswith で照合され、カードがレビュー対象として提供されるかどうかを決定するため、すべての言語で固定されています。

WIP 制限がカウントを監視するのではなく1つの遷移を制限する理由を含む完全な論拠は、docs/dossier/config.md にあります。

リリース

利用者は移動する stable ブランチを購読します。main へのすべてのグリーンのプッシュはパッチバージョンを自動的に上げ、vX.Y.Z にタグを付け、stable をその上に移動させます — したがって、修正は PR ボットもリポジトリごとのバージョンアップもなしに、次のセッション開始時にすべての利用リポジトリに届きます。不変のタグは履歴とロールバックポイントとして残ります:

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

マイナーおよびメジャーバージョンのアップは手動編集のコミットです。CI は新しいベースラインから自動パッチを再開します。アトミックなプッシュと前方のみのチャネルの背後にある競合分析は docs/dossier/releases.md にあります。

開発

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

統合テストは実際の Vikunja コンテナに対して実行され、VIKUNJA_TEST_URL がない場合は自分自身をスキップします — レシピは CONTRIBUTING.md にあり、見た目ほど明白ではないハウスルール(行の長さが2つの数値である理由、対照ラウンドなしのミューテーションスイープが何も測定しない理由)もそこにあります。

ドキュメント

docs/ — ルールは CLAUDE.md にあり、証拠 は9つの資料にあり、サブシステムごとに1つです。ガードを変更しようとしている場合、その資料が、そのガードを設置した測定値が記録されている場所です。

ライセンス

MIT — LICENSE を参照してください。