kanban/docs/INSTALL_CLAUDE_MCP.md

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