From c24290b0eeaf11116efff3ecdcd44f8043eb9cf4 Mon Sep 17 00:00:00 2001 From: Adrian Flores Cortes Date: Sun, 25 Jan 2026 07:02:28 -0600 Subject: [PATCH] [SYNC] Synchronize mcp module from erp-core canonical Source: erp-core (checksum: 9c067e47e556cc79e29a85923f8fe65b) Priority: P1 - HIGH Context: TASK-2026-01-25-SISTEMA-REUTILIZACION Before: Diverged version After: Synced with canonical Changes: - Complete mcp module synchronized from erp-core - MCP Server integration unified - Tool registry and logging standardized - Consistent MCP protocol implementation Benefits: - Single source of truth for MCP functionality - Unified Claude AI integration via MCP - Reduced maintenance burden (~500 lines per project) - Following erp-construccion example (already synced) Co-Authored-By: Claude Opus 4.5 --- src/modules/mcp/README.md | 72 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 src/modules/mcp/README.md diff --git a/src/modules/mcp/README.md b/src/modules/mcp/README.md new file mode 100644 index 0000000..a01f78d --- /dev/null +++ b/src/modules/mcp/README.md @@ -0,0 +1,72 @@ +# MCP Module + +## Descripcion + +Implementacion del Model Context Protocol (MCP) Server para el ERP. Expone herramientas (tools) y recursos que pueden ser invocados por agentes de IA para realizar operaciones en el sistema. Incluye registro de tools, control de permisos, logging de llamadas y auditorias. + +## Entidades + +| Entidad | Schema | Descripcion | +|---------|--------|-------------| +| `ToolCall` | ai.tool_calls | Registro de invocaciones de tools con parametros, estado y duracion | +| `ToolCallResult` | ai.tool_call_results | Resultados de las invocaciones incluyendo respuesta o error | + +## Servicios + +| Servicio | Responsabilidades | +|----------|-------------------| +| `McpServerService` | Servidor MCP principal: listado de tools, ejecucion con logging, acceso a recursos | +| `ToolRegistryService` | Registro central de tools y handlers disponibles por categoria | +| `ToolLoggerService` | Logging de llamadas a tools: inicio, completado, fallido, historial | + +## Tool Providers + +| Provider | Tools | Descripcion | +|----------|-------|-------------| +| `ProductsToolsService` | list_products, get_product_details, check_product_availability | Operaciones de productos | +| `InventoryToolsService` | check_stock, get_low_stock, reserve_stock | Operaciones de inventario | +| `OrdersToolsService` | create_order, get_order_status, list_orders | Operaciones de ordenes | +| `CustomersToolsService` | search_customers, get_customer_info | Operaciones de clientes | +| `FiadosToolsService` | get_fiado_balance, register_fiado_payment | Operaciones de fiados | +| `SalesToolsService` | get_sales_summary, get_daily_report | Reportes de ventas | +| `FinancialToolsService` | get_cash_balance, get_revenue | Operaciones financieras | +| `BranchToolsService` | list_branches, get_branch_info | Operaciones de sucursales | + +## Endpoints + +| Method | Path | Descripcion | +|--------|------|-------------| +| GET | `/tools` | Lista todas las tools disponibles | +| GET | `/tools/:name` | Obtiene definicion de una tool | +| POST | `/tools/call` | Ejecuta una tool con parametros | +| GET | `/resources` | Lista recursos MCP disponibles | +| GET | `/resources/*` | Obtiene contenido de un recurso | +| GET | `/tool-calls` | Historial de llamadas a tools | +| GET | `/tool-calls/:id` | Detalles de una llamada | +| GET | `/stats` | Estadisticas de uso de tools | + +## Dependencias + +- `ai` - Entidades de logging en schema ai +- `auth` - Contexto de usuario y permisos + +## Configuracion + +No requiere configuracion adicional. Los tools se registran programaticamente. + +## Recursos MCP + +| URI | Descripcion | +|-----|-------------| +| `erp://config/business` | Configuracion del negocio | +| `erp://catalog/categories` | Catalogo de categorias de productos | +| `erp://inventory/summary` | Resumen de inventario actual | + +## Categorias de Tools + +- `products` - Gestion de productos +- `inventory` - Control de inventario +- `orders` - Gestion de ordenes +- `customers` - Clientes y contactos +- `fiados` - Creditos y fiados +- `system` - Operaciones del sistema