Complete documentation for future sessions
- CLAUDE.md for AI agents to understand the codebase - GITEA-GUIDE.md centralizes all Gitea operations (API, Registry, Auth) - DEVELOPMENT-WORKFLOW.md explains complete dev process - ROADMAP.md, NEXT-SESSION.md for planning - QUICK-REFERENCE.md, TROUBLESHOOTING.md for daily use - 40+ detailed docs in /docs folder - Backend as submodule from Gitea Everything documented for autonomous operation. Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Hector Ros
452
docs/05-agents/mcp-tools.md
Normal file
452
docs/05-agents/mcp-tools.md
Normal file
@@ -0,0 +1,452 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user