@fullqueso/mcp-bc-gastos 1.11.1 → 1.13.0

package/lib/bc-client.js

@@ -196,6 +196,11 @@ export class BCClient {
     return this.buildCustomApiUrl(companyId, 'fullQueso', 'multiPayment', 'v1.0', endpoint, params);
   }
 
+  // Shorthand for Payroll API calls (publisher: fullQueso, group: fqPayroll, v1.0)
+  buildPayrollApiUrl(companyId, endpoint, params = {}) {
+    return this.buildCustomApiUrl(companyId, 'fullQueso', 'fqPayroll', 'v1.0', endpoint, params);
+  }
+
   // ── OData V4 Web Service Methods ──────────────────────────────────
   // OData endpoints use company NAME (URL-encoded) instead of GUID.
   // Same OAuth token works; different URL path (ODataV4 vs api/v2.0).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fullqueso/mcp-bc-gastos",
-  "version": "1.11.1",
-  "description": "MCP server for Business Central operational expense analysis, bank reconciliation, POS reconciliation, accounts receivable/payable, and multi-payment draft visibility - Full Queso franchise stores",
+  "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",
   "main": "server.js",
   "bin": {
     "mcp-bc-gastos": "server.js"
@@ -38,6 +38,8 @@
     "accounts-receivable",
     "accounts-payable",
     "multi-payment",
+    "payroll",
+    "manager-report",
     "odata",
     "fullqueso"
   ],

package/server.js

@@ -59,6 +59,16 @@ import {
   draftSummaryTool, handleDraftSummary,
 } from './tools/multi-payment/index.js';
 
+// Payroll tools
+import {
+  payrollDocumentsTool, handlePayrollDocuments,
+  payrollLinesTool, handlePayrollLines,
+  employeesTool, handleEmployees,
+} from './tools/payroll/index.js';
+
+// Reports tools
+import { managerReportTool, handleGenerateManagerReport } from './tools/reports/manager-report.js';
+
 const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf-8'));
 const bcClient = new BCClient();
 
@@ -108,6 +118,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       draftReceivablesTool,
       draftPayablesTool,
       draftSummaryTool,
+      // Payroll
+      payrollDocumentsTool,
+      payrollLinesTool,
+      employeesTool,
+      // Reports
+      managerReportTool,
     ],
   };
 });
@@ -204,6 +220,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'get_draft_summary':
         result = await handleDraftSummary(bcClient, args);
         break;
