local-llm-agent/docs/60-plan-desarrollo/FASE-2-MCP-TOOLS-DESIGN.md

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:

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

Output:

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

2. EXTRACT

Input:

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

Output:

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

3. SUMMARIZE

Input:

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

Output:

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

4. REWRITE

Input:

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

Output:

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

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)