@fullqueso/mcp-bc-gastos 1.11.1 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # CHANGELOG
 
+## [1.14.0] - 2026-03-15
+
+### Highlights
+- **35 tools** across 7 domains — new **Inventario** domain for inventory cost analysis
+- 3 new tools to diagnose FIFO unit cost, open layers, and value entry adjustments
+- Uses BC Standard v2.0 API: `items`, `itemLedgerEntries`, `valueEntries`
+
+### Added
+
+**Inventario (Inventory Cost Analysis) — 3 herramientas (Standard v2.0):**
+- `get_item_card` — datos maestros de ítems: unitCost, costingMethod, inventory qty, unitPrice, categoría. Filtra por número, búsqueda por nombre, o categoría
+- `get_item_ledger_entries` — capas FIFO abiertas/cerradas con remainingQuantity y costAmountActual. Calcula `weighted_avg_unit_cost` sobre capas abiertas. Filtros por open_only (default: true), entry_type, fecha
+- `get_item_value_entries` — detalle de valorización por entrada del ledger: costPerUnit, ajustes de costo, revaluaciones. Permite drill-down por item_ledger_entry_number específico
+
+### Technical
+- New domain folder: `tools/inventario/` with `index.js` re-exports
+- Spec document: `docs/tool_inventario.md`
+- All tools use `buildApiUrl()` + `apiCall()` from BCClient (Standard v2.0, GUID-based)
+- `unit_cost_actual` computed per ledger entry: `|costAmountActual / quantity|`
+- `weighted_avg_unit_cost` computed proportionally from remaining qty of open layers
+- Zero `console.log` — all logging via `logger.info()` (console.error wrapper)
+
+---
+
 ## [1.10.0] - 2026-02-26
 
 ### Highlights

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.14.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": {
     "mcp-bc-gastos": "server.js"
@@ -38,6 +38,8 @@
     "accounts-receivable",
     "accounts-payable",
     "multi-payment",
+    "payroll",
+    "manager-report",
     "odata",
     "fullqueso"
   ],

package/scripts/generate-cxp-report-xlsx.py

