aiworker/docs/05-agents/mcp-tools.md

# MCP Tools - Herramientas Disponibles para Agentes

Esta documentación detalla todas las herramientas MCP que los agentes Claude Code pueden usar para interactuar con el sistema AiWorker.

## get_next_task

Obtiene la siguiente tarea disponible de la cola y la asigna al agente.

**Input**:
```json
{
  "agentId": "uuid-of-agent",
  "capabilities": ["javascript", "react", "python"]  // opcional
}
```

**Output**:
```json
{
  "task": {
    "id": "task-uuid",
    "title": "Implement user authentication",
    "description": "Create a JWT-based authentication system...",
    "priority": "high",
    "project": {
      "id": "project-uuid",
      "name": "My App",
      "giteaRepoUrl": "http://gitea/owner/my-app",
      "dockerImage": "myapp:latest"
    }
  }
}
```

**Ejemplo de uso**:
```typescript
// En Claude Code, el agente puede hacer:
const task = await mcp.callTool('get_next_task', {
  agentId: process.env.AGENT_ID,
  capabilities: ['javascript', 'typescript', 'react']
})
```

---

## update_task_status

Actualiza el estado de una tarea.

**Input**:
```json
{
  "taskId": "task-uuid",
  "status": "in_progress" | "needs_input" | "ready_to_test" | "completed",
  "metadata": {
    "durationMinutes": 45,
    "linesChanged": 250
  }
}
```

**Output**:
```json
{
  "success": true
}
```

**Estados válidos**:
- `in_progress`: Agente trabajando activamente
- `needs_input`: Agente necesita información del usuario
- `ready_to_test`: Tarea completada, lista para testing
- `completed`: Tarea completamente finalizada

---

## ask_user_question

Solicita información al usuario cuando el agente necesita clarificación.

**Input**:
```json
{
  "taskId": "task-uuid",
  "question": "Which authentication library should I use: Passport.js or NextAuth?",
  "context": "The task requires implementing OAuth authentication. I found two popular options..."
}
```

**Output**:
```json
{
  "success": true,
  "message": "Question sent to user",
  "questionId": "question-uuid"
}
```

**Comportamiento**:
1. Cambia el estado de la tarea a `needs_input`
2. Notifica al frontend vía WebSocket
3. Usuario responde desde el dashboard
4. Agente puede hacer polling con `check_question_response`

---

## check_question_response

Verifica si el usuario ha respondido una pregunta.

**Input**:
```json
{
  "taskId": "task-uuid"
}
```

**Output (sin respuesta)**:
```json
{
  "hasResponse": false,
  "message": "No response yet"
}
```

**Output (con respuesta)**:
```json
{
  "hasResponse": true,
  "response": "Use NextAuth, it integrates better with our Next.js stack",
  "question": "Which authentication library should I use..."
}
```

---

## create_branch

Crea una nueva rama en Gitea para la tarea.

**Input**:
```json
{
  "taskId": "task-uuid",
  "branchName": "feature/user-auth"  // opcional, se genera automático
}
```

**Output**:
```json
{
  "success": true,
  "branchName": "task-abc123-implement-user-authentication",
  "repoUrl": "http://gitea/owner/my-app"
}
```

**Comportamiento**:
- Si no se especifica `branchName`, se genera como: `task-{shortId}-{title-slugified}`
- Se crea desde la rama default del proyecto (main/develop)
- Se actualiza el campo `branchName` en la tarea

---

## create_pull_request

Crea un Pull Request en Gitea con los cambios de la tarea.

**Input**:
```json
{
  "taskId": "task-uuid",
  "title": "Implement JWT-based authentication",
  "description": "## Changes\n- Added JWT middleware\n- Created auth routes\n- Added tests\n\n## Test Plan\n- [ ] Test login flow\n- [ ] Test token refresh"
}
```

**Output**:
```json
{
  "success": true,
  "prUrl": "http://gitea/owner/my-app/pulls/42",
  "prNumber": 42
}
```

**Comportamiento**:
- Crea PR desde la rama de la tarea hacia la rama default
- Actualiza campos `prNumber` y `prUrl` en la tarea
- Emite evento WebSocket `task:pr_created`

---

## trigger_preview_deploy

Despliega la tarea en un preview environment aislado en Kubernetes.

**Input**:
```json
{
  "taskId": "task-uuid"
}
```

**Output**:
```json
{
  "success": true,
  "previewUrl": "https://task-abc123.preview.aiworker.dev",
  "namespace": "preview-task-abc123"
}
```

**Comportamiento**:
1. Crea namespace en K8s: `preview-task-{shortId}`
2. Deploya la aplicación con la imagen del proyecto
3. Crea ingress con URL única
4. Actualiza tarea a estado `ready_to_test`
5. Guarda `previewUrl` y `previewNamespace` en la tarea

---

## get_task_details

Obtiene detalles completos de una tarea incluyendo preguntas pendientes.

**Input**:
```json
{
  "taskId": "task-uuid"
}
```

