@fullqueso/mcp-bc-gastos 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # CHANGELOG
 
+## [1.10.0] - 2026-02-26
+
+### Highlights
+- **26 tools** across 5 domains
+- **New**: Consolidated bank reconciliation report tool — single call replaces 3-5 sequential tool calls
+- **Performance**: Parallel API fetching in reconciliation-status, bulk MP line fetching
+
+### Added
+- `get_bank_reconciliation_report` — consolidated bank reconciliation: progress + unmatched debits/credits + journal entry suggestions in ONE MCP call. Statement selection by number, month (`month: "2025-12"`), or latest. Includes `matchBankDescription` keyword matching + historical GL pattern matching for debit suggestions.
+- Skill spec: `docs/SKILL_bank_reconciliation.md` — trigger phrases, presentation guide, example queries
+
+### Performance
+- **Bank reconciliation**: `get_reconciliation_status` now fetches statement lines in parallel (`Promise.all`) instead of sequential `for...of` loop
+- **Multi-Payment draft tools**: Replaced per-MP-header parallel line fetch (`Promise.all` on N headers) with single bulk fetch + in-memory grouping. Fixes BC 429 rate limiting for large stores (FQ28: ~1,173 invoices)
+- **BC client**: `fetchWithRetry` now handles HTTP 429 with `Retry-After` header support and exponential backoff
+
+---
+
+## [1.9.0] - 2026-02-25
+
+### Highlights
+- **25 tools** across 5 domains: expenses, bank reconciliation, POS reconciliation, AR/AP, **Multi-Payment draft visibility**
+- **4 API integrations**: Standard v2.0, OData V4, Finance Reports Beta, **Custom Extension API**
+- Three-tier invoice classification: Fully Pending → Drafted → In Journal
+
+### Added
+
+**Multi-Payment Draft Visibility — 3 herramientas (Custom Extension API):**
+- `get_draft_receivables` — facturas de venta abiertas con clasificación de tres niveles: sin documento, con borrador Open, con borrador Transferred. Incluye monto neto realmente pendiente y desglose por método de pago
+- `get_draft_payables` — mismo análisis para facturas de compra (proveedores)
+- `get_draft_summary` — resumen ejecutivo del pipeline de cobros y pagos en borrador por tienda
+
+**Aging Reports — nuevo parámetro `report` en get_draft_receivables y get_draft_payables:**
+- `report: "aging_pending"` — facturas SIN multipago agrupadas por mes con top vendors/customers, age_days_avg, y aging buckets (0-30, 31-60, 61-90, 90+)
+- `report: "aging_full"` — ambas categorías por mes: sin multipago + con draft sin postear, incluyendo drafted_amount y net_pending
+- `report: "default"` (o sin parámetro) — comportamiento existente sin cambios
+
+### Fixed
+- **Currency conversion bug**: `totalPaymentAmount` on MP headers is a VES FlowField sum — was being reported as USD. Now fetches MP lines + BCV exchange rates to compute accurate USD totals per line (VES lines ÷ BCV rate, USD lines as-is). Affects all 3 draft tools.
+
+### Technical
+- Custom Extension API integration (`buildCustomApiUrl`, `buildMultiPaymentApiUrl`) in BCClient
+- Supports 4 new API pages from Sales Invoice Payment Automation extension v1.4.0.0:
+  `multiPaymentHeaders`, `multiPaymentLines`, `purchMultiPaymentHeaders`, `purchMultiPaymentLines`
+- Three-tier classification logic cross-referencing customer/vendor ledger entries with MP headers
+- Multi-store parallel fetching with consolidated summaries
+- Payment method breakdown via MP lines (optional `include_lines` parameter)
+- Aging logic is pure post-processing on existing data — no additional API calls
+- Entity-parameterized aging builders (`VENDOR_ENTITY` / `CUSTOMER_ENTITY`) for correct field names per tool
+
+---
+
 ## [1.8.0] - 2026-02-23
 
 ### Highlights

