From 924bf2244de1a53e701ec528e348909a6ea82374 Mon Sep 17 00:00:00 2001 From: Hector Ros Date: Tue, 20 Jan 2026 02:11:06 +0100 Subject: [PATCH] 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) --- AGENT-ACCESS.md | 214 +++++++++++++++++++++++++++++++++++++++++ claude-mcp-config.json | 11 +++ 2 files changed, 225 insertions(+) create mode 100644 AGENT-ACCESS.md create mode 100644 claude-mcp-config.json diff --git a/AGENT-ACCESS.md b/AGENT-ACCESS.md new file mode 100644 index 0000000..cd7760f --- /dev/null +++ b/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 diff --git a/claude-mcp-config.json b/claude-mcp-config.json new file mode 100644 index 0000000..40e88eb --- /dev/null +++ b/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" + } + } + } +}