chore: auto-commit (12 archivos)

- app.md - backend/handlers.go - backend/main.go - frontend/src/App.tsx - frontend/src/api.ts - frontend/vite.config.ts - backend/mcp_http.go - backend/mcp_tokens.go - backend/mcp_tokens_handlers.go - backend/migrations/016_mcp_tokens.sql - ... Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-22 14:38:17 +02:00
parent c9e15513c7
commit c28ae7d3c0
13 changed files with 771 additions and 4 deletions
@@ -0,0 +1,132 @@
+# Prompt para instalar el MCP del kanban en Claude Code
+
+Este documento esta escrito **para Claude**, no para un humano. Pegalo en tu sesion de Claude Code junto con tu URL y tu token, y Claude registrara el MCP server `kanban` por ti, verificara la conexion y te dira como invocarlo.
+
+---
+
+## Contexto
+
+El kanban (https://github.com/... — repo interno) expone un endpoint **MCP Streamable HTTP** en `/mcp` con autenticacion Bearer por usuario. Cada usuario genera su propio token en la UI ("avatar menu → MCP tokens → Generar"). El token cifrado no se recupera: si se pierde, hay que generar otro y revocar el anterior.
+
+El MCP server expone 14 tools para gestionar el board:
+
+| Tool | Que hace |
+|---|---|
+| `list_board` | Lista columnas y tarjetas |
+| `find_cards` | Busca por texto/columna/solicitante |
+| `create_card` / `update_card` / `delete_card` | CRUD de tarjetas |
+| `move_card` | Mueve tarjeta a otra columna |
+| `assign_card` | Asigna o desasigna usuario |
+| `card_history` | Cambios historicos de una tarjeta |
+| `create_column` / `update_column` / `rename_column` / `delete_column` / `reorder_columns` | Admin de columnas |
+| `list_users` | Lista usuarios disponibles |
+
+---
+
+## Datos que necesitas pedir al usuario (o que recibes con el prompt)
+
+- `MCP_URL`: URL completa del endpoint, por ejemplo `http://192.168.1.50:5180/mcp`. Suele ser el mismo host:puerto donde el usuario abre el kanban en el navegador + sufijo `/mcp`.
+- `MCP_TOKEN`: token que empieza por `kmcp_` seguido de 64 caracteres hex. El usuario lo copio del modal "MCP tokens".
+
+Si el usuario no te ha dado uno o ambos, pidelo antes de continuar. NO inventes valores ni uses placeholders.
+
+---
+
+## Pasos que tienes que ejecutar
+
+### 1. Comprobar prerequisitos
+
+```bash
+claude --version
+claude mcp list 2>&1 | head
+```
+
+Si `claude` no esta en el PATH, indica al usuario que instale Claude Code antes de continuar (no intentes instalarlo tu).
+
+### 2. Registrar el MCP server
+
+```bash
+claude mcp add kanban \
+  --transport http \
+  --header "Authorization: Bearer ${MCP_TOKEN}" \
+  -- ${MCP_URL}
+```
+
+Notas:
+
+- Si ya existe un MCP `kanban` previo, primero `claude mcp remove kanban` y luego registra el nuevo. NO intentes editarlo en place.
+- Si el comando devuelve error sobre `--transport`, comprueba que la version de Claude Code soporta MCP HTTP (>= 2.0.0). En versiones antiguas usa `mcp-remote` como bridge:
+  ```bash
+  claude mcp add kanban -- npx -y mcp-remote "${MCP_URL}" --header "Authorization: Bearer ${MCP_TOKEN}"
+  ```
+
+### 3. Verificar conexion
+
+```bash
+claude mcp list
+```
+
+Tiene que aparecer una linea como:
+
+```
+kanban  http  ✓ connected
+```
+
+Si aparece `✗ failed` o un error de conexion, comprueba:
+
+- Que el host del kanban es accesible desde esta maquina (`curl -s -o /dev/null -w '%{http_code}\n' ${MCP_URL}` debe devolver `405` — es POST-only).
+- Que el token no caduco ni fue revocado.
+- Que la URL termina exactamente en `/mcp` (sin barra final).
+
+### 4. Probar una llamada real
+
+```bash
+claude -p "Usa la tool mcp__kanban__list_board y dime cuantas columnas tiene mi tablero y cuantas tarjetas hay en total." \
+  --allowed-tools mcp__kanban__list_board
+```
+
+Output esperado: un resumen en lenguaje natural con el numero de columnas y tarjetas. Si Claude responde "no tengo acceso a esa tool" o "MCP no esta configurado", vuelve al paso 2.
+
+### 5. Resumir al usuario
+
+Cuando termines, dile al usuario:
+
+- Si la conexion esta OK y el smoke test paso.
+- Que tools tiene disponibles.
+- Como invocarlas en futuras sesiones (por ejemplo: "crea una tarjeta para revisar el reporte mensual" o "muevela a la columna Doing").
+- Como revocar el token si pierde el control de esta maquina.
+
+---
+
+## Errores frecuentes
+
+| Sintoma | Causa probable | Accion |
+|---|---|---|
+| `claude mcp add` no acepta `--transport http` | Version vieja de Claude Code | Usar `mcp-remote` (ver paso 2). |
+| `connection refused` | El kanban no esta corriendo o el puerto cambio | Confirmar con el usuario que abre el kanban en el navegador. |
+| `401 unauthorized` | Token mal copiado o revocado | Generar nuevo token en la UI, repetir paso 2. |
+| `405 Method Not Allowed` en smoke test | URL apuntando a un GET en vez de POST | El endpoint es POST-only; el flujo de `claude mcp` lo gestiona, pero un `curl` manual con GET fallara. |
+| Tools no aparecen tras instalar | Sesion de Claude Code cacheo la config vieja | Cierra y vuelve a abrir Claude Code. |
+
+---
+
+## Que NO hacer
+
+- No escribas el token en plain text en ningun archivo del repositorio del usuario, ni en logs, ni en commits, ni en mensajes que persistan.
+- No intentes "probar" el token llamando al endpoint con `curl` y pegandolo visible — solo usa el comando `claude mcp add`.
+- No modifiques `~/.claude.json` a mano; usa siempre `claude mcp add/remove`.
+- No expongas el endpoint `/mcp` a redes mas amplias que las del usuario sin consultarle.
+- No crees, modifiques ni borres tarjetas durante el smoke test salvo que el usuario lo pida explicitamente. Usa solo `list_board` para validar.
+
+---
+
+## Si algo no esta claro
+
+Pidele al usuario:
+
+- El URL exacto que abre en el navegador para usar el kanban (sin `/mcp`; lo añades tu).
+- El token recien generado (NO uno viejo).
+- La version de Claude Code (`claude --version`).
+- El SO en el que esta (`uname -a` o, en Windows, `ver`).
+
+Con eso puedes terminar la instalacion en menos de un minuto.
@@ -0,0 +1,79 @@
+# Conectar Claude al kanban via MCP
+
+El kanban expone un endpoint **MCP HTTP** (`/mcp`) que permite a un cliente Claude leer y modificar el tablero de cada usuario.
+
+## Cuando usarlo
+
+- Pedir a Claude que cree, actualice, mueva o busque tarjetas desde tu terminal local sin abrir el navegador.
+- Listar el board en lenguaje natural.
+- Asignar tarjetas, consultar historial, etc.
+
+## Configuracion (una vez por PC)
+
+### 1. Generar token en el kanban
+
+1. Abre el kanban en el navegador (mismo URL que usas normalmente, por ejemplo `http://<host-windows>:5180`).
+2. Click en tu avatar (esquina superior derecha) → **MCP tokens**.
+3. Pulsa **Generar**, dale un nombre descriptivo (por ejemplo `portatil-trabajo`).
+4. **Copia el token inmediatamente** — solo se muestra una vez. Tambien tendras el comando `claude mcp add` listo para pegar.
+
+### 2. Registrar el MCP en Claude Code
+
+En el PC desde el que vas a usar Claude:
+
+```bash
+claude mcp add kanban --transport http http://<host-windows>:5180/mcp \
+  --header "Authorization: Bearer kmcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+```
+
+Reemplaza `<host-windows>` por la IP o nombre del PC Windows que sirve el kanban en la LAN, y el token por el valor que copiaste.
+
+Verifica con:
+
+```bash
+claude mcp list
+```
+
+Tienes que ver `kanban` con estado **connected**.
+
+## Tools disponibles
+
+Una vez conectado, Claude puede invocar:
+
+| Tool | Que hace |
+|---|---|
+| `list_board` | Devuelve columnas y tarjetas del tablero |
+| `create_column` | Crea una columna nueva |
+| `update_column` | Modifica nombre, ancho, WIP, ubicacion, terminal |
+| `rename_column` | Alias rapido de `update_column` con `{id, name}` |
+| `delete_column` | Borra una columna (cards a papelera) |
+| `reorder_columns` | Reordena columnas |
+| `create_card` | Crea tarjeta en una columna |
+| `update_card` | Edita titulo, descripcion, color, lock, asignado |
+| `delete_card` | Envia tarjeta a papelera |
+| `move_card` | Mueve tarjeta a otra columna |
+| `card_history` | Historial de cambios de una tarjeta |
+| `find_cards` | Busca por texto/columna/solicitante |
+| `list_users` | Usuarios disponibles para asignar |
+| `assign_card` | Asigna o desasigna usuario |
+
+## Revocar acceso
+
+Si pierdes el PC o quieres rotar el token, vuelve al modal **MCP tokens** y pulsa el icono de papelera en la fila correspondiente. El cliente Claude perdera acceso al instante.
+
+## Limitaciones actuales
+
+- Las acciones por MCP no registran `actor_id` en el historial — quedan como anonimas. (Mejora pendiente.)
+- No hay rate limiting por token; revoca si detectas mal uso.
+- El endpoint NO soporta SSE server→client (solicitudes Claude→kanban funcionan, sin streaming inverso).
+- Solo POST `/mcp` esta soportado; GET y DELETE devuelven 405.
+- Body limit 1 MiB.
+
+## Troubleshooting
+
+| Sintoma | Probable causa |
+|---|---|
+| `claude mcp list` muestra error de conexion | Vite (puerto 5180) o backend (8095) parados. Lanza el `control.sh` del kanban. |
+| `401 unauthorized` | Token mal pegado, revocado, o caducado. Genera uno nuevo. |
+| `405 Method Not Allowed` | Estas haciendo GET; el MCP solo acepta POST. |
+| Tools listan pero `list_board` falla | Backend devuelve error real — mira `kanban.log` en WSL. |