michangarrito/docs/01-epicas/MCH-010-mcp-server.md

---
id: EPIC-MCH-010
type: Epic
title: "MCH-010: MCP Server"
code: MCH-010
status: Pendiente
status_real: Pendiente
status_nota: "Submodulo mcp-server/ no inicializado - BLOQUEANTE para MCH-012, MCH-013"
phase: 3
priority: P0
created_at: 2026-01-10
updated_at: 2026-01-17
simco_version: "4.0.1"
story_points: 21
dependencies:
  blocks: ["MCH-012", "MCH-013"]
  depends_on: ["MCH-001", "MCH-002", "MCH-003", "MCH-004"]
---

# MCH-010: MCP Server

## Metadata
- **Codigo:** MCH-010
- **Fase:** 3 - Asistente IA
- **Prioridad:** P0 (BLOQUEANTE)
- **Estado:** Pendiente
- **Estado Real:** Submodulo vacío - NO IMPLEMENTADO
- **Story Points:** 21
- **Sprint Asignado:** Sprint 1 (Desbloqueo Crítico)

## Descripcion

Gateway LLM agnostico usando el protocolo MCP (Model Context Protocol) de Anthropic. Permite conectar multiples proveedores de LLM (Claude, GPT-4, Llama) con tools especificos para el negocio.

## Objetivos

1. Gateway LLM agnostico (OpenRouter)
2. Tools MCP para operaciones del negocio
3. Contexto por tenant (productos, ventas)
4. Rate limiting por tokens
5. Logging de conversaciones

## Alcance

### Incluido
- MCP Server con TypeScript
- Tools para: productos, ventas, inventario, clientes
- Routing a multiples LLMs via OpenRouter
- Contexto del negocio en prompts
- Control de consumo de tokens

### Excluido
- Entrenamiento de modelos propios
- Fine-tuning
- Vision/imagenes (fase posterior)

## Arquitectura

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Mobile    │     │  WhatsApp   │     │    Web      │
│    App      │     │   Service   │     │  Dashboard  │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
                    ┌──────▼──────┐
                    │  MCP Server │
                    │  (Gateway)  │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
       ┌──────▼──────┐ ┌───▼───┐ ┌─────▼─────┐
       │  OpenRouter │ │ Claude│ │   GPT-4   │
       │  (Default)  │ │  API  │ │    API    │
       └─────────────┘ └───────┘ └───────────┘
```

## Tools MCP

### Products
```typescript
{
  name: "search_products",
  description: "Buscar productos en el catalogo",
  parameters: {
    query: string,
    category?: string
  }
}

{
  name: "get_product_stock",
  description: "Obtener stock de un producto",
  parameters: {
    product_id: string
  }
}

{
  name: "update_product_price",
  description: "Actualizar precio de producto",
  parameters: {
    product_id: string,
    new_price: number
  }
}
```

### Sales
```typescript
{
  name: "get_daily_sales",
  description: "Obtener ventas del dia",
  parameters: {
    date?: string
  }
}

{
  name: "get_sales_report",
  description: "Reporte de ventas por periodo",
  parameters: {
    start_date: string,
    end_date: string
  }
}
```

### Inventory
```typescript
{
  name: "get_low_stock_products",
  description: "Productos con stock bajo",
  parameters: {}
}

{
  name: "get_inventory_value",
  description: "Valor total del inventario",
  parameters: {}
}
```

### Customers
```typescript
{
  name: "search_customers",
  description: "Buscar clientes",
  parameters: {
    query: string
  }
}

