@fullqueso/mcp-bc-gastos 1.1.0

package/tools/expense-details.js

@@ -0,0 +1,179 @@
+import { getDateRange } from '../utils/date-helper.js';
+import { getExpenseCategory, getAccountName, EXPENSE_CATEGORIES } from '../config/expense-accounts.js';
+import { resolveStores } from '../config/company-config.js';
+import { round2 } from '../utils/currency-converter.js';
+
+export const expenseDetailsTool = {
+  name: 'get_expense_details',
+  description:
+    'Drill-down de transacciones individuales de gastos operacionales. Muestra cada movimiento contable con fecha, documento, descripción, proveedor (vendor), cuenta, monto y categoría. Ideal para investigar el detalle detrás de un resumen de gastos. Montos en USD.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88'],
+        description: 'Tienda a consultar.',
+      },
+      period: {
+        type: 'string',
+        enum: ['last_7_days', 'last_30_days', 'this_month', 'last_month', 'last_3_months', 'specific_month', 'custom'],
+        description: 'Periodo de consulta. Usar "specific_month" con month para un mes específico.',
+        default: 'last_month',
+      },
+      month: {
+        type: 'string',
+        description: 'Mes específico en formato YYYY-MM (ej: "2025-12"). Usar con period="specific_month".',
+      },
+      start_date: {
+        type: 'string',
+        description: 'Fecha inicio (YYYY-MM-DD). Requerido si period=custom.',
+      },
+      end_date: {
+        type: 'string',
+        description: 'Fecha fin (YYYY-MM-DD). Requerido si period=custom.',
+      },
+      category: {
+        type: 'string',
+        enum: [
+          'planta_fisica', 'alquiler_equipos', 'logistica', 'marketing',
+          'administrativos', 'seguros', 'bancarios', 'servicios_contratados',
+          'nomina', 'otros',
+        ],
+        description: 'Filtrar por categoría de gasto (opcional).',
+      },
+      account_number: {
+        type: 'string',
+        description: 'Filtrar por número de cuenta específico, ej: "68210" (opcional).',
+      },
+      min_amount: {
+        type: 'number',
+        description: 'Monto mínimo en USD para filtrar transacciones (opcional).',
+      },
+      limit: {
+        type: 'number',
+        description: 'Máximo de transacciones a retornar. Default: 50.',
+        default: 50,
+      },
+    },
+    required: ['store'],
+  },
+};
+
+export async function handleExpenseDetails(bcClient, args) {
+  const store = args.store;
+  const period = args.period || 'last_month';
+  const limit = args.limit || 50;
+  const dateRange = getDateRange(period, args.start_date, args.end_date, args.month);
+
+  const stores = resolveStores([store]);
+  const storeInfo = stores[0];
+
+  // Determine account range filters
+  let accountMin = '60000';
+  let accountMax = '99999';
+  let specificAccount = null;
+
+  if (args.account_number) {
+    specificAccount = args.account_number;
+  } else if (args.category) {
+    const catConfig = EXPENSE_CATEGORIES[args.category];
+    if (!catConfig) {
+      throw new Error(`Categoría desconocida: ${args.category}. Opciones: ${Object.keys(EXPENSE_CATEGORIES).join(', ')}`);
+    }
+    accountMin = String(catConfig.accountRange.min);
+    accountMax = String(catConfig.accountRange.max);
+  }
+
+  // Fetch GL entries
+  const filters = {
+    startDate: dateRange.start,
+    endDate: dateRange.end,
+  };
+
+  if (specificAccount) {
+    filters.accountNumber = specificAccount;
+  } else {
+    filters.accountMin = accountMin;
+    filters.accountMax = accountMax;
+  }
+
+  // Fetch GL entries (critical) and vendor map (best-effort) in parallel
+  // buildVendorMap is resilient — returns {} if vendor endpoints fail
+  const [entries, vendorMap] = await Promise.all([
+    bcClient.getDetailedGLEntries(storeInfo.companyId, filters),
+    bcClient.buildVendorMap(storeInfo.companyId, dateRange.start, dateRange.end),
+  ]);
+
+  // Map entries with category info, vendor info, and compute expense amount
+  let transactions = entries.map((entry) => {
+    const category = getExpenseCategory(entry.accountNumber);
+    const expenseAmount = (entry.debitAmount || 0) - (entry.creditAmount || 0);
+    const vendor = vendorMap[entry.documentNumber] || null;
+
+    return {
+      posting_date: entry.postingDate,
+      document_no: entry.documentNumber,
+      description: entry.description || '',
+      vendor_name: vendor?.vendor_name || null,
+      vendor_number: vendor?.vendor_number || null,
+      account_number: entry.accountNumber,
+      account_name: getAccountName(entry.accountNumber),
+      debit: round2(entry.debitAmount || 0),
+      credit: round2(entry.creditAmount || 0),
+      amount_usd: round2(expenseAmount),
+      category: category?.key || 'otros',
+      category_name: category?.name || 'Otros Gastos',
+      category_icon: category?.icon || '',
+    };
+  });
+
+  // Apply category filter if account_number was not specified but category was
+  if (args.category && !args.account_number) {
+    transactions = transactions.filter((t) => t.category === args.category);
+  }
+
+  // Apply min_amount filter
+  if (args.min_amount) {
+    transactions = transactions.filter((t) => Math.abs(t.amount_usd) >= args.min_amount);
+  }
+
+  const totalBeforeLimit = transactions.length;
+
+  // Apply limit
+  transactions = transactions.slice(0, limit);
+
+  // Summary
+  const totalAmount = transactions.reduce((sum, t) => sum + t.amount_usd, 0);
+
+  // Exchange rate
+  let exchangeRate = null;
+  try {
+    const rates = await bcClient.getExchangeRates(store);
+    exchangeRate = bcClient.getExchangeRateForDate(rates, dateRange.end);
+  } catch (_) {
+    // optional
+  }
+
+  return {
+    store: storeInfo.name,
+    store_code: store,
+    period: { start: dateRange.start, end: dateRange.end, label: period },
+    filters_applied: {
+      category: args.category || null,
+      account_number: args.account_number || null,
+      min_amount: args.min_amount || null,
+    },
+    exchange_rate: exchangeRate ? {
+      rate: round2(exchangeRate.rate),
+      label: `1 USD = ${round2(exchangeRate.rate)} VES`,
+    } : null,
+    summary: {
+      total_transactions: totalBeforeLimit,
+      showing: transactions.length,
+      total_amount_usd: round2(totalAmount),
+      total_amount_ves: exchangeRate ? round2(totalAmount * exchangeRate.rate) : null,
+    },
+    transactions,
+  };
+}