package/lib/bc-client.js

@@ -111,7 +111,15 @@ export class BCClient {
   async fetchWithRetry(url, options, retries = 3) {
     for (let attempt = 1; attempt <= retries; attempt++) {
       try {
-        return await fetch(url, options);
+        const response = await fetch(url, options);
+        if (response.status === 429 && attempt < retries) {
+          const retryAfter = response.headers.get('Retry-After');
+          const delay = retryAfter ? parseInt(retryAfter) * 1000 : attempt * 3000;
+          logger.warn(`Rate limited (429), retry ${attempt}/${retries} in ${delay}ms`);
+          await new Promise((r) => setTimeout(r, delay));
+          continue;
+        }
+        return response;
       } catch (err) {
         if (attempt === retries) throw err;
         const delay = attempt * 2000;
@@ -163,6 +171,30 @@ export class BCClient {
     return qs ? `${base}?${qs}` : base;
   }
 
+  // ── Custom Extension API ─────────────────────────────────────────
+  // Custom API pages published by extensions (e.g., Sales Invoice Payment Automation).
+  // Path: api/{publisher}/{group}/{version}/companies({companyGuid})/{endpoint}
+  // Same OAuth token — different URL path.
+
+  buildCustomApiUrl(companyId, publisher, group, version, endpoint, params = {}) {
+    const base = `${this.baseUrl}/${this.tenantId}/${this.environment}/api/${publisher}/${group}/${version}/companies(${companyId})/${endpoint}`;
+    const searchParams = new URLSearchParams();
+
+    if (params.$filter) searchParams.set('$filter', params.$filter);
+    if (params.$top) searchParams.set('$top', String(params.$top));
+    if (params.$orderby) searchParams.set('$orderby', params.$orderby);
+    if (params.$select) searchParams.set('$select', params.$select);
+    if (params.$expand) searchParams.set('$expand', params.$expand);
+
+    const qs = searchParams.toString();
+    return qs ? `${base}?${qs}` : base;
+  }
+
+  // Shorthand for Multi-Payment API calls (publisher: fullQueso, group: multiPayment, v1.0)
+  buildMultiPaymentApiUrl(companyId, endpoint, params = {}) {
+    return this.buildCustomApiUrl(companyId, 'fullQueso', 'multiPayment', '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.8.0",
-  "description": "MCP server for Business Central operational expense analysis, bank reconciliation, POS reconciliation, and accounts receivable/payable - Full Queso franchise stores",
+  "version": "1.10.0",
+  "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",
   "main": "server.js",
   "bin": {
     "mcp-bc-gastos": "server.js"
@@ -13,6 +13,7 @@
     "config/",
     "tools/",
     "utils/",
+    "scripts/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -36,6 +37,7 @@
     "pos-reconciliation",
     "accounts-receivable",
     "accounts-payable",
+    "multi-payment",
     "odata",
     "fullqueso"
   ],

package/scripts/generate-bank-recon-xlsx.py

@@ -0,0 +1,376 @@
+#!/usr/bin/env python3
+"""
+Generate a bank reconciliation Excel report from MCP tool JSON output.
+
+Usage:
+    python3 generate-bank-recon-xlsx.py <input.json> <output.xlsx>
+
+Input: JSON file from get_bank_reconciliation_report MCP tool
+Output: Formatted Excel with 3 sheets (Resumen, Debitos Pendientes, Creditos Pendientes)
+
+Requires: openpyxl (pip3 install openpyxl)
+"""
+
+import json
+import sys
+from pathlib import Path
+
+try:
+    from openpyxl import Workbook
+    from openpyxl.styles import Font, Alignment, PatternFill, Border, Side, numbers
+except ImportError:
+    print("Error: openpyxl is required. Install with: pip3 install openpyxl", file=sys.stderr)
+    sys.exit(1)
+
+
+# ─── Styles ───
+
+BOLD = Font(bold=True)
+BOLD_14 = Font(bold=True, size=14)
+BOLD_12 = Font(bold=True, size=12)
+BOLD_11 = Font(bold=True, size=11)
+HEADER_FILL = PatternFill(start_color="4472C4", end_color="4472C4", fill_type="solid")
+HEADER_FONT = Font(bold=True, color="FFFFFF", size=10)
+SUBTOTAL_FILL = PatternFill(start_color="D9E2F3", end_color="D9E2F3", fill_type="solid")
+THIN_BORDER = Border(
+    bottom=Side(style="thin", color="CCCCCC"),
+)
+NUM_FMT = '#,##0.00'
+PCT_FMT = '0.0%'
+
+
+def fmt_bs(amount):
+    """Format amount as Bs. string for display."""
+    if amount is None:
+        return ""
+    return f"Bs. {abs(amount):,.2f}" if amount >= 0 else f"-Bs. {abs(amount):,.2f}"
+
+
+def set_col_widths(ws, widths):
+    """Set column widths by letter."""
+    for col_letter, width in widths.items():
+        ws.column_dimensions[col_letter].width = width
+
+
+def write_header_row(ws, row, headers, start_col=1):
+    """Write a styled header row."""
+    for i, header in enumerate(headers):
+        cell = ws.cell(row=row, column=start_col + i, value=header)
+        cell.font = HEADER_FONT
+        cell.fill = HEADER_FILL
+        cell.alignment = Alignment(horizontal="center")
+
+
+# ─── Sheet 1: Resumen ───
+
+def build_resumen(wb, data):
+    ws = wb.active
+    ws.title = "Resumen"
+    set_col_widths(ws, {"A": 45, "B": 22, "C": 22, "D": 18, "E": 18})
+
+    bank = data.get("bank_account", "")
+    store_name = data.get("store_name", "")
+    statement_no = data.get("statement_no", "")
+    statement_date = data.get("statement_date", "")
+    summary = data.get("unmatched_summary", {})
+    debits = data.get("unmatched_debits", {})
+    credits = data.get("unmatched_credits", {})
+
+    # Title block
+    ws.cell(row=1, column=1, value=f"CONCILIACION BANCARIA — {bank}").font = BOLD_14
+    ws.cell(row=2, column=1, value=store_name).font = BOLD_12
+    month_label = ""
+    if statement_date:
+        parts = statement_date.split("-")
+        months_es = ["", "Enero", "Febrero", "Marzo", "Abril", "Mayo", "Junio",
+                     "Julio", "Agosto", "Septiembre", "Octubre", "Noviembre", "Diciembre"]
+        if len(parts) >= 2:
+            m = int(parts[1])
+            month_label = f"{months_es[m]} {parts[0]}" if 1 <= m <= 12 else ""
+    ws.cell(row=3, column=1, value=f"Statement #{statement_no} — {month_label}").font = BOLD_11
+
+    # Key metrics
+    row = 5
+    ws.cell(row=row, column=1, value="Concepto").font = BOLD
+    ws.cell(row=row, column=2, value="Valor").font = BOLD
+
+    metrics = [
+        ("Total lineas en statement", summary.get("total_statement_lines", 0)),
+        ("Lineas conciliadas", summary.get("matched_lines", 0)),
+        ("Lineas pendientes", summary.get("total_unmatched", 0)),
+        ("% Conciliacion", f"{summary.get('match_rate_pct', 0)}%"),
+    ]
+    for i, (label, value) in enumerate(metrics):
+        ws.cell(row=row + 1 + i, column=1, value=label)
+        cell = ws.cell(row=row + 1 + i, column=2, value=value)
+        if isinstance(value, (int, float)):
+            cell.number_format = '#,##0' if isinstance(value, int) else NUM_FMT
+
+    row += len(metrics) + 2
+    # Amounts
+    recon_progress = data.get("reconciliation_progress", {}).get("reconciliations", [])
+    target_recon = next((r for r in recon_progress if str(r.get("statement_no")) == str(statement_no)), {})
+
+    ws.cell(row=row, column=1, value="Monto conciliado (Bs.)")
+    ws.cell(row=row, column=2, value=target_recon.get("matched_amount", 0)).number_format = NUM_FMT
+    row += 1
+    ws.cell(row=row, column=1, value="Monto pendiente (Bs.)")
+    ws.cell(row=row, column=2, value=target_recon.get("unmatched_amount", 0)).number_format = NUM_FMT
+    row += 2
+
+    ws.cell(row=row, column=1, value="Balance inicio statement")
+    ws.cell(row=row, column=2, value=data.get("balance_last_statement", 0)).number_format = NUM_FMT
+    row += 1
+    ws.cell(row=row, column=1, value="Balance fin statement")
+    ws.cell(row=row, column=2, value=data.get("statement_ending_balance", 0)).number_format = NUM_FMT
+    row += 2
+
+    # Debit breakdown
+    ws.cell(row=row, column=1, value="DESGLOSE DE PENDIENTES").font = BOLD_12
+    row += 1
+    ws.cell(row=row, column=1, value="Categoria").font = BOLD
+    ws.cell(row=row, column=2, value="Lineas").font = BOLD
+    ws.cell(row=row, column=3, value="Monto (Bs.)").font = BOLD
+    row += 1
+
+    ws.cell(row=row, column=1, value="DEBITOS PENDIENTES").font = BOLD
+    ws.cell(row=row, column=2, value=debits.get("count", 0)).font = BOLD
+    cell = ws.cell(row=row, column=3, value=debits.get("total_amount", 0))
+    cell.font = BOLD
+    cell.number_format = NUM_FMT
+    row += 1
+
+    for item in debits.get("breakdown", []):
+        ws.cell(row=row, column=1, value=f"  {item['category']}")
+        ws.cell(row=row, column=2, value=item["count"])
+        ws.cell(row=row, column=3, value=item["total_amount"]).number_format = NUM_FMT
+        row += 1
+
+    row += 1
+    ws.cell(row=row, column=1, value="CREDITOS PENDIENTES").font = BOLD
+    ws.cell(row=row, column=2, value=credits.get("count", 0)).font = BOLD
+    cell = ws.cell(row=row, column=3, value=credits.get("total_amount", 0))
+    cell.font = BOLD
+    cell.number_format = NUM_FMT
+    row += 1
+
+    for item in credits.get("breakdown", []):
+        ws.cell(row=row, column=1, value=f"  {item['category']}")
+        ws.cell(row=row, column=2, value=item["count"])
+        ws.cell(row=row, column=3, value=item["total_amount"]).number_format = NUM_FMT
+        row += 1
+
+    # Insights
+    insights = data.get("insights", [])
+    if insights:
+        row += 2
+        ws.cell(row=row, column=1, value="OBSERVACIONES Y ACCIONES RECOMENDADAS").font = BOLD_12
+        row += 1
+        for i, insight in enumerate(insights):
+            ws.cell(row=row, column=1, value=f"{i + 1}. {insight}")
+            row += 1
+
+    return ws
+
+
+# ─── Sheet 2: Debitos Pendientes ───
+
+def build_debitos(wb, data):
+    ws = wb.create_sheet("Debitos Pendientes")
+    set_col_widths(ws, {"A": 14, "B": 45, "C": 18, "D": 22, "E": 25})
+
+    debits = data.get("unmatched_debits", {})
+    bank = data.get("bank_account", "")
+    lines = debits.get("lines", [])
+    total = debits.get("total_amount", 0)
+    count = debits.get("count", 0)
+
+    # Title
+    ws.cell(row=1, column=1,
+            value=f"DEBITOS PENDIENTES — {bank} — {_month_label(data)}").font = BOLD_14
+    ws.cell(row=2, column=1,
+            value=f"{count} lineas — Total: Bs. {total:,.2f}")
+
+    # Header row
+    write_header_row(ws, 4, ["Fecha", "Descripcion", "Monto (Bs.)", "Documento", "Categoria"])
+
+    # Sort by date for display
+    sorted_lines = sorted(lines, key=lambda l: l.get("transaction_date") or "9999")
+
+    row = 5
+    for line in sorted_lines:
+        ws.cell(row=row, column=1, value=line.get("transaction_date", ""))
+        ws.cell(row=row, column=2, value=line.get("description", ""))
+        ws.cell(row=row, column=3, value=line.get("statement_amount", 0)).number_format = NUM_FMT
+        ws.cell(row=row, column=4, value=line.get("document_no", ""))
+        ws.cell(row=row, column=5, value=line.get("line_category", ""))
+        row += 1
+
+    # Total row
+    ws.cell(row=row, column=1, value="TOTAL").font = BOLD
+    total_cell = ws.cell(row=row, column=3, value=f"=SUM(C5:C{row - 1})")
+    total_cell.font = BOLD
+    total_cell.number_format = NUM_FMT
+
+    # Journal suggestions section
+    suggestions = data.get("journal_suggestions", {})
+    if suggestions and suggestions.get("suggestions"):
+        row += 3
+        ws.cell(row=row, column=1,
+                value="SUGERENCIAS DE ASIENTOS CONTABLES").font = BOLD_12
+        row += 1
+        write_header_row(ws, row, ["Fecha", "Descripcion", "Monto (Bs.)", "Cuenta Debito", "Confianza"])
+        row += 1
+
+        for s in suggestions["suggestions"]:
+            ws.cell(row=row, column=1, value=s.get("transaction_date", ""))
+            ws.cell(row=row, column=2, value=s.get("bank_description", ""))
+            ws.cell(row=row, column=3, value=s.get("amount", 0)).number_format = NUM_FMT
+            entry = s.get("suggested_entry", {})
+            acct = entry.get("debit_account", "") if entry else ""
+            acct_name = entry.get("debit_account_name", "") if entry else ""
+            ws.cell(row=row, column=4, value=f"{acct} {acct_name}".strip() if acct else "")
+            ws.cell(row=row, column=5, value=s.get("confidence", ""))
+            row += 1
+
+    return ws
+
+
+# ─── Sheet 3: Creditos Pendientes ───
+
+def build_creditos(wb, data):
+    ws = wb.create_sheet("Creditos Pendientes")
+    set_col_widths(ws, {"A": 14, "B": 45, "C": 18, "D": 22, "E": 25})
+
+    credits = data.get("unmatched_credits", {})
+    bank = data.get("bank_account", "")
+    lines = credits.get("lines", [])
+    total = credits.get("total_amount", 0)
+    count = credits.get("count", 0)
+
+    # Title
+    ws.cell(row=1, column=1,
+            value=f"CREDITOS PENDIENTES — {bank} — {_month_label(data)}").font = BOLD_14
+    ws.cell(row=2, column=1,
+            value=f"{count} lineas — Total: Bs. {total:,.2f}")
+
+    # Group lines by category
+    groups = {}
+    for line in lines:
+        cat = line.get("line_category", "Otro credito")
+        if cat not in groups:
+            groups[cat] = []
+        groups[cat].append(line)
+
+    # Determine if category is POS (show top 25 only)
+    POS_PREFIXES = ("POS ", "Deposito UBII")
+
+    # Sort categories: non-POS first, then POS
+    non_pos_cats = [c for c in groups if not c.startswith(POS_PREFIXES)]
+    pos_cats = [c for c in groups if c.startswith(POS_PREFIXES)]
+
+    row = 4
+    first_data_row = None
+
+    for cat in non_pos_cats + pos_cats:
+        cat_lines = groups[cat]
+        is_pos = cat.startswith(POS_PREFIXES)
+
+        # Category header
+        ws.cell(row=row, column=1, value=cat.upper()).font = BOLD_12
+        row += 1
+        write_header_row(ws, row, ["Fecha", "Descripcion", "Monto (Bs.)", "Documento", "Tipo"])
+        row += 1
+
+        # Sort by date
+        sorted_cat = sorted(cat_lines, key=lambda l: l.get("transaction_date") or "9999")
+
+        # For POS: show top 25 by amount
+        if is_pos and len(sorted_cat) > 25:
+            display_lines = sorted(sorted_cat, key=lambda l: abs(l.get("statement_amount", 0)), reverse=True)[:25]
+            display_lines = sorted(display_lines, key=lambda l: l.get("transaction_date") or "9999")
+            remaining = len(sorted_cat) - 25
+        else:
+            display_lines = sorted_cat
+            remaining = 0
+
+        start_row = row
+        if first_data_row is None:
+            first_data_row = row
+
+        for line in display_lines:
+            ws.cell(row=row, column=1, value=line.get("transaction_date", ""))
+            ws.cell(row=row, column=2, value=line.get("description", ""))
+            ws.cell(row=row, column=3, value=line.get("statement_amount", 0)).number_format = NUM_FMT
+            ws.cell(row=row, column=4, value=line.get("document_no", ""))
+            ws.cell(row=row, column=5, value=line.get("line_category", ""))
+            row += 1
+
+        if remaining > 0:
+            ws.cell(row=row, column=1,
+                    value=f"... +{remaining} lineas adicionales de {cat} no mostradas").font = Font(italic=True)
+            row += 1
+
+        # Subtotal
+        cat_total = sum(l.get("statement_amount", 0) for l in cat_lines)
+        ws.cell(row=row, column=1, value="Subtotal").font = BOLD
+        ws.cell(row=row, column=2, value=f"{len(cat_lines)} lineas").font = BOLD
+        cell = ws.cell(row=row, column=3, value=round(cat_total, 2))
+        cell.font = BOLD
+        cell.number_format = NUM_FMT
+        cell.fill = SUBTOTAL_FILL
+        row += 2
+
+    # Grand total
+    ws.cell(row=row, column=1, value=f"Total creditos pendientes ({count} lineas)").font = BOLD_12
+    cell = ws.cell(row=row, column=3, value=total)
+    cell.font = BOLD_12
+    cell.number_format = NUM_FMT
+
+    return ws
+
+
+# ─── Helpers ───
+
+def _month_label(data):
+    """Extract month label from statement_date."""
+    sd = data.get("statement_date", "")
+    if not sd:
+        return ""
+    months_es = ["", "Enero", "Febrero", "Marzo", "Abril", "Mayo", "Junio",
+                 "Julio", "Agosto", "Septiembre", "Octubre", "Noviembre", "Diciembre"]
+    parts = sd.split("-")
+    if len(parts) >= 2:
+        m = int(parts[1])
+        return f"{months_es[m]} {parts[0]}" if 1 <= m <= 12 else ""
+    return ""
+
+
+# ─── Main ───
+
+def main():
+    if len(sys.argv) < 3:
+        print(f"Usage: {sys.argv[0]} <input.json> <output.xlsx>", file=sys.stderr)
+        sys.exit(1)
+
+    input_path = Path(sys.argv[1])
+    output_path = Path(sys.argv[2])
+
+    if not input_path.exists():
+        print(f"Error: Input file not found: {input_path}", file=sys.stderr)
+        sys.exit(1)
+
+    with open(input_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    wb = Workbook()
+    build_resumen(wb, data)
+    build_debitos(wb, data)
+    build_creditos(wb, data)
+    wb.save(str(output_path))
+
+    print(f"Excel report saved to: {output_path}")
+
+
+if __name__ == "__main__":
+    main()