@fullqueso/mcp-bc-gastos 1.1.0

package/server.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Only load .env if running from source (local development).
+// When installed via npm/npx, env vars come from the MCP client config.
+const envPath = join(__dirname, '.env');
+if (existsSync(envPath)) {
+  const dotenv = await import('dotenv');
+  dotenv.config({ path: envPath });
+}
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { BCClient } from './lib/bc-client.js';
+import { expenseAnalysisTool, handleExpenseAnalysis } from './tools/expense-analysis.js';
+import { efficiencyRatiosTool, handleEfficiencyRatios } from './tools/efficiency-ratios.js';
+import { storeComparisonTool, handleStoreComparison } from './tools/store-comparison.js';
+import { anomalyDetectionTool, handleAnomalyDetection } from './tools/anomaly-detection.js';
+import { trendsTool, handleTrends } from './tools/trends.js';
+import { expenseDetailsTool, handleExpenseDetails } from './tools/expense-details.js';
+import { accountTransactionsTool, handleAccountTransactions } from './tools/account-transactions.js';
+
+const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf-8'));
+const bcClient = new BCClient();
+
+const server = new Server(
+  {
+    name: pkg.name,
+    version: pkg.version,
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List all available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      expenseAnalysisTool,
+      efficiencyRatiosTool,
+      storeComparisonTool,
+      anomalyDetectionTool,
+      trendsTool,
+      expenseDetailsTool,
+      accountTransactionsTool,
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    let result;
+
+    switch (name) {
+      case 'get_expense_analysis':
+        result = await handleExpenseAnalysis(bcClient, args);
+        break;
+      case 'get_efficiency_ratios':
+        result = await handleEfficiencyRatios(bcClient, args);
+        break;
+      case 'compare_stores':
+        result = await handleStoreComparison(bcClient, args);
+        break;
+      case 'detect_anomalies':
+        result = await handleAnomalyDetection(bcClient, args);
+        break;
+      case 'get_trends':
+        result = await handleTrends(bcClient, args);
+        break;
+      case 'get_expense_details':
+        result = await handleExpenseDetails(bcClient, args);
+        break;
+      case 'get_account_transactions':
+        result = await handleAccountTransactions(bcClient, args);
+        break;
+      default:
+        return {
+          content: [{ type: 'text', text: `Herramienta desconocida: ${name}` }],
+          isError: true,
+        };
+    }
+
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  } catch (error) {
+    console.error(`Error ejecutando herramienta ${name}:`, error);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error: ${error.message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+function validateEnv() {
+  const required = [
+    'BC_API_BASE', 'BC_TENANT_ID', 'BC_ENVIRONMENT',
+    'BC_TOKEN_URL', 'BC_CLIENT_ID', 'BC_CLIENT_SECRET', 'BC_SCOPE',
+    'BC_COMPANY_FQ01',
+  ];
+  const missing = required.filter((k) => !process.env[k]);
+  if (missing.length > 0) {
+    console.error(`Missing required environment variables: ${missing.join(', ')}`);
+    console.error('Set them in your MCP client config or .env file.');
+    console.error('See: https://github.com/Fullqueso/fullqueso-mcp-bc-gastos#installation');
+    process.exit(1);
+  }
+}
+
+async function main() {
+  validateEnv();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('MCP Full Queso BC Gastos server running on stdio');
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/tools/account-transactions.js

@@ -0,0 +1,125 @@
+import { getExpenseCategory, getAccountName } from '../config/expense-accounts.js';
+import { resolveStores } from '../config/company-config.js';
+import { round2 } from '../utils/currency-converter.js';
+
+export const accountTransactionsTool = {
+  name: 'get_account_transactions',
+  description:
+    'Listado completo de transacciones para una cuenta contable específica con balance running y nombre de proveedor. Ideal para auditar movimientos de una cuenta, ej: "Todas las transacciones de la cuenta 68210 en FQ28 en diciembre 2025". Sin límite de registros. Montos en USD.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      account_number: {
+        type: 'string',
+        description: 'Número de cuenta contable (requerido), ej: "68210", "71100".',
+      },
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88'],
+        description: 'Tienda a consultar.',
+      },
+      start_date: {
+        type: 'string',
+        description: 'Fecha inicio en formato YYYY-MM-DD.',
+      },
+      end_date: {
+        type: 'string',
+        description: 'Fecha fin en formato YYYY-MM-DD.',
+      },
+    },
+    required: ['account_number', 'store', 'start_date', 'end_date'],
+  },
+};
+
+export async function handleAccountTransactions(bcClient, args) {
+  const { account_number, store, start_date, end_date } = args;
+
+  if (!account_number || !store || !start_date || !end_date) {
+    throw new Error('Parámetros requeridos: account_number, store, start_date, end_date');
+  }
+
+  const stores = resolveStores([store]);
+  const storeInfo = stores[0];
+
+  // Fetch GL entries (critical) and vendor map (best-effort) in parallel
+  const [entries, vendorMap] = await Promise.all([
+    bcClient.getDetailedGLEntries(storeInfo.companyId, {
+      startDate: start_date,
+      endDate: end_date,
+      accountNumber: account_number,
+    }),
+    bcClient.buildVendorMap(storeInfo.companyId, start_date, end_date),
+  ]);
+
+  // Get category and account info
+  const category = getExpenseCategory(account_number);
+  const accountName = getAccountName(account_number);
+
+  // Build transactions with running balance and vendor info
+  let runningBalance = 0;
+  const transactions = entries
+    .sort((a, b) => {
+      // Sort chronologically ascending for running balance
+      if (a.postingDate !== b.postingDate) return a.postingDate.localeCompare(b.postingDate);
+      return a.entryNumber - b.entryNumber;
+    })
+    .map((entry) => {
+      const debit = entry.debitAmount || 0;
+      const credit = entry.creditAmount || 0;
+      const netAmount = debit - credit;
+      runningBalance += netAmount;
+      const vendor = vendorMap[entry.documentNumber] || null;
+
+      return {
+        posting_date: entry.postingDate,
+        entry_number: entry.entryNumber,
+        document_no: entry.documentNumber,
+        description: entry.description || '',
+        vendor_name: vendor?.vendor_name || null,
+        vendor_number: vendor?.vendor_number || null,
+        debit: round2(debit),
+        credit: round2(credit),
+        net_amount: round2(netAmount),
+        running_balance: round2(runningBalance),
+      };
+    });
+
+  // Exchange rate
+  let exchangeRate = null;
+  try {
+    const rates = await bcClient.getExchangeRates(store);
+    exchangeRate = bcClient.getExchangeRateForDate(rates, end_date);
+  } catch (_) {
+    // optional
+  }
+
+  const totalDebit = round2(transactions.reduce((s, t) => s + t.debit, 0));
+  const totalCredit = round2(transactions.reduce((s, t) => s + t.credit, 0));
+  const totalNet = round2(totalDebit - totalCredit);
+
+  return {
+    store: storeInfo.name,
+    store_code: store,
+    account: {
+      number: account_number,
+      name: accountName,
+      category: category?.key || null,
+      category_name: category?.name || null,
+      category_icon: category?.icon || null,
+    },
+    period: { start: start_date, end: end_date },
+    exchange_rate: exchangeRate ? {
+      rate: round2(exchangeRate.rate),
+      label: `1 USD = ${round2(exchangeRate.rate)} VES`,
+    } : null,
+    summary: {
+      total_transactions: transactions.length,
+      total_debit: totalDebit,
+      total_credit: totalCredit,
+      net_amount: totalNet,
+      net_amount_ves: exchangeRate ? round2(totalNet * exchangeRate.rate) : null,
+      final_balance: transactions.length > 0 ? transactions[transactions.length - 1].running_balance : 0,
+    },
+    transactions,
+  };
+}

