# 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