+      // Payroll
+      case 'get_payroll_documents':
+        result = await handlePayrollDocuments(bcClient, args);
+        break;
+      case 'get_payroll_lines':
+        result = await handlePayrollLines(bcClient, args);
+        break;
+      case 'get_employees':
+        result = await handleEmployees(bcClient, args);
+        break;
+      // Reports
+      case 'generate_manager_report':
+        result = await handleGenerateManagerReport(bcClient, args);
+        break;
       default:
         return {
           content: [{ type: 'text', text: `Herramienta desconocida: ${name}` }],

package/tools/payroll/employees.js

@@ -0,0 +1,147 @@
+import { resolveStores } from '../../config/company-config.js';
+import { logger } from '../../utils/logger.js';
+
+export const employeesTool = {
+  name: 'get_employees',
+  description:
+    'Lista empleados de una tienda con datos de nomina: tipo, status, salarios base, bonos predeterminados, fechas. Filtros por status, tipo de nomina, busqueda por nombre.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88', 'all'],
+        description: 'Tienda(s) a consultar.',
+      },
+      status: {
+        type: 'string',
+        enum: ['Active', 'Inactive'],
+        description: "Filtrar por status. Default: 'Active'.",
+      },
+      payroll_type: {
+        type: 'string',
+        enum: ['SEMANAL', 'QUINCENAL', 'MENSUAL'],
+        description: 'Filtrar por tipo de nomina.',
+      },
+      employee_search: {
+        type: 'string',
+        description: 'Busqueda parcial por nombre (case-insensitive, client-side).',
+      },
+      employee_code: {
+        type: 'string',
+        description: 'Filtrar por codigo de empleado exacto.',
+      },
+    },
+    required: ['store'],
+  },
+};
+
+export async function handleEmployees(bcClient, args) {
+  const storeParam = args.store;
+  if (!storeParam) throw new Error('Parametro requerido: store');
+
+  const stores = resolveStores(storeParam === 'all' ? null : [storeParam]);
+
+  if (stores.length === 1) {
+    return processStore(bcClient, stores[0], args);
+  }
+
+  const results = await Promise.all(
+    stores.map((s) => processStore(bcClient, s, args))
+  );
+
+  const consolidated = {
+    total_employees: 0,
+    by_status: {},
+    by_payroll_type: {},
+    by_employee_type: {},
+  };
+
+  for (const r of results) {
+    consolidated.total_employees += r.summary.total_employees;
+    for (const [k, v] of Object.entries(r.summary.by_status)) {
+      consolidated.by_status[k] = (consolidated.by_status[k] || 0) + v;
+    }
+    for (const [k, v] of Object.entries(r.summary.by_payroll_type)) {
+      consolidated.by_payroll_type[k] = (consolidated.by_payroll_type[k] || 0) + v;
+    }
+    for (const [k, v] of Object.entries(r.summary.by_employee_type)) {
+      consolidated.by_employee_type[k] = (consolidated.by_employee_type[k] || 0) + v;
+    }
+  }
+
+  return { stores: results, consolidated };
+}
+
+async function processStore(bcClient, storeInfo, args) {
+  const companyId = storeInfo.companyId;
+  const status = args.status || 'Active';
+
+  const filters = [`companyCode eq '${storeInfo.code}'`, `status eq '${status}'`];
+  if (args.payroll_type) filters.push(`payrollType eq '${args.payroll_type}'`);
+  if (args.employee_code) filters.push(`employeeCode eq '${args.employee_code}'`);
+
+  const url = bcClient.buildPayrollApiUrl(companyId, 'fqEmployees', {
+    $filter: filters.join(' and '),
+    $select: 'employeeCode,employeeName,cedulaDeIdentidad,companyCode,employeeType,status,payrollType,startDate,endDate,defaultTransportBonusVES,bonoAlimentacionUSD,salarioBaseSemanalVES,salarioBaseMensualVES,bonoProduccionUSD',
+    $orderby: 'employeeName',
+  });
+
+  const data = await bcClient.apiCallAllPages(url);
+  logger.info(`${storeInfo.code}: ${data.length} employees (status=${status})`);
+
+  let employees = data.map((emp) => ({
+    employee_code: emp.employeeCode,
+    employee_name: emp.employeeName,
+    cedula: emp.cedulaDeIdentidad || null,
+    company_code: emp.companyCode,
+    employee_type: emp.employeeType || null,
+    status: emp.status,
+    payroll_type: emp.payrollType || null,
+    start_date: emp.startDate || null,
+    end_date: emp.endDate || null,
+    salary: {
+      base_semanal_ves: round2(emp.salarioBaseSemanalVES || 0),
+      base_mensual_ves: round2(emp.salarioBaseMensualVES || 0),
+    },
+    default_bonuses: {
+      transport_ves: round2(emp.defaultTransportBonusVES || 0),
+      alimentacion_usd: round2(emp.bonoAlimentacionUSD || 0),
+      produccion_usd: round2(emp.bonoProduccionUSD || 0),
+    },
+  }));
+
+  // Client-side name search
+  if (args.employee_search) {
+    const search = args.employee_search.toLowerCase();
+    employees = employees.filter((e) => e.employee_name && e.employee_name.toLowerCase().includes(search));
+  }
+
+  const summary = {
+    total_employees: employees.length,
+    by_status: {},
+    by_payroll_type: {},
+    by_employee_type: {},
+  };
+
+  for (const emp of employees) {
+    summary.by_status[emp.status] = (summary.by_status[emp.status] || 0) + 1;
+    if (emp.payroll_type) {
+      summary.by_payroll_type[emp.payroll_type] = (summary.by_payroll_type[emp.payroll_type] || 0) + 1;
+    }
+    if (emp.employee_type) {
+      summary.by_employee_type[emp.employee_type] = (summary.by_employee_type[emp.employee_type] || 0) + 1;
+    }
+  }
+
+  return {
+    store: storeInfo.code,
+    store_name: storeInfo.name,
+    summary,
+    employees,
+  };
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}