package/tools/anomaly-detection.js

@@ -0,0 +1,105 @@
+import { getDateRange, getPreviousPeriodRange } from '../utils/date-helper.js';
+import { detectAnomalies } from '../lib/anomaly-detector.js';
+
+export const anomalyDetectionTool = {
+  name: 'detect_anomalies',
+  description:
+    'Detecta anomalías en los gastos operacionales de Full Queso: gastos por encima de benchmarks, incrementos inusuales vs periodo anterior, concentración excesiva en una cuenta, y alertas de margen. Incluye severidad, causas posibles y acciones recomendadas.',
+  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 a analizar para detectar anomalías.',
+        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',
+      },
+      stores: {
+        type: 'array',
+        items: { type: 'string', enum: ['FQ01', 'FQ28', 'FQ88', 'all'] },
+        description: 'Tiendas a analizar.',
+        default: ['all'],
+      },
+      sensitivity: {
+        type: 'string',
+        enum: ['low', 'medium', 'high'],
+        description: 'Sensibilidad de detección. "high" detecta más anomalías.',
+        default: 'medium',
+      },
+    },
+  },
+};
+
+export async function handleAnomalyDetection(bcClient, args) {
+  const period = args.period || 'last_month';
+  const stores = args.stores || ['all'];
+
+  const dateRange = getDateRange(period, args.start_date, args.end_date, args.month);
+  const prevRange = getPreviousPeriodRange(dateRange.start, dateRange.end);
+
+  // Fetch current period
+  const currentData = await bcClient.getAllStoresFinancialData(stores, dateRange.start, dateRange.end);
+
+  // Fetch previous period for comparison
+  let previousData = null;
+  try {
+    previousData = await bcClient.getAllStoresFinancialData(stores, prevRange.start, prevRange.end);
+  } catch (err) {
+    // Previous period data is optional
+  }
+
+  // Exchange rate
+  const firstStoreCode = Object.keys(currentData)[0];
+  let exchangeRate = null;
+  try {
+    const rates = await bcClient.getExchangeRates(firstStoreCode);
+    exchangeRate = bcClient.getExchangeRateForDate(rates, dateRange.end);
+  } catch (err) {
+    // Optional
+  }
+
+  // Detect anomalies for each store
+  const results = {};
+  let totalAnomalies = 0;
+  let totalCritical = 0;
+  let totalWarnings = 0;
+
+  for (const [code, storeData] of Object.entries(currentData)) {
+    const prevStoreData = previousData ? previousData[code] : null;
+    results[code] = detectAnomalies(storeData, prevStoreData);
+    totalAnomalies += results[code].total_anomalies;
+    totalCritical += results[code].critical;
+    totalWarnings += results[code].warnings;
+  }
+
+  return {
+    period: {
+      current: { start: dateRange.start, end: dateRange.end },
+      previous: { start: prevRange.start, end: prevRange.end },
+      label: period,
+    },
+    exchange_rate: exchangeRate ? {
+      rate: Math.round(exchangeRate.rate * 100) / 100,
+      label: `1 USD = ${Math.round(exchangeRate.rate * 100) / 100} VES`,
+    } : null,
+    summary: {
+      total_anomalies: totalAnomalies,
+      critical: totalCritical,
+      warnings: totalWarnings,
+      status: totalCritical > 0 ? '🚨 Requiere atención inmediata' : totalWarnings > 0 ? '⚠️ Monitorear' : '✅ Sin anomalías significativas',
+    },
+    by_store: results,
+  };
+}

