Add agent access documentation and MCP usage guide
All checks were successful
Build and Push Agent / build (push) Successful in 4s
All checks were successful
Build and Push Agent / build (push) Successful in 4s
- 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>
This commit is contained in:
Hector Ros
214
AGENT-ACCESS.md
Normal file
214
AGENT-ACCESS.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user