**Output**:
```json
{
  "task": {
    "id": "task-uuid",
    "title": "Implement user authentication",
    "description": "...",
    "state": "needs_input",
    "branchName": "task-abc123-implement-user-authentication",
    "prUrl": "http://gitea/owner/my-app/pulls/42",
    "previewUrl": "https://task-abc123.preview.aiworker.dev",
    "questions": [
      {
        "id": "q-uuid",
        "question": "Which auth library?",
        "status": "pending",
        "askedAt": "2026-01-19T10:00:00Z"
      }
    ],
    "project": {
      "name": "My App",
      "giteaRepoUrl": "..."
    }
  }
}
```

---

## log_activity

Registra actividad del agente en los logs del sistema.

**Input**:
```json
{
  "agentId": "agent-uuid",
  "level": "info" | "debug" | "warn" | "error",
  "message": "Starting task implementation",
  "metadata": {
    "taskId": "task-uuid",
    "operation": "code_generation",
    "filesModified": 5
  }
}
```

**Output**:
```json
{
  "success": true
}
```

**Niveles de log**:
- `debug`: Información detallada de debugging
- `info`: Eventos normales (default)
- `warn`: Situaciones que requieren atención
- `error`: Errores que impidieron completar una operación

---

## heartbeat

Envía señal de vida para indicar que el agente está activo.

**Input**:
```json
{
  "agentId": "agent-uuid",
  "status": "idle" | "busy" | "error"
}
```

**Output**:
```json
{
  "success": true
}
```

**Comportamiento**:
- Actualiza `lastHeartbeat` timestamp
- Actualiza `status` del agente
- Si no se recibe heartbeat por 5 minutos, el agente se marca como `offline`

---

## Flujo Típico de una Tarea

```mermaid
sequenceDiagram
    Agent->>MCP: get_next_task()
    MCP-->>Agent: task details
    Agent->>MCP: create_branch()
    Agent->>Agent: Work on task
    Agent->>?MCP: ask_user_question() (si necesita)
    Agent->>Agent: Wait for response
    Agent->>MCP: check_question_response()
    Agent->>Agent: Continue working
    Agent->>Git: commit & push
    Agent->>MCP: create_pull_request()
    Agent->>MCP: trigger_preview_deploy()
    Agent->>MCP: update_task_status("ready_to_test")
```

## Ejemplo de Uso Completo

```typescript
// Dentro del agente Claude Code
async function processTask() {
  // 1. Get task
  const taskResult = await mcp.callTool('get_next_task', {
    agentId: process.env.AGENT_ID
  })

  const task = JSON.parse(taskResult.content[0].text).task

  if (!task) {
    console.log('No tasks available')
    return
  }

  console.log(`Working on: ${task.title}`)

  // 2. Create branch
  const branchResult = await mcp.callTool('create_branch', {
    taskId: task.id
  })

  const { branchName } = JSON.parse(branchResult.content[0].text)

  // 3. Clone and checkout
  await exec(`git clone ${task.project.giteaRepoUrl} /workspace/task-${task.id}`)
  await exec(`cd /workspace/task-${task.id} && git checkout ${branchName}`)

  // 4. Do the work...
  // (Claude Code generates and commits code)

  // 5. Need clarification?
  if (needsClarification) {
    await mcp.callTool('ask_user_question', {
      taskId: task.id,
      question: 'Should I add error handling for network failures?',
      context: 'The API calls can fail...'
    })

    // Wait for response
    let response
    while (!response) {
      await sleep(5000)
      const checkResult = await mcp.callTool('check_question_response', {
        taskId: task.id
      })
      const check = JSON.parse(checkResult.content[0].text)
      if (check.hasResponse) {
        response = check.response
      }
    }
  }

  // 6. Create PR
  await mcp.callTool('create_pull_request', {
    taskId: task.id,
    title: task.title,
    description: `## Summary\nImplemented ${task.title}\n\n## Changes\n- Feature A\n- Feature B`
  })

  // 7. Deploy preview
  await mcp.callTool('trigger_preview_deploy', {
    taskId: task.id
  })

  // 8. Mark as done
  await mcp.callTool('update_task_status', {
    taskId: task.id,
    status: 'ready_to_test'
  })

  console.log('Task completed!')
}
```

## Error Handling

Todos los tools pueden retornar errores:

```json
{
  "content": [{
    "type": "text",
    "text": "Error: Task not found"
  }],
  "isError": true
}
```

El agente debe manejar estos errores apropiadamente:

```typescript
const result = await mcp.callTool('update_task_status', { ... })

if (result.isError) {
  console.error('Tool failed:', result.content[0].text)
  // Handle error
}
```

## Rate Limiting

Para evitar abuse, los tools tienen rate limits:

- `get_next_task`: 1 por segundo
- `ask_user_question`: 5 por minuto por tarea
- `create_pr`: 1 por minuto
- `trigger_preview_deploy`: 1 por minuto
- Otros: 10 por segundo

Si se excede el rate limit, el tool retorna error 429.