intelliboard-mcp

MCP server do Kanban do Intelliboard. Pluga no Claude Code, opencode ou qualquer cliente MCP e deixa o agente criar cards estruturados, ler o board, mover/ atualizar cards e marcar como concluído — com validação imposta antes de concluir.

Zero variável de ambiente. Auth por device flow, tudo pelo chat do agente; config por arquivo no repo.

Instalar

Registre o servidor no seu agente — um comando:

# Claude Code
claude mcp add intelliboard -- npx -y intelliboard-mcp

# Codex
codex mcp add intelliboard -- npx -y intelliboard-mcp

# opencode (prompt interativo → Type: Local · Command: npx -y intelliboard-mcp)
opencode mcp add

Aponta pra https://intelliboard.aglissilva.dev por padrão. Local/self-host: veja apiUrl abaixo.

Autenticar (pelo chat)

Sem terminal. No agente:

1. Peça: "conecte o Intelliboard" → o agente chama a tool login e devolve uma URL + código.
2. Abra a URL (página /device), aprove o dispositivo. É o único passo humano.
3. O agente chama intelliboard_status e confirma (authenticated: true).

O token fica em ~/.config/intelliboard/credentials.json (modo 0600), dura ~7 dias; refaça login quando expirar. (Alternativa CLI: npx intelliboard-mcp login.)

Configurar o projeto (opcional)

Só precisa de intelliboard.config.json para self-host (apiUrl) ou para o gate de conclusão (validate). Crie na raiz do repositório onde o agente roda:

{
  "apiUrl": "http://localhost:3333",
  "validate": "bash scripts/validate.sh"
}

• apiUrl — backend do Intelliboard (default https://intelliboard.aglissilva.dev).
• validate — comando que prova que a implementação está OK (build/types/test). complete_card roda isto e bloqueia a conclusão se falhar.

Tools

| Tool | O que faz | |---|---| | login / intelliboard_status | Autentica (device flow) e checa a conexão — tudo pelo chat. | | list_columns | Colunas do board (com role). Filtros: summaryOnly (só contagem), sprintId, epic, limit (por coluna), columns — use-os p/ não estourar o contexto em board grande. | | create_column / delete_column | Cria / remove coluna (role opcional). | | create_card | Cria card estruturado (leia o código antes; markdown com causa raiz, repro, critérios). Título com prefixo [tipo]. Opcional: sprintId, epic, dependsOn. | | create_cards_bulk | Cria vários cards de uma vez (tudo-ou-nada) — planeja uma sprint numa chamada; exige prefixo [tipo] em cada título. | | update_card / move_card / delete_card | Edita / move / remove card. update_card também move entre sprints (sprintId) e define dependsOn/epic. | | validate | Roda a validação (config.validate) sem mexer em card. | | complete_card | Roda a validação e bloqueia se falhar; só então move para done. Aceita campos estruturados: epic, changedFiles, validationCommands, residualRisks, knownLimitations, securityNotes, followUpCards. | | get_next_task | Pega o próximo card desbloqueado de todo (pula os com dependsOn não-done), trava por assignee e move para doing. | | list_my_cards | Cards atribuídos a você. | | list_sprints / create_sprint / update_sprint / activate_sprint | Gerencia sprints. activate_sprint suporta dryRun (mostra o diff) e force (encerrar sprint com cards abertos). | | get_project_context / log_decision | Lê o briefing do projeto; registra decisão arquitetural no log do board. |

As colunas todo/doing/done vêm do backend (board-config) pelo role da coluna (definido na UI) — com fallback por nome. Sem env de coluna.

Validação imposta

complete_card executa config.validate num shell. Saída ≠ 0 → o card não é concluído (continua em doing), com a saída do erro. Impede que qualquer agente marque cards como prontos sem validar. Sem validate no config, a conclusão fica bloqueada (fail-closed).

Fluxo

1. Criar card: o agente lê o código, entende a causa, e chama create_card.
2. Executar: "pega o próximo card e implementa" → get_next_task → implementa → complete_card (valida) → repete até acabar.

Dev

bun install
bun run dev        # roda do source (stdio)
bun run build      # compila para dist/ (Node, publicável no npm)

Runtime alvo: Node ≥ 18 (roda via npx/bunx). Publicação: npm publish (ou bun publish — ambos vão para o registro npm).