# FASE 2 - MCP TOOLS DESIGN DOCUMENT

**Fecha:** 2026-01-20
**Version:** 1.0.0
**Estado:** Diseno completo - Listo para implementacion

---

## RESUMEN EJECUTIVO

La Fase 2 amplia el MVP con **4 herramientas MCP especializadas**:

1. **classify** - Clasificar texto en categorias
2. **extract** - Extraer datos estructurados
3. **summarize** - Resumir texto
4. **rewrite** - Reescribir con estilo especifico

**Duracion estimada:** 3 semanas

---

## ARQUITECTURA

```
AGENTES (Claude, Gemini, Trae)
         |
    POST /mcp/tools/:name
         v
+---------------------------+
|    GATEWAY (3160)         |
|  +---------------------+  |
|  | MCP Tools Module    |  |
|  | - ToolsRegistry     |  |
|  | - ToolExecutor      |  |
|  | - ResponseParser    |  |
|  +----------+----------+  |
|             |             |
|  +----------v----------+  |
|  | Router + RateLimiter|  |
|  +----------+----------+  |
+-------------|-------------+
              v
+---------------------------+
|  INFERENCE ENGINE (3161)  |
|  - Chat Completions       |
|  - Backend Manager        |
+-------------|-------------+
              v
+---------------------------+
|      OLLAMA (11434)       |
|  - tinyllama / gpt-oss    |
+---------------------------+
```

---

## HERRAMIENTAS MCP

### 1. CLASSIFY

**Input:**
```json
{
  "text": "El mercado subio 2%",
  "categories": ["finanzas", "tecnologia", "deporte"],
  "context": "Noticias latinoamericanas"
}
```

**Output:**
```json
{
  "category": "finanzas",
  "confidence": 0.95,
  "reasoning": "Menciona mercado y porcentaje",
  "latency_ms": 450,
  "tier_used": "small"
}
```

### 2. EXTRACT

**Input:**
```json
{
  "text": "Juan Garcia, email: juan@ejemplo.com, tel: 555-1234",
  "schema": {
    "nombre": {"type": "string"},
    "email": {"type": "string"},
    "telefono": {"type": "string"}
  }
}
```

**Output:**
```json
{
  "data": {
    "nombre": "Juan Garcia",
    "email": "juan@ejemplo.com",
    "telefono": "555-1234"
  },
  "missing_fields": [],
  "confidence": 0.98
}
```

### 3. SUMMARIZE

**Input:**
```json
{
  "text": "[texto largo...]",
  "max_length": 100,
  "format": "bullets",
  "style": "formal"
}
```

**Output:**
```json
{
  "summary": "- Punto 1\n- Punto 2\n- Punto 3",
  "original_word_count": 500,
  "summary_word_count": 45,
  "compression_ratio": 0.09
}
```

### 4. REWRITE

**Input:**
```json
{
  "text": "El sistema fallo por un error critico",
  "style": "formal",
  "audience": "executive"
}
```

**Output:**
```json
{
  "rewritten": "Se presento una incidencia que requirio atencion inmediata",
  "tone_shift": "casual -> formal"
}
```

---

## PLAN DE IMPLEMENTACION

### Semana 1: Foundation
- F2-1A: ToolsRegistry + DTOs (1 dia)
- F2-1B: PromptBuilder + ResponseParser (1 dia)
- F2-1C: ToolExecutor base (0.5 dias)
- F2-1D: RateLimiter (0.5 dias)

### Semana 2: Tools
- F2-2A: Classify tool (1 dia)
- F2-2B: Extract tool (1.5 dias)
- F2-2C: Summarize tool (1 dia)
- F2-2D: Rewrite tool (1.5 dias)

### Semana 3: Polish
- F2-3A: Integration testing (2 dias)
- F2-3B: Router mejorado (1 dia)
- F2-3C: Documentacion (1.5 dias)
- F2-3D: Optimization (0.5 dias)

---

## RATE LIMITING

```typescript
perIp: {
  small: { requestsPerMinute: 60, tokensPerMinute: 30000 },
  main: { requestsPerMinute: 20, tokensPerMinute: 100000 }
}
```

---

## ARCHIVOS A CREAR

```
apps/gateway/src/mcp-tools/
├── mcp-tools.module.ts
├── mcp-tools.service.ts (modificar)
├── tools-registry.ts (NEW)
├── tools/
│   ├── classify.tool.ts (NEW)
│   ├── extract.tool.ts (NEW)
│   ├── summarize.tool.ts (NEW)
│   └── rewrite.tool.ts (NEW)
├── dto/
│   ├── tool-response.dto.ts (NEW)
│   └── tool-errors.dto.ts (NEW)
└── utils/
    ├── prompt-builder.ts (NEW)
    ├── response-parser.ts (NEW)
    └── cost-estimator.ts (NEW)
```

---

## DEPENDENCIAS

- Fase 1 MVP: MUST BE 100% complete
- Inference Engine gaps P0: MUST BE fixed
- Docker setup: OK (ya probado)

---

## RIESGOS

| Riesgo | Probabilidad | Mitigacion |
|--------|--------------|------------|
| Latencia Ollama | Media | Small tier + prompts optimizados |
| JSON parsing fails | Media | ResponseParser con fallbacks |
| Rate limiting insuficiente | Baja | Token-based + global limits |

---

## REFERENCIAS

- RF-MCP-001 a RF-MCP-004 (Requerimientos Funcionales)
- INVENTARIO.yml (fase_2_multi_tool)
- apps/gateway/src/mcp/ (codigo existente scaffold)