package/tools/payroll/index.js

@@ -0,0 +1,3 @@
+export { payrollDocumentsTool, handlePayrollDocuments } from './payroll-documents.js';
+export { payrollLinesTool, handlePayrollLines } from './payroll-lines.js';
+export { employeesTool, handleEmployees } from './employees.js';

package/tools/payroll/payroll-documents.js

@@ -0,0 +1,172 @@
+import { resolveStores } from '../../config/company-config.js';
+import { logger } from '../../utils/logger.js';
+
+export const payrollDocumentsTool = {
+  name: 'get_payroll_documents',
+  description:
+    'Lista documentos de nomina (headers) con filtros por periodo, tipo, status. Muestra totales por documento, cantidad de empleados, tasas de cambio. Soporta multi-tienda.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88', 'all'],
+        description: 'Tienda(s) a consultar.',
+      },
+      period_code: {
+        type: 'string',
+        description: "Filtrar por codigo de periodo exacto (ej: 'FQ88-2025-03-W10').",
+      },
+      payroll_type: {
+        type: 'string',
+        enum: ['SEMANAL', 'QUINCENAL', 'MENSUAL'],
+        description: 'Filtrar por tipo de nomina.',
+      },
+      status: {
+        type: 'string',
+        enum: ['Draft', 'Posted'],
+        description: 'Filtrar por status. Sin filtro = todos.',
+      },
+      start_date: {
+        type: 'string',
+        description: 'Fecha inicio (YYYY-MM-DD) para filtrar por documentDate.',
+      },
+      end_date: {
+        type: 'string',
+        description: 'Fecha fin (YYYY-MM-DD) para filtrar por documentDate.',
+      },
+      summary_only: {
+        type: 'boolean',
+        description: 'Solo resumen (sin lista de documentos). Default: false.',
+      },
+    },
+    required: ['store'],
+  },
+};
+
+export async function handlePayrollDocuments(bcClient, args) {
+  const storeParam = args.store;
+  if (!storeParam) throw new Error('Parametro requerido: store');
+
+  const stores = resolveStores(storeParam === 'all' ? null : [storeParam]);
+  const summaryOnly = args.summary_only || false;
+
+  if (stores.length === 1) {
+    return processStore(bcClient, stores[0], args, summaryOnly);
+  }
+
+  const results = await Promise.all(
+    stores.map((s) => processStore(bcClient, s, args, summaryOnly))
+  );
+
+  const consolidated = {
+    total_documents: 0,
+    total_employees_lines: 0,
+    total_net_usd: 0,
+    total_net_ves: 0,
+    by_status: { Draft: 0, Posted: 0 },
+    by_type: {},
+  };
+
+  for (const r of results) {
+    consolidated.total_documents += r.summary.total_documents;
+    consolidated.total_employees_lines += r.summary.total_employees_lines;
+    consolidated.total_net_usd += r.summary.total_net_usd;
+    consolidated.total_net_ves += r.summary.total_net_ves;
+    consolidated.by_status.Draft += r.summary.by_status.Draft || 0;
+    consolidated.by_status.Posted += r.summary.by_status.Posted || 0;
+    for (const [type, count] of Object.entries(r.summary.by_type)) {
+      consolidated.by_type[type] = (consolidated.by_type[type] || 0) + count;
+    }
+  }
+
+  consolidated.total_net_usd = round2(consolidated.total_net_usd);
+  consolidated.total_net_ves = round2(consolidated.total_net_ves);
+
+  return { stores: results, consolidated };
+}
+
+async function processStore(bcClient, storeInfo, args, summaryOnly) {
+  const companyId = storeInfo.companyId;
+
+  const filters = [];
+  if (args.period_code) filters.push(`periodCode eq '${args.period_code}'`);
+  if (args.payroll_type) filters.push(`payrollType eq '${args.payroll_type}'`);
+  if (args.status) filters.push(`status eq '${args.status}'`);
+  if (args.start_date) filters.push(`documentDate ge ${args.start_date}`);
+  if (args.end_date) filters.push(`documentDate le ${args.end_date}`);
+
+  const params = {
+    $select: 'documentNo,periodCode,payrollType,companyCode,documentDate,postingDate,paymentDate,status,lineCount,totalBonusesVES,totalBonusesUSD,totalNetUSD,totalNetVES,exchangeRate,createdBy,postedBy,createdDateTime,postedDateTime',
+    $orderby: 'documentDate desc',
+  };
+  if (filters.length > 0) params.$filter = filters.join(' and ');
+
+  const url = bcClient.buildPayrollApiUrl(companyId, 'fqPayrollDocuments', params);
+  const data = await bcClient.apiCallAllPages(url);
+
+  logger.info(`${storeInfo.code}: ${data.length} payroll documents`);
+
+  const summary = {
+    total_documents: data.length,
+    total_employees_lines: 0,
+    total_net_usd: 0,
+    total_net_ves: 0,
+    by_status: { Draft: 0, Posted: 0 },
+    by_type: {},
+  };
+
+  const documents = [];
+
+  for (const doc of data) {
+    const lineCount = doc.lineCount || 0;
+    const netUsd = doc.totalNetUSD || 0;
+    const netVes = doc.totalNetVES || 0;
+
+    summary.total_employees_lines += lineCount;
+    summary.total_net_usd += netUsd;
+    summary.total_net_ves += netVes;
+    summary.by_status[doc.status] = (summary.by_status[doc.status] || 0) + 1;
+    summary.by_type[doc.payrollType] = (summary.by_type[doc.payrollType] || 0) + 1;
+
+    if (!summaryOnly) {
+      documents.push({
+        document_no: doc.documentNo,
+        period_code: doc.periodCode,
+        payroll_type: doc.payrollType,
+        company_code: doc.companyCode,
+        document_date: doc.documentDate,
+        posting_date: doc.postingDate,
+        payment_date: doc.paymentDate,
+        status: doc.status,
+        line_count: lineCount,
+        total_bonuses_ves: round2(doc.totalBonusesVES || 0),
+        total_bonuses_usd: round2(doc.totalBonusesUSD || 0),
+        total_net_usd: round2(netUsd),
+        total_net_ves: round2(netVes),
+        exchange_rate: doc.exchangeRate || null,
+        created_by: doc.createdBy || null,
+        posted_by: doc.postedBy || null,
+        created_date_time: doc.createdDateTime || null,
+        posted_date_time: doc.postedDateTime || null,
+      });
+    }
+  }
+
+  summary.total_net_usd = round2(summary.total_net_usd);
+  summary.total_net_ves = round2(summary.total_net_ves);
+
+  const result = {
+    store: storeInfo.code,
+    store_name: storeInfo.name,
+    summary,
+  };
+
+  if (!summaryOnly) result.documents = documents;
+
+  return result;
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}

