@fullqueso/mcp-bc-gastos 1.28.0 → 1.33.0

package/.env.example

@@ -17,3 +17,10 @@ BC_COMPANY_FQFR=guid-for-franquicias
 
 # Optional
 LOG_LEVEL=info
+
+# Per-request BC fetch timeout (ms). A hung request is aborted + retried instead
+# of blocking the MCP forever (BUG #1 fix). Default 90000. Raise for heavy reports.
+BC_FETCH_TIMEOUT_MS=90000
+
+# CRM rate endpoint (get_crm_rate) — opcional, default abajo
+CRM_RATE_BASE=https://crm-rate.fullqueso.com/api/v1

package/CHANGELOG.md

@@ -1,5 +1,132 @@
 # CHANGELOG
 
+## [1.33.0] — 2026-07-11
+
+### Added — `get_income_statement`: estado de resultados en formato Power BI (Level 1)
+Nuevo tool en `tools/financials/income-statement.js`. READ-ONLY.
+
+- **Qué expone:** el reporte "Income Statement by Month" de Power BI (G/L Account **Level 1**)
+  para una tienda y un mes, agregando los General Ledger entries por cuenta level-1 con la
+  convención de signos de Power BI (`amount = debitAmount − creditAmount` → ingresos negativos,
+  costos/gastos positivos, Total negativo = ganancia). Devuelve las 3 secciones (40001/50001/60001),
+  cuentas level-1, totales, Total general y un **`accounts_map`** listo para el generador Excel
+  del skill-fq-resultados-mensual (`data.json`). Con `level=2` incluye las cuentas de posteo
+  hijas con su nombre real de BC.
+- **Por qué:** resuelve las fronteras que `get_financial_statements` (agrega por categoría) no
+  separa: nómina **71000** vs impuestos **74000**, y otros **74000** (80xxx) vs **90000** (9xxxx).
+  Trabaja desde los entries por cuenta, así que cuadra 1:1 con Power BI.
+- **Estructura level-1** embebida (`COA_PBI`) — fuente: screenshots Power BI FQ28, CoA compartido
+  FQ01/FQ28/FQ88. Espejo de `skill-fq-resultados-mensual/references/income_statement_coa.json`.
+- **Nuevo en bc-client:** `getChartOfAccountNames(companyId)` (entidad BC `accounts`, cache por
+  companyId) para etiquetar las cuentas hijas en level 2.
+- **Test:** `tests/test-income-statement.js` (agregación pura con GL entries mock, sin BC):
+  valida signos, mapeo por rangos, fronteras 71000/74000 y 74000/90000, totales y level 2.
+- La columna **Ajustado** (drafts como posteados) y la reclasificación de dividendos las agrega
+  el skill sobre el `posted` — el MCP entrega solo el posted objetivo del GL.
+
+## [1.32.1] — 2026-07-04
+
+### Docs — README "Tools" regenerado desde el código (22 stale → 57 reales)
+- **`scripts/generate-tools-doc.mjs`**: importa dinámicamente todos los `*Tool` de
+  `tools/**/*.js` (incluye definiciones en `index.js`, dedup por `name`), agrupa por
+  categoría y reescribe la sección `## Tools (N)` del README. Verificado 57/57 contra
+  el switch de `server.js`. Uso: `node scripts/generate-tools-doc.mjs --write`
+  (sin flag = dry-run a stdout). La sección queda marcada como autogenerada.
+
+## [1.32.0] — 2026-07-04
+
+### Added — `get_unposted_invoices`: facturas sin postear para Cierre Parcial
+Nuevo tool en el cluster de draft visibility (`tools/multi-payment/unposted-invoices.js`).
+Verificado contra BC real (mayo 2026, 4 empresas). READ-ONLY.
+
+- **Qué expone:** facturas de compra y venta con `status` `Draft`/`In Review` en
+  `api/v2.0` `purchaseInvoices`/`salesInvoices` — documentos que NO están en el GL.
+  Complementa a `get_draft_payables`/`receivables`/`summary`, que son Multi-Payments
+  (settlement) sobre facturas ya posteadas y por tanto no sirven como ajuste P&L.
+- **Para qué:** ajuste de CIERRE PARCIAL del P&L en `skill-fq-resultados-mensual`
+  (compras draft → +costo/gasto; ventas draft no-IC → +ingreso). Cada tienda incluye
+  `pl_adjustment_hint` con los montos listos.
+- **Params:** `store` (incl. `all`), `type` (purchases|sales|both), `start_date`/`end_date`
+  (filtro por `postingDate`), `include_in_review` (default true), `summary_only`.
+- **Multi-moneda correcto:** totales SIEMPRE por moneda (`by_currency`,
+  `non_ic_by_currency`, consolidado por moneda) — nunca se suman VES con USD.
+  `LCY` = USD; VES se convierte aguas arriba con `get_exchange_rate`.
+- **Ventas IC:** separa clientes `IC-*` (`intercompany`) del total ajustable.
+- **Smoke test:** `tests/test-unposted-invoices.js` (store y mes por CLI).
+- Hallazgo del estreno (mayo 2026): FQ01 11 compras sin postear (Bs 1,838,737.54),
+  FQ28 4 (Bs 1,210,031.04), FQFR 2 ($7,116.50), FQ01 1 venta IC (Bs 165,456.04).
+
+## [1.31.0] — 2026-07-01
+
+### Added — KPIs de nómina operativa: tienda vs eventos, activos vs pagados
+Contratos existentes intactos (solo se agregan campos). Todo USD. Verificado contra BC real (mayo 2026, FQ01/FQ28/FQ88/FQFR).
+
+- **`paid_employees` en `get_payroll_documents` (con `include_employee_count=true`).** Además de `summary.unique_employees`, ahora `summary.paid_employees`: lista agregada por empleado en el período con `{ employee_code, employee_name, cedula, cost_usd, lines, payroll_types:[...], classification }`. Permite cruzar activos vs pagados sin leer las líneas doc por doc.
+- **Deduplicación por cédula.** `unique_employees` y `paid_employees` deduplican por `cedula` cuando existe (una persona puede tener un código SEMANAL y otro EVENTO → se consolidan costo y líneas en un registro). `summary.duplicate_codes: [{ cedula, codes:[...] }]` expone los casos multi-código para limpieza en BC. Si `cedula` es null se trata el código como persona única (no se fusiona por nombre). El consolidado (`store="all"`) re-deduplica también entre tiendas (misma cédula en dos tiendas = una persona).
+  - Resolución de cédula en 2 pasos: si un código tiene cédula en alguna línea, las líneas con cédula en blanco de ese código heredan la cédula (evita partir un código en dos personas). Verificado mayo 2026: 0 splits, 0 merges; 82 personas = 58 con cédula (1:1) + 24 códigos sin cédula en BC (data-quality, tratados como únicos).
+- **Clasificación evento/operativo por empleado** (relevante FQ01): `classification` = `"evento"` (todos sus pagos EVENTO), `"operativo"` (ningún EVENTO — SEMANAL/VACACIONES/LIQUIDACION), `"mixto"` (tiene EVENTO y no-EVENTO). Evita marcar como "inactivo no declarado" a quien solo trabaja eventos.
+- **Buckets de nómina tienda vs eventos** en `summary` (per-store y consolidado): `store_payroll` = Σ `cost_usd` de docs SEMANAL + VACACIONES + LIQUIDACION; `event_payroll` = Σ EVENTO. `total_cost_usd` se mantiene igual (gerencia queda solo ahí). Constantes `STORE_PAYROLL_TYPES`/`EVENT_PAYROLL_TYPES` en `tools/payroll/cost-model.js`.
+
+### Added — Denominador de ventas correcto para el KPI (get_sales_analysis / compare_sales_by_store)
+- **`revenue_store`, `revenue_events`, `revenue_intercompany`, `revenue_non_sales` + `revenue_total`** en `summary` (y por tienda en `compare_sales_by_store`), además del `total_revenue_usd` actual (sin cambios). Identidad: `revenue_total = revenue_store + revenue_intercompany + revenue_events + revenue_non_sales`.
+- **`revenue_store = revenue_total − intercompañía − eventos − no-venta`.** Se excluye del denominador de tienda la venta intercompañía, la venta de eventos y el ingreso **no-venta** (FX gains + rebajas de compra) — este último por recomendación aceptada por FP.
+- **Cuentas configurables (no inline), por tienda** en `config/income-accounts.js`, verificadas contra el CoA real:
+  - `INTERCOMPANY_REVENUE_ACCOUNTS = ['40310']` (tiendas operativas; FQ01/FQ88, FQ28=0).
+  - `EVENT_REVENUE_ACCOUNTS = ['40180','40700']` (solo FQ01 con movimiento).
+  - `NON_SALES_REVENUE_ACCOUNTS = ['40580','40540','40550']` (dif. cambiario + descuentos/rebajas de compra).
+  - **FQFR** usa `FQFR_INTERCOMPANY_REVENUE_ACCOUNTS = ['40420','40430','40660','40930']` (royalties/fees del master de franquicia, NO 40310) vía `getRevenueClassification(storeCode)` → sus buckets salen correctos aunque el KPI no aplique.
+  - Lógica en `splitRevenueBuckets(glRevenue, total, storeCode)` (`utils/sales-aggregation.js`); `calculateSummary` ahora recibe `storeCode` (los dos tools de ventas lo pasan por tienda).
+- **KPI** (lo calcula el consumidor cruzando ambos tools): `nomina_tienda_pct = store_payroll / revenue_store`; `nomina_eventos_pct = event_payroll / revenue_events` (**null si `revenue_events = 0`** → solo FQ01). **FQFR excluido por completo** del KPI (`KPI_PAYROLL_STORES = ['FQ01','FQ28','FQ88']`).
+  - Verificado mayo 2026 (2 fases, `tests/verify-payroll-sales-kpi.js`):
+    - **Estricto** (− interco − eventos), coincide con la validación de FP: FQ01 8.36% tienda / 31.02% eventos (rev_store 86,987.43); FQ28 10.22% (77,407.51); FQ88 8.75% (150,122.32).
+    - **Refinado** (además − no-venta): FQ01 8.36% (86,940.37); FQ28 10.25% (77,146.08); FQ88 8.80% (149,322.16).
+
+### Nota operativa
+- **Reiniciar Claude Desktop** tras el publish para que los tools recarguen (G-002).
+
+---
+
+## [1.30.0] — 2026-07-01
+
+### Fixed
+- **BUG #1 — `get_employees`/`get_payroll_documents` con `store="all"` podían colgar el MCP indefinidamente.** Causa raíz: `fetch()` no tenía timeout → una sola petición colgada nunca resolvía, y como el consolidado usaba `Promise.all`, una tienda colgada tumbaba todo el call (aparecía como "MCP no responde").
+  - **`lib/bc-client.js` — timeout por petición (AbortController).** Cada intento de `fetchWithRetry` aborta a los `BC_FETCH_TIMEOUT_MS` (default **90000**, env-tunable) y reintenta; al agotar reintentos lanza un error claro de timeout en vez de colgarse. Cubre token + todas las llamadas v2.0/OData/custom (afecta a las 54 tools; el default generoso no toca ninguna llamada legítima — todas las observadas <1s).
+  - **Consolidación multi-tienda resiliente.** `get_payroll_documents` y `get_employees` con `store="all"` ahora usan `Promise.allSettled`: una tienda que falle/timeoutee devuelve data parcial + un array `errors[]` por tienda, nunca cuelga ni bota el consolidado.
+  - Verificado: per-store discovery <500ms; el timeout aborta+reintenta (3x) y lanza error en ~6s con `BC_FETCH_TIMEOUT_MS=1`.
+
+### Changed / Added — KPIs de nómina operativa
+- **#2/#3 — Costo total en USD por documento (`total_cost_usd`) robusto a drafts sin distribuir.** Nuevo módulo `tools/payroll/cost-model.js` como **fuente única de verdad del costo**. Regla (verificada contra 448 docs reales): `total_cost_usd = totalGrossUSD (>0) → si no, bonos-equivalente USD → si no, neto (MAX, no suma)`. El campo `cost_basis` (`gross`|`bonuses`|`net`) hace auditable de dónde salió el número, y `net_distributed:false` marca los drafts cuyo neto aún no se reparte por método de pago (elimina el parche `max(neto,bonos)`).
+  - **Por qué la suma `net_usd + net_ves/tasa` estaba mal:** VACACIONES/LIQUIDACION contabilizan el MISMO monto en `totalNetUSD` **y** `totalNetVES` → esa suma **duplica** el costo. `totalGrossUSD` es el costo real y ya está en el header (antes no se seleccionaba).
+  - Expuestos en cada documento: `total_cost_usd`, `cost_basis`, `net_distributed`, `total_gross_usd`, `total_deductions_usd`. Agregado `total_cost_usd` a `summary` y `consolidated`.
+- **#4 — Enums de `payroll_type` corregidos a los valores reales de BC + `exclude_managerial`.** El enum viejo `[SEMANAL|QUINCENAL|MENSUAL]` estaba mal (QUINCENAL/MENSUAL no existen).
+  - `get_payroll_documents`: `SEMANAL, GERENCIAL, GERENCIAL_CIERRE, EVENTO, VACACIONES, LIQUIDACION`. Nuevo flag `exclude_managerial` → excluye GERENCIAL + GERENCIAL_CIERRE server-side (nómina operativa en un solo call).
+  - `get_employees`: `SEMANAL, GERENCIAL, EVENTO`. Nuevo flag `exclude_managerial` → excluye `payrollType GERENCIAL` + `employeeType Management`.
+- **#5 — `summary.by_type` ahora trae costo, no solo conteo.** De `{ TIPO: n }` a `{ TIPO: { count, lines, cost_usd } }` (per-store y consolidado).
+- **#6 — Headcount único de empleados pagados en el periodo.** Nuevo flag `include_employee_count` en `get_payroll_documents` → `summary.unique_employees` (y `consolidated.unique_employees`). Lee las líneas de los docs filtrados en lotes de OR (no doc-por-doc). Distingue el headcount real de `total_employees_lines` (que duplica al mismo empleado por cada corrida semanal).
+- **#7 — Costo por empleado en USD en `get_payroll_lines`.** Expuesto `total_ves_equivalent` (campo de la API antes sin usar) y `cost_usd` por línea = `totalVESEquivalent / tasa` (la tasa se lee del header en 1 llamada extra). `summary` trae `total_cost_usd`, `total_ves_equivalent`, `payroll_type`, `status`, `exchange_rate`.
+  - **Nota (L-001):** la API `fqPayrollLines` **no** expone días/horas trabajados ni FTE por línea → no se pueden calcular KPIs de productividad laboral sin ampliar la extensión de BC. Documentado, no fabricado.
+
+### Nota operativa
+- **Reiniciar Claude Desktop** tras el publish para que los tools recarguen (G-002).
+
+---
+
+## [1.29.0] — 2026-06-21
+
+### Added
+- **`get_crm_rate` — tasa de cambio Bs/USD desde el CRM de Full Queso (tasa de referencia, hora Caracas).** Complementa a `get_exchange_rate` (que trae la tasa BCV contable vigente en BC): este tool consulta el endpoint del CRM `https://crm-rate.fullqueso.com` y expone tanto la tasa **USDT/Binance** (paralelo) como la **BCV** (oficial), histórica o del día.
+  - **Dos monedas con sinónimos:** `coin` acepta `USDT`/`BINANCE` (paralelo, mismo valor) y `VES`/`BCV` (oficial). La descripción dispara con "tasa USDT, tasa Binance, dólar Binance, tasa paralelo/paralela, tasa BCV, tasa oficial, tasa del día, tasa histórica".
+  - **Histórica vs del día automático:** con `date` (YYYY-MM-DD) → `GET /api/v1/history/price?coin={VES|USDT}&date=...`; sin `date` → `GET /api/v1/coin/{bcv|usdt}` (momento de la consulta).
+  - Maneja `400` (coin/date inválidos → error claro), `404` (sin registro → `price: null` + mensaje) y fallo de conexión. Precio redondeado a 2 decimales; respuesta incluye `queried_at_caracas` y `source`.
+  - Base URL configurable vía env **`CRM_RATE_BASE`** (default `https://crm-rate.fullqueso.com/api/v1`). El endpoint no requiere auth de BC → tool autónomo (ignora `bcClient`).
+  - Nuevo `tools/get-crm-rate.js`; registrado en `server.js` (import + lista de tools + switch).
+  - **Verificado contra el endpoint real (21-jun-2026):** USDT del día ≈798.35; BCV del día 612.43; histórica USDT 19-jun 805.40; histórica VES 19-jun **607.39** (coincide con el ejemplo del doc); 404 (1990) y coin inválido (DOGE) manejados. `node --check` OK.
+
+### Nota operativa
+- **Reiniciar Claude Desktop** tras el publish para que el tool recargue (G-002).
+
+---
+
 ## [1.28.0] — 2026-06-12
 
 ### Added

