vikunja-mcp

Qué es esto

La mayoría de las integraciones de rastreadores de tareas son envoltorios CRUD: le dan a un agente create_task, update_task, delete_task y esperan que el prompt lo mantenga honesto. Esta hace lo contrario. Expone doce herramientas específicas, y cada una rechaza los movimientos que romperían el proceso:

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

• Backlog y Done son territorio humano. Triage en un extremo, aprobación en el otro. No hay argumento para advance que llegue a Done — a un agente que lo intente se le dice solo un humano mueve una tarea a Done después de la revisión.

• Queue → Design → Build → Review es el bucle del agente. Reclama una tarea, escribe una especificación para salir de Design, produce un worklog y un sha de evidencia para salir de Build.

• Your Call es la rama lateral para cuando un agente necesita una decisión que no debería tomar solo. Mantiene su asignación y su contexto; el humano responde en la tarjeta.

Las compuertas son barandillas para los agentes, no un límite de seguridad — el límite real es el token de API con alcance que Vikunja emite. Ver SECURITY.md.

Related MCP server: Accordo

Por qué

Un agente autónomo que se deja corriendo contra una API de tareas simple se desvía de maneras que son individualmente razonables y colectivamente inútiles: marca su propio trabajo como hecho, comienza lo siguiente antes de terminar esto, "arregla" un error eliminando el test, y el único registro de todo ello es un registro de chat que se desplazó hace tres horas.

Nada de eso se arregla con un prompt más largo. El prompt es un consejo; la llamada a la herramienta es el punto de decisión. Así que el proceso se aplica donde ocurre la decisión:

Lo que obtienes es un tablero donde cada tarjeta lleva su propia historia — la reclamación, el plan, el trabajo, el veredicto independiente — en el orden en que ocurrió.

Cómo se ve en la práctica

Una tarjeta que ha recorrido todo el bucle. Nada aquí fue escrito por un humano: los marcadores, las etiquetas y la etapa son lo que las herramientas escribieron mientras los agentes la movían.

Leyendo de arriba a abajo, eso es claim → advance(to="build", spec=…) → advance(to="review", worklog=…, evidence=…) → el review_task(verdict="approve", report=…) de un agente diferente. La etiqueta reviewed es lo que dejó el veredicto; la tarjeta ahora está en Review esperando que un humano la apruebe. Cada tarea recibe esa revisión, no solo las correcciones de errores — solo un contenedor epic está exento, porque su código vive en sus hijos.

Y cuando el agente se encuentra con una decisión que no le corresponde tomar, estaciona la tarjeta en lugar de adivinar:

La tarjeta conserva su asignado, así que vuelve al mismo agente cuando respondas. Configura VIKUNJA_NOTIFY_WEBHOOK y también recibes un ping con forma de Slack con un enlace profundo, de modo que estacionar una pregunta no significa esperar a que alguien note un tablero.

Inicio rápido

1. Instalar — no se necesita clonar, uvx lo ejecuta directamente desde el repositorio:

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

2. Crear el tablero. Con un token de administrador, esto crea el proyecto si falta y reconcilia las siete columnas canónicas (también migra las columnas Todo/Doing de un tablero Vikunja predeterminado, e imprime fragmentos de configuración listos para confirmar):

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. Apuntar el repositorio a él. Confirma .vikunja-mcp.toml; mantén el token fuera de él:

