@fullqueso/mcp-bc-gastos 1.14.0 → 1.14.1

package/CHANGELOG.md

@@ -4,22 +4,22 @@
 
 ### Highlights
 - **35 tools** across 7 domains — new **Inventario** domain for inventory cost analysis
-- 3 new tools to diagnose FIFO unit cost, open layers, and value entry adjustments
-- Uses BC Standard v2.0 API: `items`, `itemLedgerEntries`, `valueEntries`
+- 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, costingMethod, inventory qty, unitPrice, categoría. Filtra por número, búsqueda por nombre, o categoría
-- `get_item_ledger_entries` — capas FIFO abiertas/cerradas con remainingQuantity y costAmountActual. Calcula `weighted_avg_unit_cost` sobre capas abiertas. Filtros por open_only (default: true), entry_type, fecha
-- `get_item_value_entries` — detalle de valorización por entrada del ledger: costPerUnit, ajustes de costo, revaluaciones. Permite drill-down por item_ledger_entry_number específico
+- `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`
-- All tools use `buildApiUrl()` + `apiCall()` from BCClient (Standard v2.0, GUID-based)
-- `unit_cost_actual` computed per ledger entry: `|costAmountActual / quantity|`
-- `weighted_avg_unit_cost` computed proportionally from remaining qty of open layers
+- 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)
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullqueso/mcp-bc-gastos",
-  "version": "1.14.0",
+  "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": {

package/server.js

@@ -133,7 +133,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       // Inventario (inventory cost analysis)
       itemCardTool,
       itemLedgerEntriesTool,
-      itemValueEntriesTool,
+      itemValueEntriesTool,  // get_item_cost_analysis
       // Reports
       managerReportTool,
       cxpReportTool,
@@ -250,7 +250,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'get_item_ledger_entries':
         result = await handleItemLedgerEntries(bcClient, args);
         break;
-      case 'get_item_value_entries':
+      case 'get_item_cost_analysis':
         result = await handleItemValueEntries(bcClient, args);
         break;
       // Reports

package/tools/inventario/item-card.js

@@ -47,7 +47,7 @@ export async function handleItemCard(bcClient, args) {
   }
 
   const params = {
-    $select: 'number,displayName,type,itemCategoryCode,unitCost,unitPrice,inventory,costingMethod,blocked',
+    $select: 'number,displayName,type,itemCategoryCode,unitCost,unitPrice,inventory,blocked',
     $orderby: 'number',
   };
   if (filters.length > 0) params.$filter = filters.join(' and ');
@@ -72,7 +72,6 @@ export async function handleItemCard(bcClient, args) {
     unit_cost: round2(item.unitCost || 0),
     unit_price: round2(item.unitPrice || 0),
     inventory: round2(item.inventory || 0),
-    costing_method: item.costingMethod || null,
     blocked: item.blocked || false,
   }));
 

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