package/tools/store-comparison.js

@@ -0,0 +1,179 @@
+import { getDateRange } from '../utils/date-helper.js';
+import { analyzeExpenses, aggregateByCategory } from '../lib/expense-analyzer.js';
+import { calculateRatios } from '../lib/ratio-calculator.js';
+import { round2 } from '../utils/currency-converter.js';
+
+export const storeComparisonTool = {
+  name: 'compare_stores',
+  description:
+    'Compara la eficiencia de gastos entre las tiendas de Full Queso (FQ01 Chacao, FQ28 Marqués, FQ88 Candelaria). Ranking por eficiencia, varianzas entre tiendas y oportunidades de ahorro identificadas.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      period: {
+        type: 'string',
+        enum: ['last_7_days', 'last_30_days', 'this_month', 'last_month', 'last_3_months', 'specific_month', 'custom'],
+        description: 'Periodo de comparación.',
+        default: 'last_month',
+      },
+      month: {
+        type: 'string',
+        description: 'Mes específico en formato YYYY-MM. Usar con period="specific_month".',
+      },
+      start_date: {
+        type: 'string',
+        description: 'Fecha inicio (YYYY-MM-DD). Requerido si period=custom',
+      },
+      end_date: {
+        type: 'string',
+        description: 'Fecha fin (YYYY-MM-DD). Requerido si period=custom',
+      },
+    },
+  },
+};
+
+export async function handleStoreComparison(bcClient, args) {
+  const period = args.period || 'last_month';
+  const dateRange = getDateRange(period, args.start_date, args.end_date, args.month);
+
+  // Fetch all 3 stores
+  const allStoresData = await bcClient.getAllStoresFinancialData(['all'], dateRange.start, dateRange.end);
+
+  // Exchange rate
+  const firstStoreCode = Object.keys(allStoresData)[0];
+  let exchangeRate = null;
+  try {
+    const rates = await bcClient.getExchangeRates(firstStoreCode);
+    exchangeRate = bcClient.getExchangeRateForDate(rates, dateRange.end);
+  } catch (err) {
+    // Optional
+  }
+
+  // Analyze each store
+  const storeAnalyses = {};
+  const storeRatios = {};
+  for (const [code, storeData] of Object.entries(allStoresData)) {
+    storeAnalyses[code] = analyzeExpenses(storeData);
+    storeRatios[code] = calculateRatios(storeData);
+  }
+
+  // Build comparison table
+  const comparison = Object.entries(storeAnalyses).map(([code, analysis]) => ({
+    store_code: code,
+    store_name: analysis.store,
+    total_revenue: analysis.total_revenue,
+    total_cogs: analysis.total_cogs,
+    gross_margin_pct: analysis.gross_margin_pct,
+    total_income: analysis.total_revenue,
+    total_expenses: analysis.total_expenses,
+    operating_margin: analysis.operating_margin,
+    operating_margin_pct: analysis.operating_margin_pct,
+    margin_status: analysis.margin_status,
+    categories: analysis.categories.reduce((obj, cat) => {
+      obj[cat.category] = {
+        amount: cat.total,
+        pct_of_income: cat.pct_of_income,
+        benchmark_status: cat.benchmark_status,
+      };
+      return obj;
+    }, {}),
+  }));
+
+  // Ranking by efficiency (highest margin = most efficient)
+  const ranking = [...comparison].sort((a, b) => b.operating_margin_pct - a.operating_margin_pct);
+
+  // Identify savings opportunities (compare worst vs best in each category)
+  const savingsOpportunities = identifySavingsOpportunities(comparison, allStoresData);
+
+  // Cross-store insights
+  const crossInsights = generateCrossStoreInsights(comparison, ranking);
+
+  return {
+    period: { start: dateRange.start, end: dateRange.end, label: period },
+    exchange_rate: exchangeRate ? {
+      rate: Math.round(exchangeRate.rate * 100) / 100,
+      label: `1 USD = ${Math.round(exchangeRate.rate * 100) / 100} VES`,
+    } : null,
+    ranking,
+    comparison,
+    savings_opportunities: savingsOpportunities,
+    insights: crossInsights,
+  };
+}
+
+function identifySavingsOpportunities(comparison, allStoresData) {
+  const opportunities = [];
+
+  // For each expense category, find the store with lowest % of income
+  const categoryKeys = new Set();
+  for (const store of comparison) {
+    for (const key of Object.keys(store.categories)) {
+      categoryKeys.add(key);
+    }
+  }
+
+  for (const catKey of categoryKeys) {
+    const storesWithCat = comparison
+      .filter((s) => s.categories[catKey])
+      .map((s) => ({
+        store: s.store_name,
+        store_code: s.store_code,
+        pct: s.categories[catKey].pct_of_income,
+        amount: s.categories[catKey].amount,
+        income: s.total_income,
+      }));
+
+    if (storesWithCat.length < 2) continue;
+
+    const best = storesWithCat.reduce((min, s) => s.pct < min.pct ? s : min);
+    const worst = storesWithCat.reduce((max, s) => s.pct > max.pct ? s : max);
+
+    const gap = worst.pct - best.pct;
+    if (gap > 2 && worst.amount > 100) {
+      // Calculate potential savings if worst matched best's %
+      const potentialSaving = worst.income > 0
+        ? round2(worst.income * (gap / 100))
+        : 0;
+
+      opportunities.push({
+        category: catKey,
+        best_store: best.store,
+        best_pct: best.pct,
+        worst_store: worst.store,
+        worst_pct: worst.pct,
+        gap_pct: round2(gap),
+        potential_monthly_saving: potentialSaving,
+        recommendation: `Si ${worst.store} alcanza el nivel de ${best.store} en ${catKey}, ahorro potencial de $${potentialSaving.toLocaleString()}/mes`,
+      });
+    }
+  }
+
+  return opportunities.sort((a, b) => b.potential_monthly_saving - a.potential_monthly_saving);
+}
+
+function generateCrossStoreInsights(comparison, ranking) {
+  const insights = [];
+
+  if (ranking.length > 1) {
+    const best = ranking[0];
+    const worst = ranking[ranking.length - 1];
+
+    insights.push({
+      type: 'ranking',
+      message: `${best.store_name} es la tienda más eficiente con margen operativo de ${best.operating_margin_pct}%`,
+      detail: `Diferencia de ${round2(best.operating_margin_pct - worst.operating_margin_pct)} puntos vs ${worst.store_name}`,
+    });
+
+    // Total potential savings
+    if (worst.operating_margin_pct < best.operating_margin_pct - 5) {
+      const potentialIncrease = round2(worst.total_income * ((best.operating_margin_pct - worst.operating_margin_pct) / 100));
+      insights.push({
+        type: 'opportunity',
+        message: `Si ${worst.store_name} iguala la eficiencia de ${best.store_name}, margen adicional de $${potentialIncrease.toLocaleString()}/mes`,
+        detail: 'Revisar categorías con mayor diferencia entre tiendas.',
+      });
+    }
+  }
+
+  return insights;
+}

