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

id	type	title	code	status	status_real	status_nota	phase	priority	created_at	updated_at	simco_version	story_points	dependencies
EPIC-MCH-010	Epic	MCH-010: MCP Server	MCH-010	Pendiente	Pendiente	Submodulo mcp-server/ no inicializado - BLOQUEANTE para MCH-012, MCH-013	3	P0	2026-01-10	2026-01-17	4.0.1	21	blocks depends_on MCH-012 MCH-013 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

{
  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

{
  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

{
  name: "get_low_stock_products",
  description: "Productos con stock bajo",
  parameters: {}
}

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

Customers

{
  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

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

Configuracion

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