package/tools/payroll/payroll-lines.js

@@ -0,0 +1,128 @@
+import { resolveStores } from '../../config/company-config.js';
+import { logger } from '../../utils/logger.js';
+
+export const payrollLinesTool = {
+  name: 'get_payroll_lines',
+  description:
+    'Detalle de nomina por empleado para un documento especifico. Muestra bonos, pagos por metodo (cash VES, banco VES, cash USD), totales, y balance. Requiere document_no.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88'],
+        description: 'Tienda a consultar.',
+      },
+      document_no: {
+        type: 'string',
+        description: "Numero de documento de nomina (ej: 'FQ88-2025-03-W10-0001').",
+      },
+      employee_code: {
+        type: 'string',
+        description: 'Filtrar por codigo de empleado especifico.',
+      },
+      employee_search: {
+        type: 'string',
+        description: 'Busqueda parcial por nombre de empleado (case-insensitive, client-side).',
+      },
+    },
+    required: ['store', 'document_no'],
+  },
+};
+
+export async function handlePayrollLines(bcClient, args) {
+  const { store, document_no } = args;
+  if (!store) throw new Error('Parametro requerido: store');
+  if (!document_no) throw new Error('Parametro requerido: document_no');
+
+  const stores = resolveStores([store]);
+  const storeInfo = stores[0];
+  const companyId = storeInfo.companyId;
+
+  const filters = [`documentNo eq '${document_no}'`];
+  if (args.employee_code) filters.push(`employeeCode eq '${args.employee_code}'`);
+
+  const url = bcClient.buildPayrollApiUrl(companyId, 'fqPayrollLines', {
+    $filter: filters.join(' and '),
+    $select: 'documentNo,lineNo,employeeCode,employeeName,cedulaDeIdentidad,transportBonusVES,productivityBonusUSD,extraRedobleUSD,specialDateBonusUSD,foodBonusUSD,payCashVES,payBankVES,payCashUSD,totalBonusesVES,totalBonusesUSD,totalPayVES,totalPayUSD,balanceDifference',
+    $orderby: 'lineNo',
+  });
+
+  const data = await bcClient.apiCallAllPages(url);
+  logger.info(`${storeInfo.code}: ${data.length} payroll lines for ${document_no}`);
+
+  let lines = data.map((line) => ({
+    document_no: line.documentNo,
+    line_no: line.lineNo,
+    employee_code: line.employeeCode,
+    employee_name: line.employeeName,
+    cedula: line.cedulaDeIdentidad || null,
+    bonuses: {
+      transport_ves: round2(line.transportBonusVES || 0),
+      productivity_usd: round2(line.productivityBonusUSD || 0),
+      extra_redoble_usd: round2(line.extraRedobleUSD || 0),
+      special_date_usd: round2(line.specialDateBonusUSD || 0),
+      food_usd: round2(line.foodBonusUSD || 0),
+    },
+    payments: {
+      cash_ves: round2(line.payCashVES || 0),
+      bank_ves: round2(line.payBankVES || 0),
+      cash_usd: round2(line.payCashUSD || 0),
+    },
+    total_bonuses_ves: round2(line.totalBonusesVES || 0),
+    total_bonuses_usd: round2(line.totalBonusesUSD || 0),
+    total_pay_ves: round2(line.totalPayVES || 0),
+    total_pay_usd: round2(line.totalPayUSD || 0),
+    balance_difference: round2(line.balanceDifference || 0),
+  }));
+
+  // Client-side name search
+  if (args.employee_search) {
+    const search = args.employee_search.toLowerCase();
+    lines = lines.filter((l) => l.employee_name && l.employee_name.toLowerCase().includes(search));
+  }
+
+  // Summary totals
+  const summary = {
+    document_no,
+    total_employees: lines.length,
+    total_bonuses_ves: 0,
+    total_bonuses_usd: 0,
+    total_pay_ves: 0,
+    total_pay_usd: 0,
+    total_cash_ves: 0,
+    total_bank_ves: 0,
+    total_cash_usd: 0,
+    employees_with_balance_diff: 0,
+  };
+
+  for (const line of lines) {
+    summary.total_bonuses_ves += line.total_bonuses_ves;
+    summary.total_bonuses_usd += line.total_bonuses_usd;
+    summary.total_pay_ves += line.total_pay_ves;
+    summary.total_pay_usd += line.total_pay_usd;
+    summary.total_cash_ves += line.payments.cash_ves;
+    summary.total_bank_ves += line.payments.bank_ves;
+    summary.total_cash_usd += line.payments.cash_usd;
+    if (Math.abs(line.balance_difference) > 0.01) summary.employees_with_balance_diff++;
+  }
+
+  summary.total_bonuses_ves = round2(summary.total_bonuses_ves);
+  summary.total_bonuses_usd = round2(summary.total_bonuses_usd);
+  summary.total_pay_ves = round2(summary.total_pay_ves);
+  summary.total_pay_usd = round2(summary.total_pay_usd);
+  summary.total_cash_ves = round2(summary.total_cash_ves);
+  summary.total_bank_ves = round2(summary.total_bank_ves);
+  summary.total_cash_usd = round2(summary.total_cash_usd);
+
+  return {
+    store,
+    store_name: storeInfo.name,
+    summary,
+    lines,
+  };
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}