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:

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

Output:

{
  "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:

// 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:

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

Output:

{
  "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:

{
  "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:

{
  "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:

{
  "taskId": "task-uuid"
}

Output (sin respuesta):

{
  "hasResponse": false,
  "message": "No response yet"
}

Output (con respuesta):

{
  "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:

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

Output:

{
  "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:

{
  "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:

{
  "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:

{
  "taskId": "task-uuid"
}

Output:

{
  "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:

{
  "taskId": "task-uuid"
}

Output:

{
  "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:

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

Output:

{
  "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:

{
  "agentId": "agent-uuid",
  "status": "idle" | "busy" | "error"
}

Output:

{
  "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

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

// 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:

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

El agente debe manejar estos errores apropiadamente:

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.