@fullqueso/mcp-bc-gastos 1.13.0 → 1.14.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # CHANGELOG
 
+## [1.14.0] - 2026-03-15
+
+### Highlights
+- **35 tools** across 7 domains — new **Inventario** domain for inventory cost analysis
+- 3 new tools to diagnose unit cost, transaction history, and cost trends
+- Uses BC Standard v2.0 API: `items`, `itemLedgerEntries`
+
+### Added
+
+**Inventario (Inventory Cost Analysis) — 3 herramientas (Standard v2.0):**
+- `get_item_card` — datos maestros de ítems: unitCost, inventory qty, unitPrice, categoría. Filtra por número, búsqueda por nombre, o categoría
+- `get_item_ledger_entries` — historial de movimientos de inventario con costo real por entrada. Resumen por entry_type (Assembly Output, Sale, Purchase, Adjustments). Calcula `unit_cost_actual` y `inbound_avg_unit_cost`
+- `get_item_cost_analysis` — análisis completo: weighted avg inbound cost vs BC unitCost, tendencia de costo por mes, últimas 5 entradas de recepción, detección de discrepancia
+
+### Technical
+- New domain folder: `tools/inventario/` with `index.js` re-exports
+- Spec document: `docs/tool_inventario.md` with BC v2.0 API field limitations documented
+- BC v2.0 API does NOT expose `costingMethod`, `remainingQuantity`, `open`, or `valueEntries` — cost analysis computed from full transaction history instead
+- Entry types use BC OData encoding: `Assembly_x0020_Output`, `Negative_x0020_Adjmt_x002E_`, etc.
+- Parallel fetch of items + itemLedgerEntries in cost analysis tool
+- Zero `console.log` — all logging via `logger.info()` (console.error wrapper)
+
+---
+
 ## [1.10.0] - 2026-02-26
 
 ### Highlights

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fullqueso/mcp-bc-gastos",
-  "version": "1.13.0",
-  "description": "MCP server for Business Central operational expense analysis, bank reconciliation, POS reconciliation, accounts receivable/payable, multi-payment draft visibility, payroll, and manager reports - Full Queso franchise stores",
+  "version": "1.14.1",
+  "description": "MCP server for Business Central operational expense analysis, bank reconciliation, POS reconciliation, accounts receivable/payable, multi-payment draft visibility, payroll, inventory cost analysis, and manager reports - Full Queso franchise stores",
   "main": "server.js",
   "bin": {
     "mcp-bc-gastos": "server.js"

package/scripts/generate-cxp-report-xlsx.py

@@ -0,0 +1,355 @@
+#!/usr/bin/env python3
+"""
+Generate CxP (Cuentas por Pagar) Excel report with 3 tier sheets + summary.
+
+Usage:
+    python3 generate-cxp-report-xlsx.py <input.json> <output.xlsx>
+
+Input: JSON file with { store, store_name, report_date, invoices[] }
+Output: Formatted Excel with 4 sheets (Resumen, Sin Draft, Draft No Posteado, Pago Parcial)
+
+Requires: openpyxl (pip3 install openpyxl)
+"""
+
+import json
+import sys
+import argparse
+from datetime import datetime, date
+from pathlib import Path
+
+try:
+    from openpyxl import Workbook
+    from openpyxl.styles import Font, Alignment, PatternFill, Border, Side
+except ImportError:
+    print("Error: openpyxl is required. Install with: pip3 install openpyxl", file=sys.stderr)
+    sys.exit(1)
+
+
+# ─── Styles ───
+
+BOLD = Font(bold=True)
+BOLD_14 = Font(bold=True, size=14)
+BOLD_12 = Font(bold=True, size=12)
+BOLD_11 = Font(bold=True, size=11)
+HEADER_FILL = PatternFill(start_color="4472C4", end_color="4472C4", fill_type="solid")
+HEADER_FONT = Font(bold=True, color="FFFFFF", size=10)
+SUBTOTAL_FILL = PatternFill(start_color="D9E2F3", end_color="D9E2F3", fill_type="solid")
+SUBTOTAL_FONT = Font(bold=True, size=10)
+NUM_FMT = '#,##0.00'
+
+TIER_FILLS = {
+    "fully_pending": PatternFill(start_color="FCE4EC", end_color="FCE4EC", fill_type="solid"),
+    "draft_in_progress": PatternFill(start_color="FFF3E0", end_color="FFF3E0", fill_type="solid"),
+    "in_journal": PatternFill(start_color="E8F5E9", end_color="E8F5E9", fill_type="solid"),
+}
+
+TIER_LABELS = {
+    "fully_pending": "Sin Draft",
+    "draft_in_progress": "Draft No Posteado",
+    "in_journal": "Pago Parcial",
+}
+
+
+def set_col_widths(ws, widths):
+    for col_letter, width in widths.items():
+        ws.column_dimensions[col_letter].width = width
+
+
+def write_header_row(ws, row, headers, start_col=1):
+    for i, header in enumerate(headers):
+        cell = ws.cell(row=row, column=start_col + i, value=header)
+        cell.font = HEADER_FONT
+        cell.fill = HEADER_FILL
+        cell.alignment = Alignment(horizontal="center")
+
+
+def days_since(date_str, today):
+    try:
+        d = datetime.strptime(date_str, "%Y-%m-%d").date()
+        return max(0, (today - d).days)
+    except (ValueError, TypeError):
+        return 0
+
+
+# ─── Sheet 1: Resumen ───
+
+def build_resumen(wb, data, invoices, today):
+    ws = wb.active
+    ws.title = "Resumen"
+    set_col_widths(ws, {"A": 35, "B": 14, "C": 18, "D": 18, "E": 18, "F": 18, "G": 18, "H": 18, "I": 18})
+
+    store_label = f"{data.get('store', '')} — {data.get('store_name', '')}"
+    report_date = data.get("report_date", "")
+
+    ws.cell(row=1, column=1, value=f"REPORTE CxP — {store_label}").font = BOLD_14
+    ws.cell(row=2, column=1, value=f"Fecha: {report_date}").font = BOLD_12
+
+    # Group by tier
+    tiers = {"fully_pending": [], "draft_in_progress": [], "in_journal": []}
+    for inv in invoices:
+        tier = inv.get("tier", "fully_pending")
+        if tier in tiers:
+            tiers[tier].append(inv)
+
+    # Summary metrics
+    row = 4
+    ws.cell(row=row, column=1, value="Concepto").font = BOLD
+    ws.cell(row=row, column=2, value="Facturas").font = BOLD
+    ws.cell(row=row, column=3, value="Monto (USD)").font = BOLD
+
+    total_count = len(invoices)
+    total_amount = sum(inv.get("invoice_amount", 0) for inv in invoices)
+
+    row_data = [
+        ("TOTAL FACTURAS ABIERTAS", total_count, total_amount),
+        ("", "", ""),
+        (TIER_LABELS["fully_pending"], len(tiers["fully_pending"]),
+         sum(i.get("invoice_amount", 0) for i in tiers["fully_pending"])),
+        (TIER_LABELS["draft_in_progress"], len(tiers["draft_in_progress"]),
+         sum(i.get("invoice_amount", 0) for i in tiers["draft_in_progress"])),
+        (TIER_LABELS["in_journal"], len(tiers["in_journal"]),
+         sum(i.get("invoice_amount", 0) for i in tiers["in_journal"])),
+    ]
+
+    for i, (label, count, amount) in enumerate(row_data):
+        r = row + 1 + i
+        ws.cell(row=r, column=1, value=label)
+        if label:
+            ws.cell(row=r, column=2, value=count)
+            ws.cell(row=r, column=3, value=round(amount, 2)).number_format = NUM_FMT
+        if i == 0:
+            for c in range(1, 4):
+                ws.cell(row=r, column=c).font = BOLD
+
+    # Vendor breakdown
+    row += len(row_data) + 3
+    ws.cell(row=row, column=1, value="DESGLOSE POR PROVEEDOR").font = BOLD_12
+    row += 1
+
+    vendor_map = {}
+    for inv in invoices:
+        vno = inv.get("vendor_no", "")
+        if vno not in vendor_map:
+            vendor_map[vno] = {
+                "name": inv.get("vendor_name", vno),
+                "count": 0, "total": 0,
+                "sin_draft": 0, "sin_draft_n": 0,
+                "draft": 0, "draft_n": 0,
+                "parcial": 0, "parcial_n": 0,
+            }
+        v = vendor_map[vno]
+        v["count"] += 1
+        v["total"] += inv.get("invoice_amount", 0)
+        tier = inv.get("tier", "fully_pending")
+        if tier == "fully_pending":
+            v["sin_draft"] += inv.get("invoice_amount", 0)
+            v["sin_draft_n"] += 1
+        elif tier == "draft_in_progress":
+            v["draft"] += inv.get("invoice_amount", 0)
+            v["draft_n"] += 1
+        elif tier == "in_journal":
+            v["parcial"] += inv.get("invoice_amount", 0)
+            v["parcial_n"] += 1
+
+    vendors = sorted(vendor_map.items(), key=lambda x: x[1]["total"], reverse=True)
+
+    headers = ["No.", "Proveedor", "Facturas", "Total (USD)", "Sin Draft", "Sin Draft $", "Draft", "Draft $", "Parcial", "Parcial $"]
+    write_header_row(ws, row, headers)
+    row += 1
+
+    for vno, v in vendors:
+        ws.cell(row=row, column=1, value=vno)
+        ws.cell(row=row, column=2, value=v["name"])
+        ws.cell(row=row, column=3, value=v["count"])
+        ws.cell(row=row, column=4, value=round(v["total"], 2)).number_format = NUM_FMT
+        ws.cell(row=row, column=5, value=v["sin_draft_n"])
+        ws.cell(row=row, column=6, value=round(v["sin_draft"], 2)).number_format = NUM_FMT
+        ws.cell(row=row, column=7, value=v["draft_n"])
+        ws.cell(row=row, column=8, value=round(v["draft"], 2)).number_format = NUM_FMT
+        ws.cell(row=row, column=9, value=v["parcial_n"])
+        ws.cell(row=row, column=10, value=round(v["parcial"], 2)).number_format = NUM_FMT
+        row += 1
+
+    # Totals row
+    if vendors:
+        ws.cell(row=row, column=1, value="TOTAL").font = BOLD
+        ws.cell(row=row, column=3, value=total_count).font = BOLD
+        ws.cell(row=row, column=4, value=round(total_amount, 2)).number_format = NUM_FMT
+        ws.cell(row=row, column=4).font = BOLD
+        for c in range(1, 11):
+            ws.cell(row=row, column=c).fill = SUBTOTAL_FILL
+
+
+# ─── Sheet 2: Sin Draft ───
+
+def build_sin_draft(wb, invoices, today):
+    ws = wb.create_sheet("Sin Draft")
+    tier_invs = [i for i in invoices if i.get("tier") == "fully_pending"]
+    tier_invs.sort(key=lambda i: i.get("posting_date", ""))
+    fill = TIER_FILLS["fully_pending"]
+
+    set_col_widths(ws, {"A": 18, "B": 14, "C": 32, "D": 14, "E": 16, "F": 14})
+
+    ws.cell(row=1, column=1, value=f"SIN DRAFT — {len(tier_invs)} facturas").font = BOLD_14
+
+    headers = ["Factura", "Fecha", "Proveedor", "No. Proveedor", "Monto (USD)", "Dias Pendiente"]
+    write_header_row(ws, 3, headers)
+    ws.freeze_panes = "A4"
+
+    row = 4
+    for inv in tier_invs:
+        ws.cell(row=row, column=1, value=inv.get("invoice_no", ""))
+        ws.cell(row=row, column=2, value=inv.get("posting_date", ""))
+        ws.cell(row=row, column=3, value=inv.get("vendor_name", ""))
+        ws.cell(row=row, column=4, value=inv.get("vendor_no", ""))
+        ws.cell(row=row, column=5, value=inv.get("invoice_amount", 0)).number_format = NUM_FMT
+        ws.cell(row=row, column=6, value=days_since(inv.get("posting_date", ""), today))
+        for c in range(1, 7):
+            ws.cell(row=row, column=c).fill = fill
+        row += 1
+
+    # Subtotal
+    if tier_invs:
+        ws.cell(row=row, column=1, value="TOTAL").font = SUBTOTAL_FONT
+        ws.cell(row=row, column=5, value=f"=SUM(E4:E{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=5).font = SUBTOTAL_FONT
+        for c in range(1, 7):
+            ws.cell(row=row, column=c).fill = SUBTOTAL_FILL
+
+    return len(tier_invs)
+
+
+# ─── Sheet 3: Draft No Posteado ───
+
+def build_draft_no_posteado(wb, invoices, today):
+    ws = wb.create_sheet("Draft No Posteado")
+    tier_invs = [i for i in invoices if i.get("tier") == "draft_in_progress"]
+    tier_invs.sort(key=lambda i: i.get("posting_date", ""))
+    fill = TIER_FILLS["draft_in_progress"]
+
+    set_col_widths(ws, {"A": 18, "B": 14, "C": 32, "D": 14, "E": 16, "F": 16, "G": 14, "H": 16, "I": 16})
+
+    ws.cell(row=1, column=1, value=f"DRAFT NO POSTEADO — {len(tier_invs)} facturas").font = BOLD_14
+
+    headers = ["Factura", "Fecha", "Proveedor", "No. Proveedor", "Monto (USD)", "No. MP", "Status MP", "Drafted (USD)", "Pendiente Neto"]
+    write_header_row(ws, 3, headers)
+    ws.freeze_panes = "A4"
+
+    row = 4
+    for inv in tier_invs:
+        mp = inv.get("multi_payment") or {}
+        ws.cell(row=row, column=1, value=inv.get("invoice_no", ""))
+        ws.cell(row=row, column=2, value=inv.get("posting_date", ""))
+        ws.cell(row=row, column=3, value=inv.get("vendor_name", ""))
+        ws.cell(row=row, column=4, value=inv.get("vendor_no", ""))
+        ws.cell(row=row, column=5, value=inv.get("invoice_amount", 0)).number_format = NUM_FMT
+        ws.cell(row=row, column=6, value=mp.get("mp_no", ""))
+        ws.cell(row=row, column=7, value=mp.get("status", ""))
+        ws.cell(row=row, column=8, value=mp.get("total_payment_amount", 0)).number_format = NUM_FMT
+        ws.cell(row=row, column=9, value=mp.get("net_pending", inv.get("invoice_amount", 0))).number_format = NUM_FMT
+        for c in range(1, 10):
+            ws.cell(row=row, column=c).fill = fill
+        row += 1
+
+    if tier_invs:
+        ws.cell(row=row, column=1, value="TOTAL").font = SUBTOTAL_FONT
+        ws.cell(row=row, column=5, value=f"=SUM(E4:E{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=5).font = SUBTOTAL_FONT
+        ws.cell(row=row, column=8, value=f"=SUM(H4:H{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=8).font = SUBTOTAL_FONT
+        ws.cell(row=row, column=9, value=f"=SUM(I4:I{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=9).font = SUBTOTAL_FONT
+        for c in range(1, 10):
+            ws.cell(row=row, column=c).fill = SUBTOTAL_FILL
+
+    return len(tier_invs)
+
+
+# ─── Sheet 4: Pago Parcial ───
+
+def build_pago_parcial(wb, invoices, today):
+    ws = wb.create_sheet("Pago Parcial")
+    tier_invs = [i for i in invoices if i.get("tier") == "in_journal"]
+    tier_invs.sort(key=lambda i: i.get("posting_date", ""))
+    fill = TIER_FILLS["in_journal"]
+
+    set_col_widths(ws, {"A": 18, "B": 14, "C": 32, "D": 14, "E": 16, "F": 16, "G": 14, "H": 16, "I": 16})
+
+    ws.cell(row=1, column=1, value=f"PAGO PARCIAL — {len(tier_invs)} facturas").font = BOLD_14
+
+    headers = ["Factura", "Fecha", "Proveedor", "No. Proveedor", "Monto (USD)", "No. MP", "Status MP", "Drafted (USD)", "Pendiente Neto"]
+    write_header_row(ws, 3, headers)
+    ws.freeze_panes = "A4"
+
+    row = 4
+    for inv in tier_invs:
+        mp = inv.get("multi_payment") or {}
+        ws.cell(row=row, column=1, value=inv.get("invoice_no", ""))
+        ws.cell(row=row, column=2, value=inv.get("posting_date", ""))
+        ws.cell(row=row, column=3, value=inv.get("vendor_name", ""))
+        ws.cell(row=row, column=4, value=inv.get("vendor_no", ""))
+        ws.cell(row=row, column=5, value=inv.get("invoice_amount", 0)).number_format = NUM_FMT
+        ws.cell(row=row, column=6, value=mp.get("mp_no", ""))
+        ws.cell(row=row, column=7, value=mp.get("status", ""))
+        ws.cell(row=row, column=8, value=mp.get("total_payment_amount", 0)).number_format = NUM_FMT
+        ws.cell(row=row, column=9, value=mp.get("net_pending", inv.get("invoice_amount", 0))).number_format = NUM_FMT
+        for c in range(1, 10):
+            ws.cell(row=row, column=c).fill = fill
+        row += 1
+
+    if tier_invs:
+        ws.cell(row=row, column=1, value="TOTAL").font = SUBTOTAL_FONT
+        ws.cell(row=row, column=5, value=f"=SUM(E4:E{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=5).font = SUBTOTAL_FONT
+        ws.cell(row=row, column=8, value=f"=SUM(H4:H{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=8).font = SUBTOTAL_FONT
+        ws.cell(row=row, column=9, value=f"=SUM(I4:I{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=9).font = SUBTOTAL_FONT
+        for c in range(1, 10):
+            ws.cell(row=row, column=c).fill = SUBTOTAL_FILL
+
+    return len(tier_invs)
+
+
+# ─── Main ───
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate CxP Excel report")
+    parser.add_argument("input_json", help="Path to input JSON file")
+    parser.add_argument("output_xlsx", help="Path to output Excel file")
+    args = parser.parse_args()
+
+    input_path = Path(args.input_json)
+    output_path = Path(args.output_xlsx)
+
+    if not input_path.exists():
+        print(f"Error: Input file not found: {input_path}", file=sys.stderr)
+        sys.exit(1)
+
+    with open(input_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    invoices = data.get("invoices", [])
+    today = date.today()
+    if data.get("report_date"):
+        try:
+            today = datetime.strptime(data["report_date"], "%Y-%m-%d").date()
+        except ValueError:
+            pass
+
+    wb = Workbook()
+    build_resumen(wb, data, invoices, today)
+    n_sin = build_sin_draft(wb, invoices, today)
+    n_draft = build_draft_no_posteado(wb, invoices, today)
+    n_parcial = build_pago_parcial(wb, invoices, today)
+
+    wb.save(str(output_path))
+    print(json.dumps({
+        "file": str(output_path),
+        "sheets": {"sin_draft": n_sin, "draft_no_posteado": n_draft, "pago_parcial": n_parcial},
+        "total": len(invoices),
+    }))
+
+
+if __name__ == "__main__":
+    main()

package/server.js

@@ -66,8 +66,16 @@ import {
   employeesTool, handleEmployees,
 } from './tools/payroll/index.js';
 
+// Inventario tools (inventory cost analysis)
+import {
+  itemCardTool, handleItemCard,
+  itemLedgerEntriesTool, handleItemLedgerEntries,
+  itemValueEntriesTool, handleItemValueEntries,
+} from './tools/inventario/index.js';
+
 // Reports tools
 import { managerReportTool, handleGenerateManagerReport } from './tools/reports/manager-report.js';
+import { cxpReportTool, handleGenerateCxpReport } from './tools/reports/cxp-report.js';
 
 const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf-8'));
 const bcClient = new BCClient();
@@ -122,8 +130,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       payrollDocumentsTool,
       payrollLinesTool,
       employeesTool,
+      // Inventario (inventory cost analysis)
+      itemCardTool,
+      itemLedgerEntriesTool,
+      itemValueEntriesTool,  // get_item_cost_analysis
       // Reports
       managerReportTool,
+      cxpReportTool,
     ],
   };
 });
@@ -230,10 +243,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'get_employees':
         result = await handleEmployees(bcClient, args);
         break;
+      // Inventario (inventory cost analysis)
+      case 'get_item_card':
+        result = await handleItemCard(bcClient, args);
+        break;
+      case 'get_item_ledger_entries':
+        result = await handleItemLedgerEntries(bcClient, args);
+        break;
+      case 'get_item_cost_analysis':
+        result = await handleItemValueEntries(bcClient, args);
+        break;
       // Reports
       case 'generate_manager_report':
         result = await handleGenerateManagerReport(bcClient, args);
         break;
+      case 'generate_cxp_report':
+        result = await handleGenerateCxpReport(bcClient, args);
+        break;
       default:
         return {
           content: [{ type: 'text', text: `Herramienta desconocida: ${name}` }],

package/tools/inventario/index.js

@@ -0,0 +1,3 @@
+export { itemCardTool, handleItemCard } from './item-card.js';
+export { itemLedgerEntriesTool, handleItemLedgerEntries } from './item-ledger-entries.js';
+export { itemValueEntriesTool, handleItemValueEntries } from './item-value-entries.js';

package/tools/inventario/item-card.js

@@ -0,0 +1,88 @@
+import { resolveStores } from '../../config/company-config.js';
+import { logger } from '../../utils/logger.js';
+
+export const itemCardTool = {
+  name: 'get_item_card',
+  description:
+    'Datos maestros de ítems de inventario: unitCost, costingMethod, inventory qty, unitPrice, categoría. Filtra por número de ítem, búsqueda por nombre, o categoría.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88'],
+        description: 'Tienda a consultar.',
+      },
+      item_number: {
+        type: 'string',
+        description: 'Número de ítem exacto (e.g. FQ0850).',
+      },
+      item_search: {
+        type: 'string',
+        description: 'Búsqueda parcial por nombre (case-insensitive, client-side).',
+      },
+      item_category: {
+        type: 'string',
+        description: 'Filtrar por itemCategoryCode.',
+      },
+    },
+    required: ['store'],
+  },
+};
+
+export async function handleItemCard(bcClient, args) {
+  const storeParam = args.store;
+  if (!storeParam) throw new Error('Parámetro requerido: store');
+
+  const stores = resolveStores([storeParam]);
+  const store = stores[0];
+  const companyId = store.companyId;
+
+  const filters = [];
+  if (args.item_number) {
+    filters.push(`number eq '${args.item_number}'`);
+  }
+  if (args.item_category) {
+    filters.push(`itemCategoryCode eq '${args.item_category}'`);
+  }
+
+  const params = {
+    $select: 'number,displayName,type,itemCategoryCode,unitCost,unitPrice,inventory,blocked',
+    $orderby: 'number',
+  };
+  if (filters.length > 0) params.$filter = filters.join(' and ');
+  if (!args.item_number && !args.item_search) params.$top = '50';
+
+  const url = bcClient.buildApiUrl(companyId, 'items', params);
+  let data = await bcClient.apiCallAllPages(url);
+
+  logger.info(`${store.code}: ${data.length} items returned`);
+
+  // Client-side name search
+  if (args.item_search) {
+    const search = args.item_search.toLowerCase();
+    data = data.filter((item) => item.displayName && item.displayName.toLowerCase().includes(search));
+  }
+
+  const items = data.map((item) => ({
+    number: item.number,
+    name: item.displayName,
+    type: item.type,
+    category: item.itemCategoryCode || null,
+    unit_cost: round2(item.unitCost || 0),
+    unit_price: round2(item.unitPrice || 0),
+    inventory: round2(item.inventory || 0),
+    blocked: item.blocked || false,
+  }));
+
+  return {
+    store: store.code,
+    store_name: store.name,
+    total_items: items.length,
+    items,
+  };
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}

package/tools/inventario/item-ledger-entries.js

@@ -0,0 +1,130 @@
+import { resolveStores } from '../../config/company-config.js';
+import { logger } from '../../utils/logger.js';
+
+export const itemLedgerEntriesTool = {
+  name: 'get_item_ledger_entries',
+  description:
+    'Entradas del libro de artículos (Item Ledger Entries) — historial de movimientos de inventario con costo real por entrada. Muestra compras, ventas, ajustes, consumos, y ensamblaje. Calcula unit_cost_actual por entrada y resumen de costos por tipo de entrada.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88'],
+        description: 'Tienda a consultar.',
+      },
+      item_number: {
+        type: 'string',
+        description: 'Número de ítem exacto (e.g. FQ0850).',
+      },
+      entry_type: {
+        type: 'string',
+        description: 'Filtrar por tipo de entrada: Purchase, Sale, Positive_x0020_Adjmt., Negative_x0020_Adjmt., Transfer, Consumption, Assembly_x0020_Consumption, Assembly_x0020_Output.',
+      },
+      start_date: {
+        type: 'string',
+        description: 'Fecha inicio (YYYY-MM-DD).',
+      },
+      end_date: {
+        type: 'string',
+        description: 'Fecha fin (YYYY-MM-DD).',
+      },
+      top: {
+        type: 'number',
+        description: 'Limitar resultados. Default: 200.',
+      },
+    },
+    required: ['store', 'item_number'],
+  },
+};
+
+export async function handleItemLedgerEntries(bcClient, args) {
+  const storeParam = args.store;
+  if (!storeParam) throw new Error('Parámetro requerido: store');
+  if (!args.item_number) throw new Error('Parámetro requerido: item_number');
+
+  const stores = resolveStores([storeParam]);
+  const store = stores[0];
+  const companyId = store.companyId;
+
+  const filters = [`itemNumber eq '${args.item_number}'`];
+  if (args.entry_type) filters.push(`entryType eq '${args.entry_type}'`);
+  if (args.start_date) filters.push(`postingDate ge ${args.start_date}`);
+  if (args.end_date) filters.push(`postingDate le ${args.end_date}`);
+
+  const top = args.top || 200;
+
+  const url = bcClient.buildApiUrl(companyId, 'itemLedgerEntries', {
+    $filter: filters.join(' and '),
+    $select: 'entryNumber,itemNumber,postingDate,entryType,sourceNumber,sourceType,documentNumber,documentType,description,quantity,salesAmountActual,costAmountActual',
+    $orderby: 'postingDate desc',
+    $top: String(top),
+  });
+
+  const data = await bcClient.apiCall(url);
+  logger.info(`${store.code}: ${data.length} item ledger entries for ${args.item_number}`);
+
+  const entries = data.map((e) => ({
+    entry_number: e.entryNumber,
+    item_number: e.itemNumber,
+    posting_date: e.postingDate,
+    entry_type: e.entryType,
+    document_number: e.documentNumber || null,
+    document_type: e.documentType || null,
+    description: e.description || null,
+    quantity: round5(e.quantity || 0),
+    cost_amount_actual: round2(e.costAmountActual || 0),
+    sales_amount_actual: round2(e.salesAmountActual || 0),
+    unit_cost_actual: e.quantity ? round5(Math.abs((e.costAmountActual || 0) / e.quantity)) : 0,
+  }));
+
+  // Summary by entry type
+  const byType = {};
+  for (const e of entries) {
+    const type = e.entry_type;
+    if (!byType[type]) byType[type] = { count: 0, total_qty: 0, total_cost: 0 };
+    byType[type].count += 1;
+    byType[type].total_qty += e.quantity;
+    byType[type].total_cost += e.cost_amount_actual;
+  }
+
+  // Compute net inventory and weighted avg cost from all entries
+  const totalQty = entries.reduce((s, e) => s + e.quantity, 0);
+  const totalCost = entries.reduce((s, e) => s + e.cost_amount_actual, 0);
+
+  // Weighted avg cost from inbound entries only (positive qty = receipts)
+  const inbound = entries.filter((e) => e.quantity > 0);
+  const inboundQty = inbound.reduce((s, e) => s + e.quantity, 0);
+  const inboundCost = inbound.reduce((s, e) => s + e.cost_amount_actual, 0);
+  const avgInboundCost = inboundQty > 0 ? round5(inboundCost / inboundQty) : 0;
+
+  for (const [type, stats] of Object.entries(byType)) {
+    stats.total_qty = round5(stats.total_qty);
+    stats.total_cost = round2(stats.total_cost);
+    stats.avg_unit_cost = stats.total_qty !== 0 ? round5(Math.abs(stats.total_cost / stats.total_qty)) : 0;
+  }
+
+  return {
+    store: store.code,
+    store_name: store.name,
+    item_number: args.item_number,
+    filter: { entry_type: args.entry_type || 'all', start_date: args.start_date || 'all', end_date: args.end_date || 'all' },
+    total_entries: entries.length,
+    summary: {
+      net_quantity: round5(totalQty),
+      net_cost: round2(totalCost),
+      inbound_avg_unit_cost: avgInboundCost,
+      note: 'BC v2.0 API does not expose remainingQuantity or open flag. Net quantity = sum of all entry quantities (positive=in, negative=out). unitCost on Item Card is BC-calculated from FIFO layers internally.',
+    },
+    by_entry_type: byType,
+    entries,
+  };
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+function round5(n) {
+  return Math.round(n * 100000) / 100000;
+}