package/tools/trends.js

@@ -0,0 +1,84 @@
+import { getMonthlyRanges } from '../utils/date-helper.js';
+import { analyzeTrends } from '../lib/trend-analyzer.js';
+
+export const trendsTool = {
+  name: 'get_trends',
+  description:
+    'Análisis de tendencias históricas de gastos e ingresos de Full Queso. Muestra evolución mensual de los últimos 3-6 meses, tasas de crecimiento, estacionalidad y visualización de tendencias. Identifica patrones preocupantes o positivos.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      months: {
+        type: 'number',
+        description: 'Cantidad de meses a analizar (3-12).',
+        default: 6,
+      },
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88'],
+        description: 'Tienda a analizar. Tendencias se calculan por tienda individual.',
+        default: 'FQ01',
+      },
+    },
+  },
+};
+
+export async function handleTrends(bcClient, args) {
+  const months = Math.min(Math.max(args.months || 6, 3), 12);
+  const storeCode = args.store || 'FQ01';
+
+  // Get monthly date ranges
+  const monthlyRanges = getMonthlyRanges(months);
+
+  // Exchange rate
+  let exchangeRate = null;
+  try {
+    const rates = await bcClient.getExchangeRates(storeCode);
+    exchangeRate = bcClient.getExchangeRateForDate(rates, monthlyRanges[monthlyRanges.length - 1].end);
+  } catch (err) {
+    // Optional
+  }
+
+  // Fetch data for each month
+  const monthlyData = [];
+  for (const range of monthlyRanges) {
+    try {
+      const storeData = await bcClient.getStoreFinancialData(storeCode, range.start, range.end);
+      monthlyData.push({
+        label: range.label,
+        labelEs: range.labelEs,
+        storeData,
+      });
+    } catch (err) {
+      // Skip months with no data
+      monthlyData.push({
+        label: range.label,
+        labelEs: range.labelEs,
+        storeData: {
+          storeCode,
+          storeName: storeCode,
+          period: { start: range.start, end: range.end },
+          expenses: [],
+          income: [],
+          totalIncome: 0,
+          totalExpenses: 0,
+          operatingMargin: 0,
+          operatingMarginPct: 0,
+        },
+      });
+    }
+  }
+
+  // Analyze trends
+  const trends = analyzeTrends(monthlyData);
+
+  return {
+    store: storeCode,
+    months_analyzed: months,
+    exchange_rate: exchangeRate ? {
+      rate: Math.round(exchangeRate.rate * 100) / 100,
+      label: `1 USD = ${Math.round(exchangeRate.rate * 100) / 100} VES`,
+    } : null,
+    ...trends,
+  };
+}

