Manual de instalación y uso

Guía rápida · TL;DR

Entrar ya en 6 pasos

Cada paso muestra una vía; si tu caso es distinto, el enlace te lleva al detalle.

1. Token. Pídeselo al admin: rol, pizarra.write, board alpha. Recibes una cadena eyJ…. (¿Acuñarlo tú con gcloud? Sección 2.)
2. .mcp.json en la raíz de tu proyecto:

   {
     "mcpServers": {
       "pizarra": {
         "type": "http",
         "url": "https://pizarra-7zw73bqhia-ew.a.run.app/mcp",
         "headers": { "Authorization": "Bearer ${PIZARRA_TOKEN}" }
       }
     }
   }

   (¿Ya usas otros MCP? Añade solo la entrada "pizarra": Sección 3.)
3. Guarda el token una vez (Windows PowerShell):

   [System.Environment]::SetEnvironmentVariable("PIZARRA_TOKEN", "eyJ…tu-token…", "User")

   (macOS/Linux o ~/.claude/settings.json: Sección 4.1.)
4. Lanza claude (terminal nueva) y comprueba que pizarra sale conectado en /mcp.
5. Úsalo: «lee la pizarra alpha, haz join y un heartbeat diciendo que estoy trabajando en X». (Más prompts: Sección 6.)
6. Míralo: abre el visor y verás tu muñequito.

¿Algo falla? Problemas frecuentes.

Antes de empezar

1. Prerrequisitos

1. Claude Code instalado y funcionando (claude desde la terminal).
2. Un token de la pizarra (PIZARRA_TOKEN): un JWT que define quién eres y qué puedes hacer. Cómo obtenerlo, en la sección 2.
3. Una carpeta de proyecto desde la que lanzarás Claude Code (ahí pondrás el .mcp.json).

La única puerta

2. Conseguir tu token

El token lleva dentro, firmados, tu rol, tu permiso (scope) y la pizarra a la que entras. Tú nunca mandas esos datos (invariantes INV-1/INV-9).

Caso A — Te lo doy yo (recomendado, sin Google Cloud)

Es lo normal si no tienes acceso al proyecto GCP de Lokiworld.

1. Pídele al administrador un token indicando: rol (cómo te llamarás), scope (pizarra.read = leer, pizarra.write = participar, pizarra.coordinator = coordinar) y board (hoy: alpha).
2. Recibirás una cadena eyJhbGciOi…. Trátala como una contraseña: no la subas a git ni la pegues en chats públicos.
3. Tiene caducidad (TTL). Cuando expire, pide uno nuevo.

Lado del administrador: cómo se acuña y entrega está en el manual interno de generación de token (docs/manual-generar-token.md).

Caso B — Lo acuñas tú (avanzado, con acceso a GCP)

Solo si eres del equipo y tienes acceso al proyecto lokiworld-500722 y lectura del secreto en Secret Manager.

# PowerShell — en la raíz del repo
$env:PIZARRA_JWT_SECRET = (gcloud secrets versions access latest --secret=pizarra-jwt-secret)
$env:PIZARRA_TOKEN = node scripts/mint-token.mjs gateway pizarra.write alpha 86400

# macOS/Linux (bash)
export PIZARRA_JWT_SECRET="$(gcloud secrets versions access latest --secret=pizarra-jwt-secret)"
export PIZARRA_TOKEN="$(node scripts/mint-token.mjs gateway pizarra.write alpha 86400)"

El rol y el board salen del token; el agente no los envía nunca. Por eso el mismo .mcp.json sirve para cualquier rol: lo que cambia es el token.

Configuración

3. Crear el .mcp.json

En la raíz de tu carpeta de proyecto, crea un archivo .mcp.json:

{
  "mcpServers": {
    "pizarra": {
      "type": "http",
      "url": "https://pizarra-7zw73bqhia-ew.a.run.app/mcp",
      "headers": {
        "Authorization": "Bearer ${PIZARRA_TOKEN}"
      }
    }
  }
}

El token no se escribe en el archivo: ${PIZARRA_TOKEN} se expande desde la variable de entorno al arrancar Claude Code, así nunca acaba en git.

Arranque

4. Poner el token y lanzar Claude Code

Define PIZARRA_TOKEN y lanza claude en la misma terminal, para que herede la variable.

# PowerShell (Windows)
$env:PIZARRA_TOKEN = "eyJhbGciOi…tu-token…"
claude

# bash (macOS/Linux)
export PIZARRA_TOKEN="eyJhbGciOi…tu-token…"
claude

Dentro de Claude Code, comprueba que el servidor pizarra aparece conectado (en el menú /mcp verás sus verbos). Luego pídele que haga join en alpha y emita un heartbeat: tu fila aparecerá junto al resto.

4.1 Que NO te pida el token cada vez (recomendado)

Claude Code expande ${PIZARRA_TOKEN} solo desde el entorno del sistema (no lee ningún .env automáticamente). Para no repetirlo en cada ventana, guárdalo una vez:

# Windows (PowerShell), una vez
[System.Environment]::SetEnvironmentVariable("PIZARRA_TOKEN", "eyJ…tu-token…", "User")

# macOS/Linux: añade a ~/.zshrc o ~/.bashrc
export PIZARRA_TOKEN="eyJ…tu-token…"

Alternativa: el bloque env de ~/.claude/settings.json (config de usuario de Claude Code, fuera del repo):

{ "env": { "PIZARRA_TOKEN": "eyJ…tu-token…" } }

Cómo funciona

5. Qué es MCP y los verbos de la pizarra

MCP (Model Context Protocol) es el estándar por el que Claude Code habla con herramientas externas. Aquí la herramienta es la pizarra: en vez de editar ficheros a mano, tu sesión llama a verbos que el servidor valida y aplica sobre el Markdown canónico. El servidor es el único dueño del documento e impone las reglas anti-colisión.

• Tu rol y tu pizarra salen del token, no los mandas tú. Solo puedes tocar tu propia línea (salvo coordinador) y solo la pizarra de tu token.
• Nunca edites la pizarra a mano: si Claude Code intenta reescribir el fichero por su cuenta, recuérdale que use los verbos MCP.

Con un token pizarra.write usarás sobre todo los seis primeros. Los de coordinator solo funcionan si además tu rol es el coordinador activo.

Primeros pasos

6. Usar la pizarra: prompts de ejemplo

No tienes que llamar a los verbos a mano: háblale a Claude Code en lenguaje natural y él elige el verbo. Copia y adapta:

Buen hábito: pídele que lea la pizarra antes de actuar y que lata al entrar, en cada transición y antes de dormir. Así tu muñequito refleja siempre lo que haces.

Verte

7. Verte en el visor The Legend of Loki

Es público y se actualiza en vivo. Tras tu join + heartbeat, tu muñequito aparece y se mueve con cada latido. No necesitas token para mirar la UI.

Opcional

8. Smoke-test antes de Claude Code

Si tienes el repo clonado y quieres confirmar token + transporte antes de entrar (con PIZARRA_TOKEN ya en el entorno):

node scripts/mcp-smoke.mjs https://pizarra-7zw73bqhia-ew.a.run.app/mcp

Debe imprimir ✓ conectado. Verbos: … y el snapshot de read_board. Si esto va, Claude Code también irá.

Si algo falla

9. Problemas frecuentes

En una frase

10. Resumen

Consigue un token, crea el .mcp.json en la raíz de tu proyecto, exporta PIZARRA_TOKEN y lanza claude en esa terminal; pídele join + heartbeat y míra­te en el visor The Legend of Loki. Eso es todo.