package/tools/efficiency-ratios.js

@@ -0,0 +1,81 @@
+import { getDateRange } from '../utils/date-helper.js';
+import { calculateRatios } from '../lib/ratio-calculator.js';
+
+export const efficiencyRatiosTool = {
+  name: 'get_efficiency_ratios',
+  description:
+    'Calcula ratios de eficiencia financiera de Full Queso: gastos/ingresos, nómina/ingresos, alquiler/ingresos, servicios/ingresos, marketing/ingresos y margen operativo. Compara contra benchmarks del sector restaurantes/deli.',
+  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 análisis.',
+        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',
+      },
+      stores: {
+        type: 'array',
+        items: { type: 'string', enum: ['FQ01', 'FQ28', 'FQ88', 'all'] },
+        description: 'Tiendas a analizar.',
+        default: ['all'],
+      },
+    },
+  },
+};
+
+export async function handleEfficiencyRatios(bcClient, args) {
+  const period = args.period || 'last_month';
+  const stores = args.stores || ['all'];
+
+  const dateRange = getDateRange(period, args.start_date, args.end_date, args.month);
+
+  const allStoresData = await bcClient.getAllStoresFinancialData(stores, 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
+  }
+
+  const results = {};
+  for (const [code, storeData] of Object.entries(allStoresData)) {
+    results[code] = calculateRatios(storeData);
+  }
+
+  // Ranking by operating margin
+  const ranking = Object.entries(results)
+    .map(([code, r]) => ({
+      store: r.store,
+      store_code: code,
+      operating_margin_pct: r.main_ratios.operating_margin.value,
+      expense_to_income_pct: r.main_ratios.expense_to_income.value,
+    }))
+    .sort((a, b) => b.operating_margin_pct - a.operating_margin_pct);
+
+  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,
+    by_store: results,
+    efficiency_ranking: ranking,
+  };
+}

