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은 사람의 영역입니다. 한쪽 끝에서 트리아지, 다른 쪽 끝에서 승인. Done에 도달하는 advance 인자는 존재하지 않습니다 — 시도하는 에이전트는 리뷰 후 Done으로 옮기는 것은 사람만 할 수 있다는 답을 듣습니다.

• Queue → Design → Build → Review가 에이전트 루프입니다. 태스크를 클레임하고, Design을 떠날 때 스펙을 작성하고, Build를 떠날 때 워크로그와 증거 sha를 남깁니다.

• 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에 있습니다. 모든 태스크가 그 리뷰를 받습니다. 버그 수정만이 아니라요 — 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> — 임시 task/<id> 브랜치의 작업별 git worktree로, 여러 에이전트가 하나의 체크아웃을 두고 충돌하지 않고 큐를 병렬로 처리할 수 있게 해줍니다. --release는 푸시하고 정리하며, --gc는 고아(orphan)를 수거하고 메인 체크아웃을 fast-forward합니다. 안전 규칙은 한 줄입니다: 푸시 성공 → 제거, 푸시 실패 → 유지. 더티(dirty)하거나 푸시되지 않았거나 도달 불가능한 작업은 보고될 뿐 파괴되지 않습니다. (실제 예외 하나가 있는데, 숨기지 않고 문서화되어 있습니다: git에서 무시된(ignored) 파일은 더티 검사에 보이지 않습니다. 릴리스하기 전에 worktree에서 스크린샷을 꺼내 두세요 — dossier 참조.)

vikunja-mcp setup / install-skill — 멱등(idempotent) 보드 정합성 조정과 위에서 설명한 에이전트용 스킬 설치입니다. 둘 다 재실행해도 안전하며, MCP 서버는 시작 시 설치된 스킬을 자가 복구하므로 이동하는 stable이 자동으로 새로고침됩니다.

구성

우선순위가 높은 순서대로 네 계층:

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).

이 구분이 의미를 갖게 하는 두 가지 규칙이 있으며, 서로 반대 방향으로 작동합니다:

• 비밀은 절대 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 제한이 개수를 감시하는 대신 하나의 전이(transition)를 게이트하는 이유를 포함한 전체 근거: 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에 있고, 증거는 하위 시스템별로 하나씩, 아홉 개의 dossier에 있습니다. 가드를 변경하려 한다면, 그 가드를 넣게 만든 측정값이 기록된 곳이 바로 해당 dossier입니다.

라이선스

MIT — LICENSE 참조.