package/utils/currency-converter.js

@@ -0,0 +1,30 @@
+// Currency Converter - VES/USD
+// Business Central LCY is USD; VES is the foreign currency
+
+export function convertUSDtoVES(amountUSD, exchangeRate) {
+  if (!exchangeRate || exchangeRate === 0) return null;
+  return amountUSD * exchangeRate;
+}
+
+export function convertVEStoUSD(amountVES, exchangeRate) {
+  if (!exchangeRate || exchangeRate === 0) return null;
+  return amountVES / exchangeRate;
+}
+
+export function formatDualCurrency(amountUSD, exchangeRate) {
+  if (amountUSD === null || amountUSD === undefined) return 'N/A';
+
+  const usdStr = `$${Math.abs(amountUSD).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+
+  if (exchangeRate) {
+    const amountVES = amountUSD * exchangeRate;
+    const vesStr = `Bs. ${Math.abs(amountVES).toLocaleString('es-VE', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+    return `${usdStr} (${vesStr})`;
+  }
+
+  return usdStr;
+}
+
+export function round2(value) {
+  return Math.round(value * 100) / 100;
+}

package/utils/date-helper.js

@@ -0,0 +1,107 @@
+import { DateTime } from 'luxon';
+
+export function getDateRange(period, startDate, endDate, month) {
+  const now = DateTime.now();
+
+  switch (period) {
+    case 'last_7_days':
+      return {
+        start: now.minus({ days: 7 }).toISODate(),
+        end: now.toISODate(),
+      };
+    case 'last_30_days':
+      return {
+        start: now.minus({ days: 30 }).toISODate(),
+        end: now.toISODate(),
+      };
+    case 'this_month':
+      return {
+        start: now.startOf('month').toISODate(),
+        end: now.toISODate(),
+      };
+    case 'last_month': {
+      const lastMonth = now.minus({ months: 1 });
+      return {
+        start: lastMonth.startOf('month').toISODate(),
+        end: lastMonth.endOf('month').toISODate(),
+      };
+    }
+    case 'last_3_months': {
+      return {
+        start: now.minus({ months: 3 }).startOf('month').toISODate(),
+        end: now.toISODate(),
+      };
+    }
+    case 'last_6_months': {
+      return {
+        start: now.minus({ months: 6 }).startOf('month').toISODate(),
+        end: now.toISODate(),
+      };
+    }
+    case 'specific_month': {
+      if (!month) throw new Error('month es requerido en formato YYYY-MM cuando period es "specific_month"');
+      const [year, mon] = month.split('-').map(Number);
+      const target = DateTime.fromObject({ year, month: mon });
+      return {
+        start: target.startOf('month').toISODate(),
+        end: target.endOf('month').toISODate(),
+      };
+    }
+    case 'custom':
+      if (!startDate || !endDate) {
+        throw new Error('start_date y end_date son requeridos cuando period es "custom"');
+      }
+      return { start: startDate, end: endDate };
+    default:
+      return {
+        start: now.minus({ days: 30 }).toISODate(),
+        end: now.toISODate(),
+      };
+  }
+}
+
+export function getPreviousPeriodRange(start, end) {
+  const startDT = DateTime.fromISO(start);
+  const endDT = DateTime.fromISO(end);
+  const days = endDT.diff(startDT, 'days').days;
+
+  const prevEnd = startDT.minus({ days: 1 });
+  const prevStart = prevEnd.minus({ days: Math.round(days) });
+
+  return {
+    start: prevStart.toISODate(),
+    end: prevEnd.toISODate(),
+  };
+}
+
+export function getMonthlyRanges(months = 6) {
+  const now = DateTime.now();
+  const ranges = [];
+
+  for (let i = months - 1; i >= 0; i--) {
+    const target = now.minus({ months: i });
+    const isCurrentMonth = i === 0;
+    ranges.push({
+      label: target.toFormat('yyyy-MM'),
+      labelEs: target.setLocale('es').toFormat('LLLL yyyy'),
+      start: target.startOf('month').toISODate(),
+      end: isCurrentMonth ? now.toISODate() : target.endOf('month').toISODate(),
+    });
+  }
+
+  return ranges;
+}
+
+export function formatCurrency(amount, currency = 'USD') {
+  if (amount === null || amount === undefined) return 'N/A';
+  if (currency === 'VES') {
+    return `Bs. ${amount.toLocaleString('es-VE', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+  }
+  return `$${amount.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+export function formatPercent(value) {
+  if (value === null || value === undefined) return 'N/A';
+  const sign = value > 0 ? '+' : '';
+  return `${sign}${value.toFixed(1)}%`;
+}

package/utils/logger.js

@@ -0,0 +1,18 @@
+// Logger utility - writes to stderr (MCP convention: stdout is for protocol)
+
+const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+const currentLevel = LOG_LEVELS[process.env.LOG_LEVEL || 'info'] || 1;
+
+function log(level, ...args) {
+  if (LOG_LEVELS[level] >= currentLevel) {
+    const prefix = `[${new Date().toISOString()}] [${level.toUpperCase()}]`;
+    console.error(prefix, ...args);
+  }
+}
+
+export const logger = {
+  debug: (...args) => log('debug', ...args),
+  info: (...args) => log('info', ...args),
+  warn: (...args) => log('warn', ...args),
+  error: (...args) => log('error', ...args),
+};