package/README.md

@@ -52,111 +52,264 @@ cp .env.example .env
 npm start
 ```
 
-## Tools (22)
+## Tools (58)
 
-### Expense Analysis (5 tools)
+_Sección generada por `scripts/generate-tools-doc.mjs` — no editar a mano._
+_Regenerar con: `node scripts/generate-tools-doc.mjs --write`_
 
-#### get_expense_analysis
-Detailed expense analysis by category with account-level detail and benchmark comparisons.
-- Params: `stores`, `period`, `month`, `start_date`, `end_date`
-
-#### get_efficiency_ratios
-Financial ratios: expense-to-income, payroll, rent, utilities, marketing, operating margin.
-- Params: `stores`, `period`, `month`, `start_date`, `end_date`
+### Expense Analysis & Core (11 tools)
 
 #### compare_stores
-Compare all stores with efficiency rankings, variances, and savings opportunities.
+Compara la eficiencia de gastos entre las tiendas de Full Queso (FQ01 Chacao, FQ28 Marqués, FQ88 Candelaria).
 - Params: `period`, `month`, `start_date`, `end_date`
 
 #### detect_anomalies
-Detect expense anomalies with severity levels, root causes, and recommended actions.
-- Params: `stores`, `period`, `month`, `start_date`, `end_date`
+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.
+- Params: `period`, `month`, `start_date`, `end_date`, `stores`, `sensitivity`
 
-#### get_trends
-Historical trend analysis (up to 6 months) with growth rates, seasonality, and ASCII charts.
-- Params: `store`, `months`
+#### get_account_transactions
+Listado completo de transacciones para una cuenta contable específica con balance running y nombre de proveedor.
+- Params: `account_number`*, `store`*, `start_date`*, `end_date`*
 
-### Drill-Down & Vendors (4 tools)
+#### get_crm_rate
+Obtiene la tasa de cambio Bs/USD desde el CRM de Full Queso (hora Caracas).
+- Params: `coin`*, `date`
+
+#### get_efficiency_ratios
+Calcula ratios de eficiencia financiera de Full Queso: gastos/ingresos, nómina/ingresos, alquiler/ingresos, servicios/ingresos, marketing/ingresos y margen operativo.
+- Params: `period`, `month`, `start_date`, `end_date`, `stores`
+
+#### get_exchange_rate
+Obtiene la tasa de cambio USD → VES desde Business Central.
+- Params: `store`*, `date`, `start_date`, `end_date`
+
+#### get_expense_analysis
+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.
+- Params: `period`, `month`, `start_date`, `end_date`, `stores`
 
 #### get_expense_details
-Transaction-level drill-down with vendor lookup, category/account filters, and pagination.
-- Params: `store` (req), `period`, `month`, `start_date`, `end_date`, `category`, `account_number`, `min_amount`, `vendor_search`, `limit`, `offset`
+Drill-down de transacciones individuales de gastos operacionales.
+- Params: `store`*, `period`, `month`, `start_date`, `end_date`, `category`, `account_number`, `min_amount`, `vendor_search`, `limit`, `offset`
 
-#### get_account_transactions
-Per-account ledger with running balance and vendor information.
-- Params: `account_number` (req), `store` (req), `start_date` (req), `end_date` (req)
+#### get_trends
+Análisis de tendencias históricas de gastos e ingresos de Full Queso.
+- Params: `months`, `store`
 
 #### get_vendor_transactions
-All transactions for a vendor (partial name search) with account breakdown.
-- Params: `store` (req), `vendor_search` (req), `start_date` (req), `end_date` (req)
+Todas las transacciones de gastos operacionales de un proveedor específico.
+- Params: `store`*, `vendor_search`*, `start_date`*, `end_date`*
 
 #### list_vendors
-Directory of active vendors ordered by total amount paid.
-- Params: `store` (req), `start_date`, `end_date`
+Lista todos los proveedores activos de una tienda en un periodo, con monto total pagado y número de transacciones.
+- Params: `store`*, `start_date`, `end_date`
+
+### Auditoría / POS Reconciliation (11 tools)
 
-### Bank Reconciliation (7 tools)
+#### find_potential_matches
+Para una línea no conciliada del banco, busca posibles correspondencias en las entradas contables de BC por monto, fecha y descripción.
+- Params: `store`*, `bank_account`*, `statement_amount`*, `transaction_date`*, `description`, `date_tolerance_days`, `amount_tolerance_pct`
 
-> These tools use OData V4 Web Services. Amounts in VES. Read-only.
+#### get_bank_ledger_entries
+Todos los movimientos del libro de banco (abiertos y cerrados) para una cuenta bancaria.
+- Params: `store`*, `bank_account`*, `date_from`*, `date_to`*, `open_only`
 
-#### list_bank_accounts
-List active bank accounts for a store.
-- Params: `store` (req)
+#### get_bank_reconciliation_report
+Reporte consolidado de reconciliación bancaria: progreso de todos los statements abiertos, líneas no conciliadas (débitos y créditos por separado), y sugerencias de asientos contables para débitos.
+- Params: `store`*, `bank_account`*, `statement_no`, `month`, `min_amount`, `include_suggestions`, `save_to_file`, `excel_output`
+
+#### get_gl_account_entries
+Movimientos del libro mayor (G/L) para una cuenta específica.
+- Params: `store`*, `gl_account`*, `date_from`*, `date_to`*
+
+#### get_pm_receipts
+Recibos de Pago Móvil (PM) registrados en BC para una cuenta bancaria.
+- Params: `store`*, `bank_account`*, `date_from`*, `date_to`*
 
 #### get_reconciliation_status
-Open reconciliation summary: matched vs unmatched lines per bank account.
-- Params: `store` (req), `bank_account`
+Resumen del estado de reconciliaciones bancarias abiertas: total líneas, conciliadas, pendientes y diferencia.
+- Params: `store`*, `bank_account`
+
+#### get_unmatched_ledger_entries
+Entradas contables del banco en BC sin correspondencia en el estado de cuenta.
+- Params: `store`*, `bank_account`*, `date_from`, `date_to`
 
 #### get_unmatched_statement_lines
-Bank statement lines not reconciled with BC, categorized by type (payments/deposits).
-- Params: `store` (req), `bank_account` (req), `statement_no`, `min_amount`, `type_filter`
+Líneas del estado de cuenta bancario NO conciliadas con entradas en BC.
+- Params: `store`*, `bank_account`*, `statement_no`, `min_amount`, `type_filter`
 
-#### get_unmatched_ledger_entries
-BC ledger entries not cleared at the bank, with stale entry detection (>30 days).
-- Params: `store` (req), `bank_account` (req), `date_from`, `date_to`
+#### list_bank_accounts
+Lista las cuentas bancarias de una tienda Full Queso.
+- Params: `store`*
 
-#### find_potential_matches
-Scoring-based match finder (0-100) for unmatched bank lines against BC entries.
-- Params: `store` (req), `bank_account` (req), `statement_amount` (req), `transaction_date` (req), `description`, `date_tolerance_days`, `amount_tolerance_pct`
+#### reconcile_pos_sales
+Conciliación automática de ventas POS: cruza montos bancarios de BC (BankAccountLedgerEntries) con liquidaciones bancarias por número de lote, agrupa por liquidación bancaria (settlement batches), calcula comisiones reales.
+- Params: `store`*, `start_date`*, `end_date`*, `bank_account`
 
 #### suggest_journal_entries
-Suggest GL journal entries for unreconciled bank payments using keyword matching and historical patterns.
-- Params: `store` (req), `bank_account` (req), `statement_no`, `auto_categorize`
+Para pagos del banco sin correspondencia en BC, sugiere asientos contables basándose en la descripción y patrones históricos.
+- Params: `store`*, `bank_account`*, `statement_no`, `auto_categorize`
 
-#### reconcile_pos_sales
-Multi-bank POS sales reconciliation. Matches bank deposits against BC lot records with commission tracking.
-- **Banesco**: lot-based matching, commission netted in deposit
-- **Bancrecer**: lot-based with separate commission/ISLR lines
-- **BDV**: aggregate matching by period totals (no lot numbers)
-- **UBII**: cross-account matching (BC virtual account → Bancrecer/BDV deposits)
-- Params: `store` (req), `start_date` (req), `end_date` (req), `bank_account`
+### Cierre Mensual Bancario (6 tools)
+
+#### generate_closing_journal
+Genera el EXCEL del CIERRE MENSUAL bancario (mes completo, multi-banco).
+- Params: `store`*, `month`*, `output_dir`, `allow_partial`, `strict`
 
-### Accounts Receivable & Payable (6 tools)
+#### get_closing_match_results
+CIERRE MENSUAL bancario: vista paginada de las 4 listas con auto-clasificación.
+- Params: `store`*, `month`*, `list`, `bank_account`, `category`, `source`, `confidence`, `min_abs_amount_ves`, `sort`, `limit`, `offset`
 
-> These tools use the Finance Reports Beta API. Amounts in VES and USD. Read-only.
+#### get_closing_questionnaire
+CIERRE MENSUAL bancario: vista paginada/filtrada de las entradas del cuestionario del MES.
+- Params: `store`*, `month`*, `bucket`, `counterparty_no`, `bank_account`, `status_filter`, `min_abs_amount_ves`, `min_abs_amount_usd`, `limit`, `offset`, `sort`, `pair_by_amount`, `pair_tolerance_pct`, `pair_max_days`, `description_regex`
+
+#### reconcile_closing_with_bc
+CIERRE MENSUAL bancario: refresca el estado contra BC para detectar drift desde la última corrida.
+- Params: `store`*, `month`*
+
+#### start_month_closing
+CIERRE MENSUAL bancario (mes completo, multi-banco) en Business Central.
+- Params: `store`*, `month`, `force_refresh`
+
+#### submit_closing_answers
+CIERRE MENSUAL bancario: registra respuestas/aprobaciones al cuestionario del MES.
+- Params: `store`*, `month`*, `user`, `answers`*
+
+### Cobranzas (AR / AP) (7 tools)
+
+#### get_collection_status
+Verificación rápida del estado de cobranza de un período específico.
+- Params: `store`*, `start_date`*, `end_date`*
 
 #### get_customer_balances
-Customers with outstanding balances.
-- Params: `store` (req), `only_with_balance`, `customer_number`
+Lista clientes con saldos pendientes, montos vencidos y estado de cobranza.
+- Params: `store`*, `only_with_balance`, `customer_number`
 
 #### get_customer_ledger
-Customer transaction history: invoices, payments, credit memos with collection rate.
-- Params: `store` (req), `start_date` (req), `end_date` (req), `customer_number`, `document_type`, `open_only`
+Movimientos del libro mayor de clientes: facturas emitidas, pagos recibidos, notas de crédito.
+- Params: `store`*, `start_date`*, `end_date`*, `customer_number`, `document_type`, `open_only`
 
-#### get_open_receivables
-Open accounts receivable by customer with aging buckets (0-30, 31-60, 61-90, 90+).
-- Params: `store` (req), `as_of_date`, `customer_number`, `min_amount`
+#### get_customer_list
+Lista de clientes con número, nombre y RIF (taxRegistrationNumber).
+- Params: `store`*, `customer_number`
 
-#### get_collection_status
-Period collection completeness: "Were all December invoices collected?"
-- Params: `store` (req), `start_date` (req), `end_date` (req)
+#### get_open_payables
+Resumen de todas las cuentas por pagar abiertas.
+- Params: `store`*, `as_of_date`, `vendor_number`, `min_amount`
+
+#### get_open_receivables
+Resumen rápido de todas las cuentas por cobrar abiertas.
+- Params: `store`*, `as_of_date`, `customer_number`, `min_amount`
 
 #### get_vendor_ledger
-Vendor transaction history: bills received, payments made.
-- Params: `store` (req), `start_date` (req), `end_date` (req), `vendor_number`, `document_type`, `open_only`
+Movimientos del libro mayor de proveedores: facturas recibidas, pagos realizados, notas de crédito.
+- Params: `store`*, `start_date`*, `end_date`*, `vendor_number`, `document_type`, `open_only`
 
-#### get_open_payables
-Open accounts payable by vendor with aging buckets (0-30, 31-60, 61-90, 90+).
-- Params: `store` (req), `as_of_date`, `vendor_number`, `min_amount`
+### Financial Statements & Cash Flow (3 tools)
+
+#### get_cash_flow
+Free Cash Flow (FCF) por método indirecto para una o más tiendas Full Queso (FQ01, FQ28, FQ88).
+- Params: `stores`, `period`, `month`, `start_date`, `end_date`, `compare_previous`, `include_cash_position`, `render_html`, `output_path`, `open_browser`, `inline_html`
+
+#### get_financial_statements
+Estado financiero completo (P&L / Profit & Loss) para una o más tiendas Full Queso (FQ01, FQ28, FQ88, FQFR) en un período.
+- Params: `stores`, `period`, `month`, `start_date`, `end_date`, `render_html`, `compare_previous`, `output_path`, `open_browser`, `inline_html`
+
+#### get_income_statement
+Estado de resultados (Income Statement) en el formato EXACTO del reporte Power BI "Income Statement by Month" (G/L Account Level 1) para una tienda Full Queso (FQ01, FQ28, FQ88) y un mes.
+- Params: `store`, `stores`, `period`, `month`, `start_date`, `end_date`, `level`
+
+### Inventario (7 tools)
+
+#### get_inventory_by_location
+Inventario desglosado por ubicación (Location Code) dentro de una tienda.
+- Params: `store`*, `location_code`, `item_category`, `classification`, `as_of_date`
+
+#### get_inventory_change
+Cambio de inventario WoW (semana) o MoM (mes).
+- Params: `store`*, `period`*, `periods_back`, `item_category`, `classification`
+
+#### get_inventory_levels
+Niveles de inventario agrupados por itemCategoryCode y/o inventoryPostingGroupCode (congelados, importado, local).
+- Params: `store`*, `item_category`, `classification`, `as_of_date`
+
+#### get_item_card
+Datos maestros de ítems de inventario: unitCost (BC), calculated_unit_cost (real desde últimas entradas), inventory qty, unitPrice, categoría.
+- Params: `store`*, `item_number`, `item_search`, `item_category`
+
+#### get_item_cost_analysis
+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.
+- Params: `store`*, `item_number`*, `months`
+
+#### get_item_cost_trend
+Tendencia de costo de ítems: compara weighted avg inbound cost de últimas 2 semanas vs últimas 4 semanas.
+- Params: `store`*, `item_number`, `item_category`, `period_days`
+
+#### get_item_ledger_entries
+Entradas del libro de artículos (Item Ledger Entries) — historial de movimientos de inventario con costo real por entrada.
+- Params: `store`*, `item_number`*, `entry_type`, `start_date`, `end_date`, `top`
+
+### Draft Visibility (Multi-Payments + facturas sin postear) (4 tools)
+
+#### get_draft_payables
+Muestra facturas de compra abiertas clasificadas en tres niveles: totalmente pendientes (sin documento de pago), con Purch.
+- Params: `store`*, `status_filter`, `vendor_number`, `include_lines`, `report`, `summary_only`, `save_to_file`, `excel_output`
+
+#### get_draft_receivables
+Muestra facturas de venta abiertas clasificadas en tres niveles: totalmente pendientes (sin documento de cobro), con Multi-Payment en borrador (Open o Transferred), y el monto neto realmente sin cubrir.
+- Params: `store`*, `status_filter`, `customer_number`, `include_lines`, `report`, `summary_only`, `save_to_file`, `excel_output`
+
+#### get_draft_summary
+Resumen ejecutivo consolidado de todos los Multi-Payments en borrador (Open y Transferred) para una o todas las tiendas.
+- Params: `store`*
+
+#### get_unposted_invoices
+Facturas de compra y/o venta SIN POSTEAR en Business Central (status Draft o In Review).
+- Params: `store`*, `type`, `start_date`, `end_date`, `include_in_review`, `summary_only`
+
+### Nómina (3 tools)
+
+#### get_employees
+Lista empleados de una tienda con datos de nomina: tipo, status, salarios base, bonos predeterminados, fechas.
+- Params: `store`*, `status`, `payroll_type`, `exclude_managerial`, `employee_search`, `employee_code`
+
+#### get_payroll_documents
+Lista documentos de nomina (headers) con filtros por periodo, tipo, status.
+- Params: `store`*, `period_code`, `payroll_type`, `exclude_managerial`, `status`, `start_date`, `end_date`, `include_employee_count`, `summary_only`
+
+#### get_payroll_lines
+Detalle de nomina por empleado para un documento.
+- Params: `store`*, `document_no`*, `employee_code`, `employee_search`
+
+### Reports (2 tools)
+
+#### generate_cxp_report
+Genera reporte Excel de Cuentas por Pagar con 3 hojas: Sin Draft, Draft No Posteado, Pago Parcial + hoja Resumen con desglose por proveedor.
+- Params: `store`*, `output_path`
+
+#### generate_manager_report
+Genera el Reporte Gerente HTML completo para una tienda FQ.
+- Params: `store`*, `date`, `output_path`, `open_browser`, `payroll_days`
+
+### Ventas (4 tools)
+
+#### compare_sales_by_store
+Comparación de rendimiento de VENTAS entre las tiendas de Full Queso (FQ01 Chacao, FQ28 Marqués, FQ88 Candelaria).
+- Params: `period`, `month`, `start_date`, `end_date`, `metrics`
+
+#### get_item_sales_detail
+Detalle de ventas por ítem específico (1–50 SKUs) con granularidad día/semana/mes/total y desglose por tienda.
+- Params: `items`*, `start_date`*, `end_date`*, `stores`, `granularity`, `include_zero_days`
+
+#### get_product_performance
+Análisis detallado de rendimiento de productos de Full Queso.
+- Params: `period`, `month`, `start_date`, `end_date`, `stores`, `sort_by`, `top_n`
+
+#### get_sales_analysis
+Análisis multidimensional de ventas de Full Queso.
+- Params: `period`, `month`, `start_date`, `end_date`, `stores`, `dimensions`, `metrics`
+
+_Los params marcados con `*` son requeridos. Detalle completo en `docs/tool_*.md`._
 
 ## API Integrations
 

package/config/bank-gl-map.json

@@ -49,6 +49,7 @@
         "MN0004": { "gl": "18240", "name": "BDV 7191 Bs. *", "currency": "VES", "category": "bancos_nacionales" },
         "MN0005": { "gl": "18250", "name": "Bancrecer 2558 Bs.", "currency": "VES", "category": "bancos_nacionales" },
         "MN0007": { "gl": "18270", "name": "BDV Pago Movil 5145", "currency": "VES", "category": "bancos_nacionales" },
+        "MN0008": { "gl": "18275", "name": "Banesco 9547 Bs.", "currency": "VES", "category": "bancos_nacionales", "_nota": "Banco nuevo agregado 2026-07-10 (Puntos 20 y 21, BANESCO_9547_BS., banco 0134). gl 18275 removido de adjustment_accounts_ves el 2026-07-10 (FP): ahora es banco real, entra normal en revaluación/reconciliación." },
         "MN0028": { "gl": "18290", "name": "Ubii Bank", "currency": "VES", "category": "bancos_nacionales" },
         "MN0030": { "gl": "18130", "name": "Caja tienda ventas Bs.", "currency": "VES", "category": "caja" },
         "ME0030": { "gl": "18140", "name": "Caja tienda ventas $", "currency": "USD", "category": "caja" },
@@ -74,6 +75,7 @@
     "18250": "Banco quinto Bs.",
     "18260": "Banco sexto Bs.",
     "18270": "Banco séptimo Bs.",
+    "18275": "Banesco 9547 Bs. (FQ88)",
     "18280": "Banco octavo Bs.",
     "18290": "UBII principal",
     "18291": "UBII secundario",
@@ -90,6 +92,6 @@
     "18998": "Total Bancos",
     "18999": "Total Caja y Bancos"
   },
-  "_adjustment_accounts_nota": "Cuentas VES de ajuste/tránsito (NO son bancos reales, no tienen statement). Se tratan como informativas en la revaluación cambiaria (fuera del total de pérdida y del asiento sugerido). FP 2026-06-05.",
-  "adjustment_accounts_ves": ["18275", "18297"]
+  "_adjustment_accounts_nota": "Cuentas VES de ajuste/tránsito (NO son bancos reales, no tienen statement). Se tratan como informativas en la revaluación cambiaria (fuera del total de pérdida y del asiento sugerido). FP 2026-06-05. 18275 removido 2026-07-10: BC lo reasignó al banco real Banesco 9547 (FQ88-MN0008).",
+  "adjustment_accounts_ves": ["18297"]
 }

package/config/income-accounts.js

@@ -25,6 +25,35 @@ export const COGS_ACCOUNTS = {
   57020: { name: 'Costos Diversos', nameEn: 'Diverse Costs' },
 };
 
+// ── Revenue classification for the store-payroll KPI denominator ─────────────
+// Verified against the real CoA (tests/discover-revenue-accounts.js, May 2026):
+//   40310 "Ventas Materia Prima otras tiendas" = intercompany de tienda (FQ01/FQ88,
+//          FQ28=0); su costo par es 50110 (see LESSONS L-011).
+//   40180 "Ventas Eventos - NEN" + 40700 "Ventas Eventos" = event sales (solo FQ01).
+//   40580 "Ganancia por dif. cambiario" + 40540/40550 "Descuentos/Rebajas en Compras"
+//          = ingreso NO-venta → fuera del denominador de tienda (confirmado por FP).
+// revenue_store = revenue_total − intercompany − events − non_sales.
+export const INTERCOMPANY_REVENUE_ACCOUNTS = ['40310'];
+export const EVENT_REVENUE_ACCOUNTS = ['40180', '40700'];
+export const NON_SALES_REVENUE_ACCOUNTS = ['40580', '40540', '40550'];
+
+// FQFR (master de franquicia): su intercompañía usa cuentas propias (royalties/fees),
+// NO 40310, y no tiene ventas de evento de tienda. El KPI de nómina/ventas NO aplica a
+// FQFR (ver KPI_PAYROLL_STORES) — esta clasificación es solo para que sus buckets de
+// venta salgan correctos si alguien consulta ventas de FQFR.
+export const FQFR_INTERCOMPANY_REVENUE_ACCOUNTS = ['40420', '40430', '40660', '40930'];
+
+// Tiendas a las que aplica el KPI nómina/ventas (FQFR excluido por completo).
+export const KPI_PAYROLL_STORES = ['FQ01', 'FQ28', 'FQ88'];
+
+// Cuentas de clasificación de ingreso por tienda (interco/eventos/no-venta).
+export function getRevenueClassification(storeCode) {
+  if (storeCode === 'FQFR') {
+    return { intercompany: FQFR_INTERCOMPANY_REVENUE_ACCOUNTS, events: [], nonSales: NON_SALES_REVENUE_ACCOUNTS };
+  }
+  return { intercompany: INTERCOMPANY_REVENUE_ACCOUNTS, events: EVENT_REVENUE_ACCOUNTS, nonSales: NON_SALES_REVENUE_ACCOUNTS };
+}
+
 // Income group labels for breakdown (by 100-prefix: 40110 → 40100)
 export const INCOME_GROUP_LABELS = {
   40100: '40100_ingreso_ventas',

package/lib/bc-client.js

@@ -18,6 +18,12 @@ export class BCClient {
     this._inflightRequests = new Map();
     this.STORE_DATA_TTL = 5 * 60 * 1000;      // 5 minutes
     this.EXCHANGE_RATE_TTL = 15 * 60 * 1000;   // 15 minutes
+
+    // Per-request hard timeout (ms). Without this a single hung fetch() never
+    // rejects → the whole tool call (and, via Promise.all consolidations, the
+    // MCP process) hangs forever. Generous default (all observed BC calls are
+    // <1s); tunable via env for unusually heavy OData reports. See L-015.
+    this.FETCH_TIMEOUT_MS = Number(process.env.BC_FETCH_TIMEOUT_MS) || 90000;
   }
 
   /**
@@ -135,8 +141,12 @@ export class BCClient {
 
   async fetchWithRetry(url, options, retries = 3) {
     for (let attempt = 1; attempt <= retries; attempt++) {
+      // Abort a hung request so it fails fast (and retries) instead of blocking
+      // forever. Each attempt gets its own controller/timer. See L-015.
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.FETCH_TIMEOUT_MS);
       try {
-        const response = await fetch(url, options);
+        const response = await fetch(url, { ...options, signal: controller.signal });
         if (response.status === 429 && attempt < retries) {
           const retryAfter = response.headers.get('Retry-After');
           const delay = retryAfter ? parseInt(retryAfter) * 1000 : attempt * 3000;
@@ -146,10 +156,20 @@ export class BCClient {
         }
         return response;
       } catch (err) {
-        if (attempt === retries) throw err;
+        const timedOut = err.name === 'AbortError';
+        if (attempt === retries) {
+          throw timedOut
+            ? new Error(`BC request timed out after ${this.FETCH_TIMEOUT_MS}ms (${retries} attempts): ${url}`)
+            : err;
+        }
         const delay = attempt * 2000;
-        logger.warn(`Fetch failed (attempt ${attempt}/${retries}), retrying in ${delay}ms...`);
+        logger.warn(
+          `Fetch ${timedOut ? `timed out (>${this.FETCH_TIMEOUT_MS}ms)` : 'failed'} ` +
+          `(attempt ${attempt}/${retries}), retrying in ${delay}ms...`
+        );
         await new Promise((r) => setTimeout(r, delay));
+      } finally {
+        clearTimeout(timer);
       }
     }
   }
@@ -316,6 +336,20 @@ export class BCClient {
     return this.apiCallAllPages(url);
   }
 
+  // Nombres del Chart of Accounts (entidad `accounts` de BC api/v2.0) → { number: displayName }.
+  // Cache por companyId (el CoA cambia rara vez). Usado por get_income_statement (level 2)
+  // para etiquetar las cuentas de posteo hijas con su nombre real de BC.
+  async getChartOfAccountNames(companyId) {
+    if (!this._coaNameCache) this._coaNameCache = {};
+    if (this._coaNameCache[companyId]) return this._coaNameCache[companyId];
+    const url = this.buildApiUrl(companyId, 'accounts', { $select: 'number,displayName' });
+    const rows = await this.apiCallAllPages(url);
+    const map = {};
+    for (const a of rows) if (a && a.number) map[String(a.number)] = a.displayName || '';
+    this._coaNameCache[companyId] = map;
+    return map;
+  }
+
   // Saldos acumulados (a fecha) de cuentas con AMBAS monedas: debit/creditAmount = USD (LCY)
   // y additionalCurrency*Amount = VES (moneda adicional). Para revaluación de caja VES.
   // postingDate le asOfDate (acumulado desde el inicio = saldo a la fecha).

package/package.json

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