@@ -4,7 +4,7 @@ import { logger } from '../../utils/logger.js';
 export const itemLedgerEntriesTool = {
   name: 'get_item_ledger_entries',
   description:
-    'Entradas del libro de artículos (Item Ledger Entries) — capas FIFO abiertas/cerradas con cantidades restantes y costo real. Esencial para diagnosticar por qué el unitCost de un ítem tiene cierto valor. Por defecto muestra solo capas abiertas.',
+    '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: {
@@ -17,14 +17,9 @@ export const itemLedgerEntriesTool = {
         type: 'string',
         description: 'Número de ítem exacto (e.g. FQ0850).',
       },
-      open_only: {
-        type: 'boolean',
-        description: 'true = solo entradas abiertas (capas FIFO activas). Default: true.',
-      },
       entry_type: {
         type: 'string',
-        enum: ['Purchase', 'Sale', 'Positive Adjmt.', 'Negative Adjmt.', 'Transfer', 'Consumption', 'Output'],
-        description: 'Filtrar por tipo de entrada.',
+        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',
@@ -36,7 +31,7 @@ export const itemLedgerEntriesTool = {
       },
       top: {
         type: 'number',
-        description: 'Limitar resultados. Default: 100.',
+        description: 'Limitar resultados. Default: 200.',
       },
     },
     required: ['store', 'item_number'],
@@ -52,25 +47,22 @@ export async function handleItemLedgerEntries(bcClient, args) {
   const store = stores[0];
   const companyId = store.companyId;
 
-  const openOnly = args.open_only !== false; // default true
   const filters = [`itemNumber eq '${args.item_number}'`];
-
-  if (openOnly) filters.push('open eq true');
   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 || 100;
+  const top = args.top || 200;
 
   const url = bcClient.buildApiUrl(companyId, 'itemLedgerEntries', {
     $filter: filters.join(' and '),
-    $select: 'entryNumber,itemNumber,postingDate,entryType,documentNumber,description,quantity,remainingQuantity,costAmountActual,costAmountExpected,open,locationCode',
+    $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} (open_only=${openOnly})`);
+  logger.info(`${store.code}: ${data.length} item ledger entries for ${args.item_number}`);
 
   const entries = data.map((e) => ({
     entry_number: e.entryNumber,
@@ -78,40 +70,53 @@ export async function handleItemLedgerEntries(bcClient, args) {
     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),
-    remaining_quantity: round5(e.remainingQuantity || 0),
     cost_amount_actual: round2(e.costAmountActual || 0),
-    cost_amount_expected: round2(e.costAmountExpected || 0),
+    sales_amount_actual: round2(e.salesAmountActual || 0),
     unit_cost_actual: e.quantity ? round5(Math.abs((e.costAmountActual || 0) / e.quantity)) : 0,
-    open: e.open,
-    location_code: e.locationCode || null,
   }));
 
-  // Summary for open layers
-  const openEntries = entries.filter((e) => e.open);
-  const totalRemainingQty = openEntries.reduce((sum, e) => sum + e.remaining_quantity, 0);
-  const totalCostOpen = openEntries.reduce((sum, e) => {
-    // Proportional cost for remaining qty
-    if (e.quantity !== 0) {
-      return sum + (e.cost_amount_actual * (e.remaining_quantity / e.quantity));
-    }
-    return sum;
-  }, 0);
-  const weightedAvgCost = totalRemainingQty !== 0 ? Math.abs(totalCostOpen / totalRemainingQty) : 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: { open_only: openOnly, entry_type: args.entry_type || 'all' },
+    filter: { entry_type: args.entry_type || 'all', start_date: args.start_date || 'all', end_date: args.end_date || 'all' },
     total_entries: entries.length,
-    open_layers_summary: {
-      open_layers_count: openEntries.length,
-      total_remaining_qty: round5(totalRemainingQty),
-      total_cost_remaining: round2(totalCostOpen),
-      weighted_avg_unit_cost: round5(weightedAvgCost),
+    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,
   };
 }

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

@@ -2,9 +2,9 @@ import { resolveStores } from '../../config/company-config.js';
 import { logger } from '../../utils/logger.js';
 
 export const itemValueEntriesTool = {
-  name: 'get_item_value_entries',
+  name: 'get_item_cost_analysis',
   description:
-    'Value Entries de un ítem — detalle de valorización por entrada del ledger: costo por unidad exacto, ajustes de costo, revaluaciones. Usar después de get_item_ledger_entries para profundizar en una capa de costo específica.',
+    'Análisis de costo de un ítem — calcula costo promedio ponderado de entradas recientes (compras, ensamblaje, ajustes positivos), compara con el unitCost actual de BC, y muestra el historial de costos por mes. Útil para entender por qué el unitCost difiere del costo esperado.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -17,21 +17,9 @@ export const itemValueEntriesTool = {
         type: 'string',
         description: 'Número de ítem exacto (e.g. FQ0850).',
       },
-      item_ledger_entry_number: {
+      months: {
         type: 'number',
-        description: 'Filtrar por entrada específica del item ledger (entryNumber del get_item_ledger_entries).',
-      },
-      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: 100.',
+        description: 'Meses de historial a analizar. Default: 6.',
       },
     },
     required: ['store', 'item_number'],
@@ -46,57 +34,106 @@ export async function handleItemValueEntries(bcClient, args) {
   const stores = resolveStores([storeParam]);
   const store = stores[0];
   const companyId = store.companyId;
+  const months = args.months || 6;
+
+  // Calculate start date
+  const now = new Date();
+  const startDate = new Date(now.getFullYear(), now.getMonth() - months, 1);
+  const startStr = startDate.toISOString().split('T')[0];
 
-  const filters = [`itemNumber eq '${args.item_number}'`];
+  // Fetch item card + all ledger entries in parallel
+  const [itemData, entries] = await Promise.all([
+    bcClient.apiCall(bcClient.buildApiUrl(companyId, 'items', {
+      $filter: `number eq '${args.item_number}'`,
+      $select: 'number,displayName,unitCost,unitPrice,inventory',
+    })),
+    bcClient.apiCallAllPages(bcClient.buildApiUrl(companyId, 'itemLedgerEntries', {
+      $filter: `itemNumber eq '${args.item_number}' and postingDate ge ${startStr}`,
+      $select: 'entryNumber,postingDate,entryType,documentNumber,quantity,costAmountActual',
+      $orderby: 'postingDate asc',
+    })),
+  ]);
 
-  if (args.item_ledger_entry_number) {
-    filters.push(`itemLedgerEntryNumber eq ${args.item_ledger_entry_number}`);
+  const item = itemData[0] || null;
+  logger.info(`${store.code}: ${entries.length} ledger entries for ${args.item_number} since ${startStr}`);
+
+  // Separate inbound (receipts) vs outbound (issues)
+  const inbound = []; // Purchase, Positive Adjmt, Assembly Output
+  const outbound = []; // Sale, Negative Adjmt, Consumption, Assembly Consumption
+
+  for (const e of entries) {
+    const mapped = {
+      entry_number: e.entryNumber,
+      posting_date: e.postingDate,
+      entry_type: e.entryType,
+      document_number: e.documentNumber,
+      quantity: e.quantity,
+      cost_amount_actual: round2(e.costAmountActual || 0),
+      unit_cost: e.quantity ? round5(Math.abs((e.costAmountActual || 0) / e.quantity)) : 0,
+    };
+
+    if (e.quantity > 0) {
+      inbound.push(mapped);
+    } else if (e.quantity < 0) {
+      outbound.push(mapped);
+    }
   }
-  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 || 100;
-
-  const url = bcClient.buildApiUrl(companyId, 'valueEntries', {
-    $filter: filters.join(' and '),
-    $select: 'entryNumber,itemLedgerEntryNumber,itemNumber,postingDate,entryType,documentNumber,costAmountActual,costAmountExpected,costPerUnit,valuedQuantity,invoicedQuantity,costPostedToGL',
-    $orderby: 'postingDate desc',
-    $top: String(top),
-  });
-
-  const data = await bcClient.apiCall(url);
-  logger.info(`${store.code}: ${data.length} value entries for ${args.item_number}`);
-
-  const entries = data.map((e) => ({
-    entry_number: e.entryNumber,
-    item_ledger_entry_number: e.itemLedgerEntryNumber,
-    item_number: e.itemNumber,
-    posting_date: e.postingDate,
-    entry_type: e.entryType,
-    document_number: e.documentNumber || null,
-    cost_amount_actual: round2(e.costAmountActual || 0),
-    cost_amount_expected: round2(e.costAmountExpected || 0),
-    cost_per_unit: round5(e.costPerUnit || 0),
-    valued_quantity: round5(e.valuedQuantity || 0),
-    invoiced_quantity: round5(e.invoicedQuantity || 0),
-    cost_posted_to_gl: round2(e.costPostedToGL || 0),
+
+  // Cost trend by month (inbound only)
+  const monthlyInbound = {};
+  for (const e of inbound) {
+    const month = e.posting_date.substring(0, 7); // YYYY-MM
+    if (!monthlyInbound[month]) monthlyInbound[month] = { qty: 0, cost: 0, entries: 0 };
+    monthlyInbound[month].qty += e.quantity;
+    monthlyInbound[month].cost += e.cost_amount_actual;
+    monthlyInbound[month].entries += 1;
+  }
+  const costTrend = Object.entries(monthlyInbound).map(([month, data]) => ({
+    month,
+    inbound_qty: round5(data.qty),
+    inbound_cost: round2(data.cost),
+    avg_unit_cost: data.qty > 0 ? round5(data.cost / data.qty) : 0,
+    entries: data.entries,
   }));
 
-  // Summary
-  const totalCostActual = entries.reduce((sum, e) => sum + e.cost_amount_actual, 0);
-  const totalValuedQty = entries.reduce((sum, e) => sum + e.valued_quantity, 0);
+  // Overall inbound weighted avg
+  const totalInboundQty = inbound.reduce((s, e) => s + e.quantity, 0);
+  const totalInboundCost = inbound.reduce((s, e) => s + e.cost_amount_actual, 0);
+  const weightedAvgInbound = totalInboundQty > 0 ? round5(totalInboundCost / totalInboundQty) : 0;
+
+  // Last 5 inbound entries (most recent costs)
+  const recentInbound = inbound.slice(-5).reverse();
+
+  // Discrepancy analysis
+  const bcUnitCost = item ? item.unitCost : null;
+  const discrepancy = bcUnitCost !== null ? round5(bcUnitCost - weightedAvgInbound) : null;
 
   return {
     store: store.code,
     store_name: store.name,
     item_number: args.item_number,
-    total_entries: entries.length,
-    summary: {
-      total_cost_actual: round2(totalCostActual),
-      total_valued_qty: round5(totalValuedQty),
-      avg_cost_per_unit: totalValuedQty !== 0 ? round5(Math.abs(totalCostActual / totalValuedQty)) : 0,
+    item_name: item ? item.displayName : null,
+    current_bc_data: item ? {
+      unit_cost: item.unitCost,
+      unit_price: item.unitPrice,
+      inventory_on_hand: item.inventory,
+    } : null,
+    cost_analysis: {
+      period: `${startStr} to today`,
+      total_inbound_qty: round5(totalInboundQty),
+      total_inbound_cost: round2(totalInboundCost),
+      weighted_avg_inbound_cost: weightedAvgInbound,
+      bc_unit_cost: bcUnitCost,
+      discrepancy,
+      discrepancy_note: discrepancy !== null && Math.abs(discrepancy) > 0.01
+        ? `BC unitCost (${bcUnitCost}) differs from weighted avg inbound (${weightedAvgInbound}) by ${discrepancy}. BC uses FIFO layers internally — the unitCost reflects remaining open layers, not the simple average of all receipts.`
+        : 'BC unitCost matches weighted avg inbound cost.',
     },
-    entries,
+    cost_trend_by_month: costTrend,
+    recent_inbound_entries: recentInbound,
+    total_outbound_entries: outbound.length,
+    total_outbound_qty: round5(outbound.reduce((s, e) => s + e.quantity, 0)),
+    total_entries_in_period: entries.length,
   };
 }