[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. Registrar el servidor con Claude Code (.mcp.json) o opencode (opencode.json). Ambos se suscriben a la rama stable en movimiento, por lo que los lanzamientos se implementan en el próximo inicio de sesión sin necesidad de actualizaciones por repositorio:

{ "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. Enseñar al agente el proceso — vikunja-mcp install-skill instala la habilidad de tracker empaquetada (disciplina de cola, cuándo escalar, qué debe un worklog a un revisor) tanto para Claude Code como para opencode. Para Claude Code también aprovisiona un hook condicional SessionStart para que dentro de un proyecto configurado con tracker, un /loop simple drene la cola en lugar de recurrir al predeterminado genérico "no empieces a trabajar por tu cuenta". Fuera de ese proyecto, el hook no emite nada.

Luego ejecuta el bucle. /loop 10m para trabajo desatendido, /loop simple cuando estás mirando.

Las doce herramientas

Más allá de las herramientas

Tres comandos completan el bucle; ninguno habla MCP, y el SDK se importa de forma perezosa para que no paguen por ello.

vikunja-mcp claimable — una línea JSON que responde "¿hay trabajo reclamable para este token ahora mismo?", salida 0 si la verificación se ejecutó. Llama al next_task() real, por lo que no puede desviarse de las compuertas, y es de solo lectura por contrato. Diseñado para un supervisor que de otro modo iniciaría una sesión de agente de pago en cada tick de sondeo solo para descubrir que no había nada que hacer.

vikunja-mcp workspace <id> — un worktree de git por tarea en una rama desechable task/<id>, para que varios agentes puedan drenar la cola en paralelo sin pelearse por un único checkout. --release hace push y limpia; --gc recolecta huérfanos y hace fast-forward de tu checkout principal. Su regla de seguridad es una línea: push OK → eliminar, push FAIL → conservar. El trabajo sucio, sin push o inalcanzable se reporta, nunca se destruye. (Una excepción real, documentada en lugar de ocultada: los archivos ignorados por git son invisibles para la comprobación de suciedad. Saca las capturas de pantalla del worktree antes de liberarlo — ver el dossier).

vikunja-mcp setup / install-skill — reconciliación idempotente del tablero, y la instalación de la skill orientada al agente descrita anteriormente. Ambos son seguros de re-ejecutar; el servidor MCP también auto-repara la skill instalada al iniciar, por lo que un stable en movimiento la actualiza automáticamente.

Configuración

Cuatro capas, prioridad más alta primero:

1. Entorno — VIKUNJA_URL, VIKUNJA_TOKEN, VIKUNJA_PROJECT_ID, VIKUNJA_NOTIFY_WEBHOOK

2. .vikunja-mcp.env — archivo KEY=VALUE local al repositorio junto al toml, ignorado por git. El token por proyecto para una máquina que trabaja en varios repos.

3. .vikunja-mcp.toml — commiteado, encontrado subiendo desde el cwd. Seguro de commitear porque no contiene secretos.

4. ~/.config/vikunja-mcp/env — el lugar habitual para un VIKUNJA_TOKEN personal (chmod 600).

Dos reglas hacen que esa división importe, y van en direcciones opuestas:

• Un secreto nunca se lee del toml. Ni el token, ni la URL del webhook. Así que el archivo commiteado no puede filtrar uno ni por accidente.

• La política del equipo nunca se lee del entorno. wip_limit, require_review_independence y language son solo del toml, porque describen cómo funciona el proyecto, no en qué máquina estás. Sin definir, wip_limit es 3 — no "ilimitado"; wip_limit = 0 es un error de configuración, porque "sin límite" deliberadamente no es expresable. Sin definir, language es "en", y un valor no reconocido es un error de configuración por la misma razón.

worktree_root se encuentra en el lado de la máquina de esa línea, así que ahí el entorno gana.

language gobierna más que la salida propia de la herramienta. La especificación, el worklog y el informe de revisión son la mayor parte del texto de una tarjeta y la herramienta no los escribe — el agente lo hace — así que el valor también viaja en cada respuesta de next_task, y el libro de reglas empaquetado le dice al agente que escriba en él. Lo que nunca toca son los marcadores de comentario ([worklog], [review], …): dos de ellos se comparan con startswith para decidir si una tarjeta se ofrece para revisión, por lo que están congelados en todos los idiomas.

Razonamiento completo, incluyendo por qué el límite de WIP controla una transición en lugar de vigilar un recuento: docs/dossier/config.md.

Lanzamientos

Los consumidores se suscriben a la rama stable en movimiento. Cada push verde a main incrementa automáticamente la versión de parche, etiqueta vX.Y.Z, y mueve stable a ella — así una corrección llega a cada repositorio consumidor en su próximo inicio de sesión, sin bots de PR y sin incrementos de versión por repositorio. Las etiquetas inmutables siguen siendo el historial y los puntos de reversión:

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

Los incrementos menores y mayores son un commit editado a mano; CI reanuda el auto-parcheo desde la nueva línea base. docs/dossier/releases.md tiene el análisis de carrera detrás del push atómico y el canal solo hacia adelante.

Desarrollo

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

Las pruebas de integración se ejecutan contra un contenedor Vikunja real y se omiten a sí mismas sin VIKUNJA_TEST_URL — la receta está en CONTRIBUTING.md, junto con las reglas de la casa que son menos obvias de lo que parecen (por qué la longitud de línea es dos números, y por qué un barrido de mutaciones sin una ronda de control no mide nada).

Documentación

docs/ — las reglas viven en CLAUDE.md; la evidencia vive en nueve dossiers, uno por subsistema. Si estás a punto de cambiar una guardia, su dossier es donde está escrita la medición que la puso allí.

Licencia

MIT — ver LICENSE.