rckrdmrd
d2130250f1
Epic MCH-010 completed with: - 24 MCP tools across 6 categories - StdioServerTransport implementation - Backend API integration with mock fallbacks Updates: - MCH-010-mcp-server.md: Status -> Completado - _MAP.md: Progress 40% -> 43%, MCH-010 no longer blocker This unblocks MCH-012 and MCH-013 (pending MCH-011) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
449 lines
13 KiB
Markdown
449 lines
13 KiB
Markdown
---
|
|
id: EPIC-MCH-010
|
|
type: Epic
|
|
title: "MCH-010: MCP Server"
|
|
code: MCH-010
|
|
status: Completado
|
|
status_real: Completado
|
|
status_nota: "24 tools implementados - 6 categorias (products, orders, fiado, customers, inventory, sales)"
|
|
phase: 3
|
|
priority: P0
|
|
created_at: 2026-01-10
|
|
updated_at: 2026-01-17
|
|
completed_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:** 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
|
|
```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 | 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
|
|
|
|
- [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
|