@@ -0,0 +1,355 @@
+#!/usr/bin/env python3
+"""
+Generate CxP (Cuentas por Pagar) Excel report with 3 tier sheets + summary.
+
+Usage:
+    python3 generate-cxp-report-xlsx.py <input.json> <output.xlsx>
+
+Input: JSON file with { store, store_name, report_date, invoices[] }
+Output: Formatted Excel with 4 sheets (Resumen, Sin Draft, Draft No Posteado, Pago Parcial)
+
+Requires: openpyxl (pip3 install openpyxl)
+"""
+
+import json
+import sys
+import argparse
+from datetime import datetime, date
+from pathlib import Path
+
+try:
+    from openpyxl import Workbook
+    from openpyxl.styles import Font, Alignment, PatternFill, Border, Side
+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")
+SUBTOTAL_FONT = Font(bold=True, size=10)
+NUM_FMT = '#,##0.00'
+
+TIER_FILLS = {
+    "fully_pending": PatternFill(start_color="FCE4EC", end_color="FCE4EC", fill_type="solid"),
+    "draft_in_progress": PatternFill(start_color="FFF3E0", end_color="FFF3E0", fill_type="solid"),
+    "in_journal": PatternFill(start_color="E8F5E9", end_color="E8F5E9", fill_type="solid"),
+}
+
+TIER_LABELS = {
+    "fully_pending": "Sin Draft",
+    "draft_in_progress": "Draft No Posteado",
+    "in_journal": "Pago Parcial",
+}
+
+
+def set_col_widths(ws, widths):
+    for col_letter, width in widths.items():
+        ws.column_dimensions[col_letter].width = width
+
+
+def write_header_row(ws, row, headers, start_col=1):
+    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")
+
+
+def days_since(date_str, today):
+    try:
+        d = datetime.strptime(date_str, "%Y-%m-%d").date()
+        return max(0, (today - d).days)
+    except (ValueError, TypeError):
+        return 0
+
+
+# ─── Sheet 1: Resumen ───
+
+def build_resumen(wb, data, invoices, today):
+    ws = wb.active
+    ws.title = "Resumen"
+    set_col_widths(ws, {"A": 35, "B": 14, "C": 18, "D": 18, "E": 18, "F": 18, "G": 18, "H": 18, "I": 18})
+
+    store_label = f"{data.get('store', '')} — {data.get('store_name', '')}"
+    report_date = data.get("report_date", "")
+
+    ws.cell(row=1, column=1, value=f"REPORTE CxP — {store_label}").font = BOLD_14
+    ws.cell(row=2, column=1, value=f"Fecha: {report_date}").font = BOLD_12
+
+    # Group by tier
+    tiers = {"fully_pending": [], "draft_in_progress": [], "in_journal": []}
+    for inv in invoices:
+        tier = inv.get("tier", "fully_pending")
+        if tier in tiers:
+            tiers[tier].append(inv)
+
+    # Summary metrics
+    row = 4
+    ws.cell(row=row, column=1, value="Concepto").font = BOLD
+    ws.cell(row=row, column=2, value="Facturas").font = BOLD
+    ws.cell(row=row, column=3, value="Monto (USD)").font = BOLD
+
+    total_count = len(invoices)
+    total_amount = sum(inv.get("invoice_amount", 0) for inv in invoices)
+
+    row_data = [
+        ("TOTAL FACTURAS ABIERTAS", total_count, total_amount),
+        ("", "", ""),
+        (TIER_LABELS["fully_pending"], len(tiers["fully_pending"]),
+         sum(i.get("invoice_amount", 0) for i in tiers["fully_pending"])),
+        (TIER_LABELS["draft_in_progress"], len(tiers["draft_in_progress"]),
+         sum(i.get("invoice_amount", 0) for i in tiers["draft_in_progress"])),
+        (TIER_LABELS["in_journal"], len(tiers["in_journal"]),
+         sum(i.get("invoice_amount", 0) for i in tiers["in_journal"])),
+    ]
+
+    for i, (label, count, amount) in enumerate(row_data):
+        r = row + 1 + i
+        ws.cell(row=r, column=1, value=label)
+        if label:
+            ws.cell(row=r, column=2, value=count)
+            ws.cell(row=r, column=3, value=round(amount, 2)).number_format = NUM_FMT
+        if i == 0:
+            for c in range(1, 4):
+                ws.cell(row=r, column=c).font = BOLD
+
+    # Vendor breakdown
+    row += len(row_data) + 3
+    ws.cell(row=row, column=1, value="DESGLOSE POR PROVEEDOR").font = BOLD_12
+    row += 1
+
+    vendor_map = {}
+    for inv in invoices:
+        vno = inv.get("vendor_no", "")
+        if vno not in vendor_map:
+            vendor_map[vno] = {
+                "name": inv.get("vendor_name", vno),
+                "count": 0, "total": 0,
+                "sin_draft": 0, "sin_draft_n": 0,
+                "draft": 0, "draft_n": 0,
+                "parcial": 0, "parcial_n": 0,
+            }
+        v = vendor_map[vno]
+        v["count"] += 1
+        v["total"] += inv.get("invoice_amount", 0)
+        tier = inv.get("tier", "fully_pending")
+        if tier == "fully_pending":
+            v["sin_draft"] += inv.get("invoice_amount", 0)
+            v["sin_draft_n"] += 1
+        elif tier == "draft_in_progress":
+            v["draft"] += inv.get("invoice_amount", 0)
+            v["draft_n"] += 1
+        elif tier == "in_journal":
+            v["parcial"] += inv.get("invoice_amount", 0)
+            v["parcial_n"] += 1
+
+    vendors = sorted(vendor_map.items(), key=lambda x: x[1]["total"], reverse=True)
+
+    headers = ["No.", "Proveedor", "Facturas", "Total (USD)", "Sin Draft", "Sin Draft $", "Draft", "Draft $", "Parcial", "Parcial $"]
+    write_header_row(ws, row, headers)
+    row += 1
+
+    for vno, v in vendors:
+        ws.cell(row=row, column=1, value=vno)
+        ws.cell(row=row, column=2, value=v["name"])
+        ws.cell(row=row, column=3, value=v["count"])
+        ws.cell(row=row, column=4, value=round(v["total"], 2)).number_format = NUM_FMT
+        ws.cell(row=row, column=5, value=v["sin_draft_n"])
+        ws.cell(row=row, column=6, value=round(v["sin_draft"], 2)).number_format = NUM_FMT
+        ws.cell(row=row, column=7, value=v["draft_n"])
+        ws.cell(row=row, column=8, value=round(v["draft"], 2)).number_format = NUM_FMT
+        ws.cell(row=row, column=9, value=v["parcial_n"])
+        ws.cell(row=row, column=10, value=round(v["parcial"], 2)).number_format = NUM_FMT
+        row += 1
+
+    # Totals row
+    if vendors:
+        ws.cell(row=row, column=1, value="TOTAL").font = BOLD
+        ws.cell(row=row, column=3, value=total_count).font = BOLD
+        ws.cell(row=row, column=4, value=round(total_amount, 2)).number_format = NUM_FMT
+        ws.cell(row=row, column=4).font = BOLD
+        for c in range(1, 11):
+            ws.cell(row=row, column=c).fill = SUBTOTAL_FILL
+
+
+# ─── Sheet 2: Sin Draft ───
+
+def build_sin_draft(wb, invoices, today):
+    ws = wb.create_sheet("Sin Draft")
+    tier_invs = [i for i in invoices if i.get("tier") == "fully_pending"]
+    tier_invs.sort(key=lambda i: i.get("posting_date", ""))
+    fill = TIER_FILLS["fully_pending"]
+
+    set_col_widths(ws, {"A": 18, "B": 14, "C": 32, "D": 14, "E": 16, "F": 14})
+
+    ws.cell(row=1, column=1, value=f"SIN DRAFT — {len(tier_invs)} facturas").font = BOLD_14
+
+    headers = ["Factura", "Fecha", "Proveedor", "No. Proveedor", "Monto (USD)", "Dias Pendiente"]
+    write_header_row(ws, 3, headers)
+    ws.freeze_panes = "A4"
+
+    row = 4
+    for inv in tier_invs:
+        ws.cell(row=row, column=1, value=inv.get("invoice_no", ""))
+        ws.cell(row=row, column=2, value=inv.get("posting_date", ""))
+        ws.cell(row=row, column=3, value=inv.get("vendor_name", ""))
+        ws.cell(row=row, column=4, value=inv.get("vendor_no", ""))
+        ws.cell(row=row, column=5, value=inv.get("invoice_amount", 0)).number_format = NUM_FMT
+        ws.cell(row=row, column=6, value=days_since(inv.get("posting_date", ""), today))
+        for c in range(1, 7):
+            ws.cell(row=row, column=c).fill = fill
+        row += 1
+
+    # Subtotal
+    if tier_invs:
+        ws.cell(row=row, column=1, value="TOTAL").font = SUBTOTAL_FONT
+        ws.cell(row=row, column=5, value=f"=SUM(E4:E{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=5).font = SUBTOTAL_FONT
+        for c in range(1, 7):
+            ws.cell(row=row, column=c).fill = SUBTOTAL_FILL
+
+    return len(tier_invs)
+
+
+# ─── Sheet 3: Draft No Posteado ───
+
+def build_draft_no_posteado(wb, invoices, today):
+    ws = wb.create_sheet("Draft No Posteado")
+    tier_invs = [i for i in invoices if i.get("tier") == "draft_in_progress"]
+    tier_invs.sort(key=lambda i: i.get("posting_date", ""))
+    fill = TIER_FILLS["draft_in_progress"]
+
+    set_col_widths(ws, {"A": 18, "B": 14, "C": 32, "D": 14, "E": 16, "F": 16, "G": 14, "H": 16, "I": 16})
+
+    ws.cell(row=1, column=1, value=f"DRAFT NO POSTEADO — {len(tier_invs)} facturas").font = BOLD_14
+
+    headers = ["Factura", "Fecha", "Proveedor", "No. Proveedor", "Monto (USD)", "No. MP", "Status MP", "Drafted (USD)", "Pendiente Neto"]
+    write_header_row(ws, 3, headers)
+    ws.freeze_panes = "A4"
+
+    row = 4
+    for inv in tier_invs:
+        mp = inv.get("multi_payment") or {}
+        ws.cell(row=row, column=1, value=inv.get("invoice_no", ""))
+        ws.cell(row=row, column=2, value=inv.get("posting_date", ""))
+        ws.cell(row=row, column=3, value=inv.get("vendor_name", ""))
+        ws.cell(row=row, column=4, value=inv.get("vendor_no", ""))
+        ws.cell(row=row, column=5, value=inv.get("invoice_amount", 0)).number_format = NUM_FMT
+        ws.cell(row=row, column=6, value=mp.get("mp_no", ""))
+        ws.cell(row=row, column=7, value=mp.get("status", ""))
+        ws.cell(row=row, column=8, value=mp.get("total_payment_amount", 0)).number_format = NUM_FMT
+        ws.cell(row=row, column=9, value=mp.get("net_pending", inv.get("invoice_amount", 0))).number_format = NUM_FMT
+        for c in range(1, 10):
+            ws.cell(row=row, column=c).fill = fill
+        row += 1
+
+    if tier_invs:
+        ws.cell(row=row, column=1, value="TOTAL").font = SUBTOTAL_FONT
+        ws.cell(row=row, column=5, value=f"=SUM(E4:E{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=5).font = SUBTOTAL_FONT
+        ws.cell(row=row, column=8, value=f"=SUM(H4:H{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=8).font = SUBTOTAL_FONT
+        ws.cell(row=row, column=9, value=f"=SUM(I4:I{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=9).font = SUBTOTAL_FONT
+        for c in range(1, 10):
+            ws.cell(row=row, column=c).fill = SUBTOTAL_FILL
+
+    return len(tier_invs)
+
+
+# ─── Sheet 4: Pago Parcial ───
+
+def build_pago_parcial(wb, invoices, today):
+    ws = wb.create_sheet("Pago Parcial")
+    tier_invs = [i for i in invoices if i.get("tier") == "in_journal"]
+    tier_invs.sort(key=lambda i: i.get("posting_date", ""))
+    fill = TIER_FILLS["in_journal"]
+
+    set_col_widths(ws, {"A": 18, "B": 14, "C": 32, "D": 14, "E": 16, "F": 16, "G": 14, "H": 16, "I": 16})
+
+    ws.cell(row=1, column=1, value=f"PAGO PARCIAL — {len(tier_invs)} facturas").font = BOLD_14
+
+    headers = ["Factura", "Fecha", "Proveedor", "No. Proveedor", "Monto (USD)", "No. MP", "Status MP", "Drafted (USD)", "Pendiente Neto"]
+    write_header_row(ws, 3, headers)
+    ws.freeze_panes = "A4"
+
+    row = 4
+    for inv in tier_invs:
+        mp = inv.get("multi_payment") or {}
+        ws.cell(row=row, column=1, value=inv.get("invoice_no", ""))
+        ws.cell(row=row, column=2, value=inv.get("posting_date", ""))
+        ws.cell(row=row, column=3, value=inv.get("vendor_name", ""))
+        ws.cell(row=row, column=4, value=inv.get("vendor_no", ""))
+        ws.cell(row=row, column=5, value=inv.get("invoice_amount", 0)).number_format = NUM_FMT
+        ws.cell(row=row, column=6, value=mp.get("mp_no", ""))
+        ws.cell(row=row, column=7, value=mp.get("status", ""))
+        ws.cell(row=row, column=8, value=mp.get("total_payment_amount", 0)).number_format = NUM_FMT
+        ws.cell(row=row, column=9, value=mp.get("net_pending", inv.get("invoice_amount", 0))).number_format = NUM_FMT
+        for c in range(1, 10):
+            ws.cell(row=row, column=c).fill = fill
+        row += 1
+
+    if tier_invs:
+        ws.cell(row=row, column=1, value="TOTAL").font = SUBTOTAL_FONT
+        ws.cell(row=row, column=5, value=f"=SUM(E4:E{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=5).font = SUBTOTAL_FONT
+        ws.cell(row=row, column=8, value=f"=SUM(H4:H{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=8).font = SUBTOTAL_FONT
+        ws.cell(row=row, column=9, value=f"=SUM(I4:I{row - 1})").number_format = NUM_FMT
+        ws.cell(row=row, column=9).font = SUBTOTAL_FONT
+        for c in range(1, 10):
+            ws.cell(row=row, column=c).fill = SUBTOTAL_FILL
+
+    return len(tier_invs)
+
+
+# ─── Main ───
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate CxP Excel report")
+    parser.add_argument("input_json", help="Path to input JSON file")
+    parser.add_argument("output_xlsx", help="Path to output Excel file")
+    args = parser.parse_args()
+
+    input_path = Path(args.input_json)
+    output_path = Path(args.output_xlsx)
+
+    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)
+
+    invoices = data.get("invoices", [])
+    today = date.today()
+    if data.get("report_date"):
+        try:
+            today = datetime.strptime(data["report_date"], "%Y-%m-%d").date()
+        except ValueError:
+            pass
+
+    wb = Workbook()
+    build_resumen(wb, data, invoices, today)
+    n_sin = build_sin_draft(wb, invoices, today)
+    n_draft = build_draft_no_posteado(wb, invoices, today)
+    n_parcial = build_pago_parcial(wb, invoices, today)
+
+    wb.save(str(output_path))
+    print(json.dumps({
+        "file": str(output_path),
+        "sheets": {"sin_draft": n_sin, "draft_no_posteado": n_draft, "pago_parcial": n_parcial},
+        "total": len(invoices),
+    }))
+
+
+if __name__ == "__main__":
+    main()

package/server.js

@@ -59,6 +59,24 @@ import {
   draftSummaryTool, handleDraftSummary,
 } from './tools/multi-payment/index.js';
 
+// Payroll tools
+import {
+  payrollDocumentsTool, handlePayrollDocuments,
+  payrollLinesTool, handlePayrollLines,
+  employeesTool, handleEmployees,
+} from './tools/payroll/index.js';
+
+// Inventario tools (inventory cost analysis)
+import {
+  itemCardTool, handleItemCard,
+  itemLedgerEntriesTool, handleItemLedgerEntries,
+  itemValueEntriesTool, handleItemValueEntries,
+} from './tools/inventario/index.js';
+
+// Reports tools
+import { managerReportTool, handleGenerateManagerReport } from './tools/reports/manager-report.js';
+import { cxpReportTool, handleGenerateCxpReport } from './tools/reports/cxp-report.js';
+
 const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf-8'));
 const bcClient = new BCClient();
 
@@ -108,6 +126,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       draftReceivablesTool,
       draftPayablesTool,
       draftSummaryTool,
+      // Payroll
+      payrollDocumentsTool,
+      payrollLinesTool,
+      employeesTool,
+      // Inventario (inventory cost analysis)
+      itemCardTool,
+      itemLedgerEntriesTool,
+      itemValueEntriesTool,
+      // Reports
+      managerReportTool,
+      cxpReportTool,
     ],
   };
 });
@@ -204,6 +233,33 @@ 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;
+      // Inventario (inventory cost analysis)
+      case 'get_item_card':
+        result = await handleItemCard(bcClient, args);
+        break;
+      case 'get_item_ledger_entries':
+        result = await handleItemLedgerEntries(bcClient, args);
+        break;
+      case 'get_item_value_entries':
+        result = await handleItemValueEntries(bcClient, args);
+        break;
+      // Reports
+      case 'generate_manager_report':
+        result = await handleGenerateManagerReport(bcClient, args);
+        break;
+      case 'generate_cxp_report':
+        result = await handleGenerateCxpReport(bcClient, args);
+        break;
       default:
         return {
           content: [{ type: 'text', text: `Herramienta desconocida: ${name}` }],

package/tools/inventario/index.js

@@ -0,0 +1,3 @@
+export { itemCardTool, handleItemCard } from './item-card.js';
+export { itemLedgerEntriesTool, handleItemLedgerEntries } from './item-ledger-entries.js';
+export { itemValueEntriesTool, handleItemValueEntries } from './item-value-entries.js';

package/tools/inventario/item-card.js

@@ -0,0 +1,89 @@
+import { resolveStores } from '../../config/company-config.js';
+import { logger } from '../../utils/logger.js';
+
+export const itemCardTool = {
+  name: 'get_item_card',
+  description:
+    'Datos maestros de ítems de inventario: unitCost, costingMethod, inventory qty, unitPrice, categoría. Filtra por número de ítem, búsqueda por nombre, o categoría.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      store: {
+        type: 'string',
+        enum: ['FQ01', 'FQ28', 'FQ88'],
+        description: 'Tienda a consultar.',
+      },
+      item_number: {
+        type: 'string',
+        description: 'Número de ítem exacto (e.g. FQ0850).',
+      },
+      item_search: {
+        type: 'string',
+        description: 'Búsqueda parcial por nombre (case-insensitive, client-side).',
+      },
+      item_category: {
+        type: 'string',
+        description: 'Filtrar por itemCategoryCode.',
+      },
+    },
+    required: ['store'],
+  },
+};
+
+export async function handleItemCard(bcClient, args) {
+  const storeParam = args.store;
+  if (!storeParam) throw new Error('Parámetro requerido: store');
+
+  const stores = resolveStores([storeParam]);
+  const store = stores[0];
+  const companyId = store.companyId;
+
+  const filters = [];
+  if (args.item_number) {
+    filters.push(`number eq '${args.item_number}'`);
+  }
+  if (args.item_category) {
+    filters.push(`itemCategoryCode eq '${args.item_category}'`);
+  }
+
+  const params = {
+    $select: 'number,displayName,type,itemCategoryCode,unitCost,unitPrice,inventory,costingMethod,blocked',
+    $orderby: 'number',
+  };
+  if (filters.length > 0) params.$filter = filters.join(' and ');
+  if (!args.item_number && !args.item_search) params.$top = '50';
+
+  const url = bcClient.buildApiUrl(companyId, 'items', params);
+  let data = await bcClient.apiCallAllPages(url);
+
+  logger.info(`${store.code}: ${data.length} items returned`);
+
+  // Client-side name search
+  if (args.item_search) {
+    const search = args.item_search.toLowerCase();
+    data = data.filter((item) => item.displayName && item.displayName.toLowerCase().includes(search));
+  }
+
+  const items = data.map((item) => ({
+    number: item.number,
+    name: item.displayName,
+    type: item.type,
+    category: item.itemCategoryCode || null,
+    unit_cost: round2(item.unitCost || 0),
+    unit_price: round2(item.unitPrice || 0),
+    inventory: round2(item.inventory || 0),
+    costing_method: item.costingMethod || null,
+    blocked: item.blocked || false,
+  }));
+
+  return {
+    store: store.code,
+    store_name: store.name,
+    total_items: items.length,
+    items,
+  };
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}