{
  name: "get_customer_balance",
  description: "Saldo de fiado de cliente",
  parameters: {
    customer_id: string
  }
}
```

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /mcp/chat | Enviar mensaje al LLM |
| GET | /mcp/tools | Listar tools disponibles |
| GET | /mcp/history | Historial de conversacion |
| POST | /mcp/feedback | Feedback de respuesta |

## Modelo de Datos

### Tablas (schema: ai)

**conversations**
- id, tenant_id, user_id, channel
- started_at, last_message_at

**messages**
- id, conversation_id, role, content
- tokens_used, model, created_at

**tool_calls**
- id, message_id, tool_name
- parameters, result, duration_ms

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| MCP Server base | En progreso | `apps/mcp-server/` |
| Tools products | Pendiente | `tools/products.tool.ts` |
| Tools sales | Pendiente | `tools/sales.tool.ts` |
| Tools inventory | Pendiente | `tools/inventory.tool.ts` |
| OpenRouter client | En progreso | `clients/openrouter.ts` |

## Dependencias

### Depende de
- MCH-001 (Infraestructura)
- MCH-002 (Auth) - para context del tenant
- MCH-003 (Productos) - para tools
- MCH-004 (Sales) - para tools

### Bloquea a
- MCH-011 (WhatsApp usa MCP)
- MCH-012 (Chat dueno)
- MCH-013 (Chat cliente)

## Criterios de Aceptacion

- [x] MCP Server responde correctamente
- [x] Tools ejecutan operaciones reales
- [x] Contexto del tenant se incluye
- [x] Rate limiting por tokens funciona
- [x] Logs de conversacion completos

## Configuracion

```typescript
// config/mcp.config.ts
{
  defaultProvider: 'openrouter',
  providers: {
    openrouter: {
      apiKey: process.env.OPENROUTER_API_KEY,
      defaultModel: 'anthropic/claude-3-haiku'
    },
    anthropic: {
      apiKey: process.env.ANTHROPIC_API_KEY
    }
  },
  maxTokensPerRequest: 4000,
  maxTokensPerDay: 50000
}
```

## Puerto

- **MCP Server:** 3142

---

## Historias de Usuario

### MCH-US-090: Gateway LLM Agnostico
**Story Points:** 5

**Como** sistema
**Quiero** conectar multiples proveedores LLM a traves de un gateway unificado
**Para** tener flexibilidad en la eleccion de modelos y evitar vendor lock-in

#### Criterios de Aceptacion
- [CA-090-1] El gateway soporta OpenRouter como proveedor por defecto
- [CA-090-2] El gateway permite configurar Claude API directo como alternativa
- [CA-090-3] El gateway permite configurar GPT-4 API como alternativa
- [CA-090-4] El cambio de proveedor no afecta la interfaz de los clientes
- [CA-090-5] La configuracion de proveedores es por variables de entorno

#### Tareas
| ID | Tarea | SP | Estado |
|----|-------|-----|--------|
| MCH-TT-090-01 | Implementar cliente OpenRouter | 2 | Completado |
| MCH-TT-090-02 | Implementar cliente Anthropic | 1 | Completado |
| MCH-TT-090-03 | Implementar router de proveedores | 1 | Completado |
| MCH-TT-090-04 | Configuracion por entorno | 1 | Completado |

---

### MCH-US-091: Tools de Productos
**Story Points:** 3

**Como** LLM
**Quiero** buscar y actualizar productos del negocio
**Para** responder consultas sobre catalogo y modificar precios cuando se solicite

#### Criterios de Aceptacion
- [CA-091-1] Tool search_products busca por nombre y categoria
- [CA-091-2] Tool get_product_stock retorna stock actual del producto
- [CA-091-3] Tool update_product_price actualiza precio con validacion
- [CA-091-4] Todos los tools validan tenant_id del contexto

#### Tareas
| ID | Tarea | SP | Estado |
|----|-------|-----|--------|
| MCH-TT-091-01 | Implementar search_products tool | 1 | Completado |
| MCH-TT-091-02 | Implementar get_product_stock tool | 1 | Completado |
| MCH-TT-091-03 | Implementar update_product_price tool | 1 | Completado |

---

### MCH-US-092: Tools de Ventas
**Story Points:** 3

**Como** LLM
**Quiero** consultar ventas y generar reportes
**Para** proporcionar informacion financiera al dueno del negocio

#### Criterios de Aceptacion
- [CA-092-1] Tool get_daily_sales retorna ventas del dia o fecha especificada
- [CA-092-2] Tool get_sales_report genera reporte por rango de fechas
- [CA-092-3] Los reportes incluyen totales, conteos y desglose
- [CA-092-4] Los datos respetan el tenant_id del contexto

#### Tareas
| ID | Tarea | SP | Estado |
|----|-------|-----|--------|
| MCH-TT-092-01 | Implementar get_daily_sales tool | 1 | Completado |
| MCH-TT-092-02 | Implementar get_sales_report tool | 2 | Completado |

---

### MCH-US-093: Tools de Inventario
**Story Points:** 2

**Como** LLM
**Quiero** consultar stock y alertas de inventario
**Para** informar al dueno sobre productos que necesitan reabastecimiento

#### Criterios de Aceptacion
- [CA-093-1] Tool get_low_stock_products lista productos bajo minimo
- [CA-093-2] Tool get_inventory_value calcula valor total del inventario
- [CA-093-3] Los resultados respetan el tenant_id del contexto

#### Tareas
| ID | Tarea | SP | Estado |
|----|-------|-----|--------|
| MCH-TT-093-01 | Implementar get_low_stock_products tool | 1 | Completado |
| MCH-TT-093-02 | Implementar get_inventory_value tool | 1 | Completado |

---

### MCH-US-094: Tools de Clientes
**Story Points:** 2

**Como** LLM
**Quiero** buscar clientes y consultar fiados
**Para** gestionar la relacion con clientes y sus deudas

#### Criterios de Aceptacion
- [CA-094-1] Tool search_customers busca por nombre o telefono
- [CA-094-2] Tool get_customer_balance retorna saldo de fiado
- [CA-094-3] Los datos respetan el tenant_id del contexto

#### Tareas
| ID | Tarea | SP | Estado |
|----|-------|-----|--------|
| MCH-TT-094-01 | Implementar search_customers tool | 1 | Completado |
| MCH-TT-094-02 | Implementar get_customer_balance tool | 1 | Completado |

---

### MCH-US-095: Rate Limiting de Tokens
**Story Points:** 3

**Como** sistema
**Quiero** controlar el consumo de tokens por tenant
**Para** evitar costos excesivos y garantizar uso justo

#### Criterios de Aceptacion
- [CA-095-1] Limite de 4000 tokens por request
- [CA-095-2] Limite de 50000 tokens por dia por tenant
- [CA-095-3] El sistema rechaza requests que excedan limites
- [CA-095-4] Los contadores se reinician cada 24 horas

#### Tareas
| ID | Tarea | SP | Estado |
|----|-------|-----|--------|
| MCH-TT-095-01 | Implementar contador de tokens por request | 1 | Completado |
| MCH-TT-095-02 | Implementar limite diario por tenant | 1 | Completado |
| MCH-TT-095-03 | Implementar middleware de validacion | 1 | Completado |

---

### MCH-US-096: Logging de Conversaciones
**Story Points:** 3

**Como** sistema
**Quiero** registrar todas las conversaciones con el LLM
**Para** auditoria, debugging y mejora continua del asistente

#### Criterios de Aceptacion
- [CA-096-1] Se registra cada conversacion con tenant_id, user_id y channel
- [CA-096-2] Se registra cada mensaje con rol, contenido, tokens y modelo
- [CA-096-3] Se registran tool_calls con parametros, resultado y duracion
- [CA-096-4] Los logs son consultables via endpoint /mcp/history

#### Tareas
| ID | Tarea | SP | Estado |
|----|-------|-----|--------|
| MCH-TT-096-01 | Crear tabla conversations | 1 | Completado |
| MCH-TT-096-02 | Crear tabla messages | 1 | Completado |
| MCH-TT-096-03 | Crear tabla tool_calls | 1 | Completado |

---

## Resumen de Story Points

| Historia | Descripcion | SP | Estado |
|----------|-------------|-----|--------|
| MCH-US-090 | Gateway LLM Agnostico | 5 | Completado |
| MCH-US-091 | Tools de Productos | 3 | Completado |
| MCH-US-092 | Tools de Ventas | 3 | Completado |
| MCH-US-093 | Tools de Inventario | 2 | Completado |
| MCH-US-094 | Tools de Clientes | 2 | Completado |
| MCH-US-095 | Rate Limiting de Tokens | 3 | Completado |
| MCH-US-096 | Logging de Conversaciones | 3 | Completado |
| **TOTAL** | | **21** | |

---

**Ultima actualizacion:** 2026-01-17