Add agent access documentation and MCP usage guide

- Complete guide for accessing terminal web (claude.fuq.tv)
- MCP endpoints usage examples
- Typical workflow from task to PR
- Troubleshooting section
- MCP config template (for future use)

Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>

AGENT-ACCESS.md

@@ -0,0 +1,214 @@
+# Agent Access Guide
+
+## 🌐 Acceso al Terminal Web (Recomendado)
+
+El terminal web con tmux persistente está disponible en:
+
+**https://claude.fuq.tv**
+
+### Características:
+- ✅ Terminal web con ttyd
+- ✅ Sesión tmux persistente (sobrevive recargas de página)
+- ✅ Claude Code ya instalado
+- ✅ 10GB de almacenamiento persistente en `/workspace`
+- ✅ Todas las herramientas: git, bun, node, python3, kubectl
+
+### Cómo usar:
+
+1. **Abre tu navegador** en: https://claude.fuq.tv
+2. Verás un terminal bash
+3. **Primera vez**: Claude Code te pedirá tu API key de Anthropic
+4. **Trabajar**:
+   ```bash
+   cd /workspace
+   git clone https://git.fuq.tv/admin/tu-proyecto.git
+   cd tu-proyecto
+   claude
+   ```
+
+### Persistencia:
+- Tu sesión tmux permanece activa aunque cierres el navegador
+- Puedes reconectar desde cualquier dispositivo
+- El workspace en `/workspace` es persistente (PVC de 10GB)
+
+---
+
+## 🐳 Acceso al Pod del Agente (Alternativa)
+
+Si prefieres acceder directamente al pod en K8s:
+
+```bash
+export KUBECONFIG=~/.kube/aiworker-config
+kubectl exec -it -n agents deployment/claude-agent -- /bin/bash
+```
+
+Dentro del pod:
+```bash
+cd /workspace
+
+# Primera vez: Claude Code pedirá tu API key
+claude
+```
+
+---
+
+## 🔧 Configuración MCP en Claude Code
+
+Los endpoints MCP están disponibles en: **https://api.fuq.tv/api/mcp/**
+
+### Herramientas disponibles:
+
+1. **get_next_task** - Obtener siguiente tarea del backlog
+   ```bash
+   curl -X POST https://api.fuq.tv/api/mcp/get_next_task \
+     -H "Content-Type: application/json" \
+     -d '{"agentId":"'$POD_NAME'"}'
+   ```
+
+2. **update_task_status** - Actualizar estado de tarea
+   ```bash
+   curl -X POST https://api.fuq.tv/api/mcp/update_task_status \
+     -H "Content-Type: application/json" \
+     -d '{"taskId":"task-id","status":"in_progress"}'
+   ```
+
+3. **create_branch** - Crear rama Git
+   ```bash
+   curl -X POST https://api.fuq.tv/api/mcp/create_branch \
+     -H "Content-Type: application/json" \
+     -d '{"taskId":"task-id","branchName":"feature/nueva-funcionalidad"}'
+   ```
+
+4. **create_pull_request** - Crear PR en Gitea
+   ```bash
+   curl -X POST https://api.fuq.tv/api/mcp/create_pull_request \
+     -H "Content-Type: application/json" \
+     -d '{"taskId":"task-id","title":"Add feature","branchName":"feature/nueva-funcionalidad"}'
+   ```
+
+5. **ask_user_question** - Preguntar al usuario
+   ```bash
+   curl -X POST https://api.fuq.tv/api/mcp/ask_user_question \
+     -H "Content-Type: application/json" \
+     -d '{"taskId":"task-id","question":"¿Qué autenticación prefieres: JWT o sessions?"}'
+   ```
+
+### Uso en Claude Code:
+
+Dentro de una sesión de Claude Code, puedes usar estas herramientas:
+
+```bash
+# Ejemplo: Obtener siguiente tarea
+TASK=$(curl -s -X POST https://api.fuq.tv/api/mcp/get_next_task \
+  -H "Content-Type: application/json" \
+  -d "{\"agentId\":\"$POD_NAME\"}")
+
+echo "$TASK" | jq .
+
+# Trabajar en la tarea...
+
+# Actualizar estado cuando termines
+curl -X POST https://api.fuq.tv/api/mcp/update_task_status \
+  -H "Content-Type: application/json" \
+  -d '{"taskId":"task-id","status":"ready_to_test"}'
+```
+
+---
+
+## 🎯 Flujo de Trabajo Típico
+
+1. **Conectar al terminal**: https://claude.fuq.tv
+
+2. **Obtener tarea**:
+   ```bash
+   POD_NAME=$(hostname)
+   curl -s -X POST https://api.fuq.tv/api/mcp/get_next_task \
+     -H "Content-Type: application/json" \
+     -d "{\"agentId\":\"$POD_NAME\"}" | jq .
+   ```
+
+3. **Clonar proyecto**:
+   ```bash
+   cd /workspace
+   git clone https://git.fuq.tv/admin/proyecto.git
+   cd proyecto
+   ```
+
+4. **Crear branch**:
+   ```bash
+   git checkout -b feature/nueva-funcionalidad
+   ```
+
+5. **Trabajar con Claude Code**:
+   ```bash
+   claude
+   # Le explicas la tarea a Claude
+   # Claude hace el trabajo
+   ```
+
+6. **Commit y push**:
+   ```bash
+   git add .
+   git commit -m "Implement nueva funcionalidad"
+   git push origin feature/nueva-funcionalidad
+   ```
+
+7. **Crear PR** (desde Claude o manualmente):
+   ```bash
+   curl -X POST https://api.fuq.tv/api/mcp/create_pull_request \
+     -H "Content-Type: application/json" \
+     -d '{
+       "taskId":"task-id",
+       "title":"Add nueva funcionalidad",
+       "branchName":"feature/nueva-funcionalidad",
+       "description":"Implemented nueva funcionalidad as requested"
+     }'
+   ```
+
+8. **Actualizar estado**:
+   ```bash
+   curl -X POST https://api.fuq.tv/api/mcp/update_task_status \
+     -H "Content-Type: application/json" \
+     -d '{"taskId":"task-id","status":"ready_to_test"}'
+   ```
+
+---
+
+## 🔑 Variables de Entorno Útiles
+
+Dentro del agente, estas variables están disponibles:
+
+```bash
+BACKEND_URL=https://api.fuq.tv
+MCP_ENDPOINT=https://api.fuq.tv/api/mcp
+GITEA_URL=https://git.fuq.tv
+GITEA_TOKEN=159a5de2a16d15f33e388b55b1276e431dbca3f3
+POD_NAME=$(hostname)
+```
+
+---
+
+## 🆘 Troubleshooting
+
+### Terminal no carga
+- Verifica que el pod esté corriendo: `kubectl get pods -n agents`
+- Revisa logs: `kubectl logs -n agents claude-terminal`
+
+### Claude Code pide API key cada vez
+- La API key se guarda en `~/.config/claude/config.json`
+- En tmux persistente, se mantiene entre sesiones
+
+### No puedo hacer git push
+```bash
+# Configura git credentials
+git config --global user.name "Tu Nombre"
+git config --global user.email "tu@email.com"
+
+# Usa el token de Gitea
+git remote set-url origin https://admin:$GITEA_TOKEN@git.fuq.tv/admin/proyecto.git
+```
+
+### Workspace se borró
+- El workspace en `/workspace` del pod claude-terminal es persistente (PVC)
+- El workspace del deployment claude-agent es efímero (emptyDir)
+- **Recomendación**: Usa claude.fuq.tv (terminal web) para trabajo persistente

claude-mcp-config.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "aiworker": {
+      "command": "node",
+      "args": ["-e", "require('child_process').spawn('curl', ['-X', 'POST', process.argv[1], '-H', 'Content-Type: application/json', '-d', JSON.stringify({method: process.argv[2], params: JSON.parse(process.argv[3])})], {stdio: 'inherit'})"],
+      "env": {
+        "MCP_ENDPOINT": "https://api.fuq.tv/api/mcp"
+      }
+    }
+  }
+}