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 — это боковая ветвь для случаев, когда агенту нужно решение, которое он не должен принимать в одиночку. Он сохраняет своё назначение и свой контекст; человек отвечает на карточке.

Шлюзы — это ограждения для агентов, а не граница безопасности — настоящая граница — это ограниченный API-токен, который выдаёт Vikunja. См. SECURITY.md.

Related MCP server: Accordo

Зачем

Автономный агент, работающий с обычным API задач, дрейфует в сторону действий, которые по отдельности разумны, а вместе бесполезны: он отмечает свою работу как выполненную, начинает следующее дело, не закончив текущее, «исправляет» баг, удаляя тест, и единственная запись обо всём этом — это чат-лог, который прокрутился три часа назад.

Ничто из этого не исправляется более длинным промптом. Промпт — это совет; вызов инструмента — это точка принятия решения. Поэтому процесс enforced там, где происходит решение:

Что вы получаете в итоге — это доска, где каждая карточка несёт свою собственную историю — захват, план, работа, независимый вердикт — в том порядке, в котором это произошло.

Как это выглядит на практике

Карточка, которая прошла весь цикл. Здесь ничего не было набрано человеком: маркеры, метки и стадия — это то, что инструменты записали, когда агенты перемещали её.

Читая сверху вниз, это claim → advance(to="build", spec=…) → advance(to="review", worklog=…, evidence=…) → review_task(verdict="approve", report=…) другого агента. Метка reviewed — это то, что оставил вердикт; карточка теперь находится в Review, ожидая подписи человека. Каждая задача получает такое ревью, не только исправления багов — только контейнер epic освобождён, потому что его код живёт в его дочерних элементах.

И когда агент сталкивается с решением, которое не ему принимать, он паркует карточку вместо того, чтобы угадывать:

Карточка сохраняет своего исполнителя, поэтому она возвращается к тому же агенту, когда вы отвечаете. Установите VIKUNJA_NOTIFY_WEBHOOK — и вы также получите ping в стиле Slack с глубокой ссылкой, так что парковка вопроса не означает ожидание, пока кто-то заметит доску.

Быстрый старт

1. Установка — клонирование не нужно, uvx запускает его прямо из репозитория:

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

2. Создайте доску. С админ-токеном это создаёт проект, если он отсутствует, и согласовывает семь канонических колонок (также мигрирует колонки Todo/Doing стандартной доски Vikunja и выводит готовые к коммиту фрагменты конфигурации):

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>, чтобы несколько агентов могли параллельно обрабатывать очередь, не конфликтуя из-за одного checkout. --release пушит и очищает; --gc собирает осиротевшие ветки и делает fast-forward вашего основного checkout. Его правило безопасности — одна строка: push OK → удалить, push FAIL → сохранить. Грязная, не запушенная или недостижимая работа сообщается, но никогда не уничтожается. (Одно реальное исключение, задокументированное, а не скрытое: файлы, игнорируемые git, невидимы для проверки на грязность. Выносите скриншоты из worktree перед его освобождением — см. досье.)

vikunja-mcp setup / install-skill — идемпотентная сверка доски и установка навыка для агента, описанная выше. Обе операции безопасно повторять; MCP-сервер также самовосстанавливает установленный навык при запуске, так что движущийся stable автоматически обновляет его.

Конфигурация

Четыре уровня, приоритет сверху вниз:

1. Окружение — VIKUNJA_URL, VIKUNJA_TOKEN, VIKUNJA_PROJECT_ID, VIKUNJA_NOTIFY_WEBHOOK

2. .vikunja-mcp.env — локальный для репозитория файл KEY=VALUE рядом с toml, в gitignore. Пер-проектный токен для машины, работающей с несколькими репозиториями.

3. .vikunja-mcp.toml — закоммиченный, находится подъёмом от текущей директории. Безопасно коммитить, потому что не содержит секретов.

4. ~/.config/vikunja-mcp/env — обычное место для личного VIKUNJA_TOKEN (chmod 600).

Два правила делают это разделение важным, и они действуют в противоположных направлениях:

• Секрет никогда не читается из toml. Ни токен, ни 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 автоматически увеличивает patch-версию, ставит тег 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.