vikunja-mcp

这是什么

大多数任务追踪器集成都是 CRUD 包装器：它们给代理提供 create_task、update_task、delete_task，然后希望提示词能让它保持诚实。这个项目恰恰相反。它暴露了十二个狭窄的工具，每个工具都会拒绝那些会破坏流程的操作：

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，生成工作日志和证据 sha 以离开 Build。

• Your Call 是侧分支，用于代理需要做出不应独自决定的情况。它保留其分配和上下文；人类在卡片上回答。

门禁是代理的护栏，而不是安全边界——真正的边界是 Vikunja 生成的作用域 API 令牌。参见 SECURITY.md。

Related MCP server: Accordo

为什么

一个自主代理在普通任务 API 上持续运行，会以各种方式偏离轨道，这些方式单独看都合理，但合起来却毫无用处：它标记自己的工作已完成，它在完成当前任务之前就开始下一件事，它通过删除测试来“修复”错误，而这一切的唯一记录是一个三小时前就已经滚走的聊天日志。

这些问题都不是更长的提示词能解决的。提示词只是建议；工具调用才是决策点。所以流程在决策发生的地方强制执行：

你得到的是一块看板，其中每张卡片都携带自己的历史——认领、计划、工作、独立裁决——按发生顺序排列。

实际效果

一张卡片已经完整走完整个循环。这里没有任何内容是人类输入的：标记、标签和阶段都是工具在代理移动卡片时写入的。

从上到下阅读，那就是 claim → advance(to="build", spec=…) → advance(to="review", worklog=…, evidence=…) → 一个不同代理的 review_task(verdict="approve", report=…)。reviewed 标签是裁决留下的；卡片现在位于 Review 中，等待人类签核。每个任务都会得到这种审查，而不仅仅是 bug 修复——只有 epic 容器例外，因为它的代码存在于其子任务中。

当代理遇到一个不属于它决定的决策时，它会停放卡片而不是猜测：

卡片保留其分配人，所以当你回答时它会回到同一个代理。设置 VIKUNJA_NOTIFY_WEBHOOK，你还会收到一个带有深度链接的 Slack 风格通知，因此停放问题并不意味着要等别人注意到看板。

快速开始

1. 安装 — 无需克隆，uvx 直接从仓库运行：

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

2. 创建看板。 使用管理员令牌，如果项目不存在则创建，并协调七个标准列（它还会迁移默认 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 用于你在观看时。

十二个工具

工具之外

三个命令完善了循环；它们都不使用 MCP，并且 SDK 是惰性导入的，因此它们不会为此付出代价。

vikunja-mcp claimable — 一行 JSON 回答“这个令牌现在是否有可认领的工作？”，如果检查运行则退出码为 0。它调用真正的 next_task()，因此不会偏离门禁，并且按约定是只读的。专为监督者设计，否则它会在每次轮询时启动一个付费代理会话，却发现无事可做。

vikunja-mcp workspace <id> — 每个任务一个 git worktree，放在一次性的 task/<id> 分支上，这样多个代理可以并行处理队列，而不会争抢同一个检出。--release 推送并清理；--gc 回收孤儿并快进你的主检出。它的安全规则只有一行：推送成功 → 移除，推送失败 → 保留。 脏的、未推送的或不可达的工作会被报告，但绝不会被销毁。（有一个真实的例外，已记录而非掩盖：git-忽略 的文件对脏检查不可见。在释放 worktree 之前，请将截图带出——参见 档案。）

vikunja-mcp setup / install-skill — 幂等的看板协调，以及上述面向代理的技能安装。两者都可以安全地重新运行；MCP 服务器还会在启动时自愈已安装的技能，因此移动的 stable 会自动刷新它。

配置

四层，优先级从高到低：

1. 环境 — VIKUNJA_URL、VIKUNJA_TOKEN、VIKUNJA_PROJECT_ID、VIKUNJA_NOTIFY_WEBHOOK

2. .vikunja-mcp.env — 位于 toml 旁边的仓库本地 KEY=VALUE 文件，已被 git 忽略。适用于跨多个仓库工作的机器的项目级令牌。

3. .vikunja-mcp.toml — 已提交，从当前工作目录向上查找。可以安全提交，因为它不包含任何秘密。

4. ~/.config/vikunja-mcp/env — 个人 VIKUNJA_TOKEN 的通常存放位置（chmod 600）。

两条规则让这种划分变得重要，而且它们方向相反：

• 秘密永远不会从 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]、……）：其中两个使用 startswith 匹配来决定卡片是否被提供审查，因此它们在每种语言中都是固定的。

完整推理，包括为什么 WIP 限制只控制一个转换而不是监管计数：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 中，还有那些看起来不明显但实际很重要的内部规则（为什么行长度是两个数字，以及为什么没有对照轮次的变异扫描毫无意义）。

文档

docs/ — 规则位于 CLAUDE.md 中；证据 存在于九个档案中，每个子系统一个。如果你要更改某个防护，其档案中记录了当初设置它的测量依据。

许可证

MIT — 参见 LICENSE。