package/tools/expense-analysis.js

@@ -0,0 +1,88 @@
+import { getDateRange } from '../utils/date-helper.js';
+import { analyzeExpenses } from '../lib/expense-analyzer.js';
+import { formatExpenseAnalysis } from '../lib/formatter.js';
+
+export const expenseAnalysisTool = {
+  name: 'get_expense_analysis',
+  description:
+    'Análisis detallado de gastos operacionales de Full Queso por categoría (nómina, alquiler, servicios, marketing, etc.) con números de cuenta específicos. Incluye comparación contra benchmarks del sector y insights accionables. Montos en USD (moneda base BC).',
+  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 análisis. Usar "specific_month" con el parámetro month para un mes específico.',
+        default: 'last_month',
+      },
+      month: {
+        type: 'string',
+        description: 'Mes específico en formato YYYY-MM (ej: "2026-01"). 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',
+      },
+      stores: {
+        type: 'array',
+        items: { type: 'string', enum: ['FQ01', 'FQ28', 'FQ88', 'all'] },
+        description: 'Tiendas a analizar. Use ["all"] para todas.',
+        default: ['all'],
+      },
+    },
+  },
+};
+
+export async function handleExpenseAnalysis(bcClient, args) {
+  const period = args.period || 'last_month';
+  const stores = args.stores || ['all'];
+
+  const dateRange = getDateRange(period, args.start_date, args.end_date, args.month);
+
+  // Fetch data for all requested stores
+  const allStoresData = await bcClient.getAllStoresFinancialData(stores, dateRange.start, dateRange.end);
+
+  // Fetch exchange rate for dual currency display
+  const firstStoreCode = Object.keys(allStoresData)[0];
+  let exchangeRate = null;
+  try {
+    const rates = await bcClient.getExchangeRates(firstStoreCode);
+    exchangeRate = bcClient.getExchangeRateForDate(rates, dateRange.end);
+  } catch (err) {
+    // Exchange rate is optional
+  }
+
+  const results = {};
+  for (const [code, storeData] of Object.entries(allStoresData)) {
+    results[code] = analyzeExpenses(storeData);
+  }
+
+  // If multiple stores, add combined summary
+  let combined = null;
+  const storeCodes = Object.keys(results);
+  if (storeCodes.length > 1) {
+    const totalIncome = storeCodes.reduce((s, c) => s + results[c].total_income, 0);
+    const totalExpenses = storeCodes.reduce((s, c) => s + results[c].total_expenses, 0);
+    combined = {
+      total_stores: storeCodes.length,
+      total_income: Math.round(totalIncome * 100) / 100,
+      total_expenses: Math.round(totalExpenses * 100) / 100,
+      operating_margin: Math.round((totalIncome - totalExpenses) * 100) / 100,
+      operating_margin_pct: totalIncome > 0 ? Math.round(((totalIncome - totalExpenses) / totalIncome) * 100 * 100) / 100 : 0,
+    };
+  }
+
+  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,
+    by_store: results,
+    combined,
+  };
+}