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

id	type	title	code	status	status_real	status_nota	phase	priority	created_at	updated_at	completed_at	simco_version	story_points	dependencies
EPIC-MCH-010	Epic	MCH-010: MCP Server	MCH-010	Completado	Completado	24 tools implementados - 6 categorias (products, orders, fiado, customers, inventory, sales)	3	P0	2026-01-10	2026-01-17	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: Completado
• Estado Real: 24 tools implementados en 6 categorías
• Story Points: 21
• Sprint Asignado: Sprint 1 (Desbloqueo Crítico)
• Completado: 2026-01-17

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	Completado	mcp-server/src/index.ts
Tools products (5)	Completado	mcp-server/src/tools/products.ts
Tools orders (4)	Completado	mcp-server/src/tools/orders.ts
Tools fiado (4)	Completado	mcp-server/src/tools/fiado.ts
Tools customers (3)	Completado	mcp-server/src/tools/customers.ts
Tools inventory (4)	Completado	mcp-server/src/tools/inventory.ts
Tools sales (4)	Completado	mcp-server/src/tools/sales.ts

Tools Implementados (24 total)

Categoria	Tool	Descripcion
Products	search_products	Buscar productos
	get_product	Obtener producto por ID
	list_products	Listar productos
	get_product_by_barcode	Buscar por codigo de barras
	get_low_stock_products	Productos con stock bajo
Orders	create_order	Crear pedido
	get_order	Obtener pedido
	list_orders	Listar pedidos
	update_order_status	Actualizar estado
Fiado	create_fiado	Crear credito fiado
	get_customer_fiados	Fiados de cliente
	pay_fiado	Registrar pago
	get_pending_fiados	Fiados pendientes
Customers	search_customers	Buscar clientes
	get_customer	Obtener cliente
	create_customer	Crear cliente
Inventory	get_inventory_status	Estado del inventario
	adjust_stock	Ajustar stock
	get_stock_movements	Movimientos de stock
	get_expiring_products	Productos por vencer
Sales	get_daily_sales	Ventas del dia
	get_sales_report	Reporte por periodo
	register_sale	Registrar venta
	get_today_summary	Resumen del dia

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