npm package: @fullqueso/mcp-bc-gastos
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
Author: Francisco Padilla
Latest version: 1.17.0

# @fullqueso/mcp-bc-gastos

MCP server for Microsoft Business Central — operational expenses, bank reconciliation, POS reconciliation, and accounts receivable/payable. Built for the Full Queso franchise (3 stores: FQ01 Chacao, FQ28 Marques, FQ88 Candelaria).

**22 tools** across 4 domains, powered by 3 BC API integrations.

## Features

- **Expense Analysis** — Breakdown by 10 categories, efficiency ratios, store comparison, anomaly detection, 6-month trends
- **Drill-Down & Vendors** — Transaction-level detail with vendor lookup, per-account ledger, vendor directory
- **Bank Reconciliation** — Unmatched statement lines/ledger entries, match scoring, journal entry suggestions, multi-bank POS reconciliation (Banesco, Bancrecer, BDV, UBII)
- **Accounts Receivable & Payable** — Customer/vendor ledger entries, open receivables/payables with aging, collection status

## Installation

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "fullqueso-bc-gastos": {
      "command": "npx",
      "args": ["-y", "@fullqueso/mcp-bc-gastos"],
      "env": {
        "BC_TENANT_ID": "your-azure-tenant-id",
        "BC_CLIENT_ID": "your-azure-app-client-id",
        "BC_CLIENT_SECRET": "your-azure-app-client-secret",
        "BC_TOKEN_URL": "https://login.microsoftonline.com/YOUR_TENANT/oauth2/v2.0/token",
        "BC_SCOPE": "https://api.businesscentral.dynamics.com/.default",
        "BC_API_BASE": "https://api.businesscentral.dynamics.com/v2.0",
        "BC_ENVIRONMENT": "production",
        "BC_COMPANY_FQ01": "company-guid-fq01",
        "BC_COMPANY_FQ28": "company-guid-fq28",
        "BC_COMPANY_FQ88": "company-guid-fq88"
      }
    }
  }
}
```

### Local Development

```bash
git clone https://github.com/Fullqueso/fullqueso-mcp-bc-gastos.git
cd fullqueso-mcp-bc-gastos
npm install
cp .env.example .env
# Edit .env with your credentials
npm start
```

## Tools (22)

### Expense Analysis (5 tools)

#### 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`

#### compare_stores
Compare all stores with efficiency rankings, variances, and savings opportunities.
- 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`

#### get_trends
Historical trend analysis (up to 6 months) with growth rates, seasonality, and ASCII charts.
- Params: `store`, `months`

### Drill-Down & Vendors (4 tools)

#### 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`

#### 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_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)

#### list_vendors
Directory of active vendors ordered by total amount paid.
- Params: `store` (req), `start_date`, `end_date`

### Bank Reconciliation (7 tools)

> These tools use OData V4 Web Services. Amounts in VES. Read-only.

#### list_bank_accounts
List active bank accounts for a store.
- Params: `store` (req)

#### get_reconciliation_status
Open reconciliation summary: matched vs unmatched lines per bank account.
- Params: `store` (req), `bank_account`

#### 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`

#### 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`

#### 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`

#### 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`

#### 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`

### Accounts Receivable & Payable (6 tools)

> These tools use the Finance Reports Beta API. Amounts in VES and USD. Read-only.

#### get_customer_balances
Customers with outstanding balances.
- Params: `store` (req), `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`

#### 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_collection_status
Period collection completeness: "Were all December invoices collected?"
- Params: `store` (req), `start_date` (req), `end_date` (req)

#### 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`

#### 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`

## API Integrations

| API | Used By | URL Pattern |
|-----|---------|-------------|
| **Standard v2.0** | Expenses, vendors, customers | `v2.0/{tenant}/{environment}/api/v2.0/companies({guid})/...` |
| **OData V4** | Bank reconciliation, BALE | `ODataV4/Company('{name}')/{service}` |
| **Finance Reports Beta** | Customer/vendor ledger entries | `api/microsoft/reportsFinance/beta/companies({guid})/...` |

All APIs share the same OAuth 2.0 credentials (Azure AD client credentials flow).

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `BC_TENANT_ID` | Yes | Azure AD tenant ID |
| `BC_CLIENT_ID` | Yes | Azure AD app client ID |
| `BC_CLIENT_SECRET` | Yes | Azure AD app client secret |
| `BC_TOKEN_URL` | Yes | OAuth 2.0 token endpoint |
| `BC_SCOPE` | Yes | BC API scope |
| `BC_API_BASE` | Yes | BC API base URL |
| `BC_ENVIRONMENT` | Yes | BC environment (e.g., `production`) |
| `BC_COMPANY_FQ01` | Yes | Company GUID for store FQ01 |
| `BC_COMPANY_FQ28` | No | Company GUID for store FQ28 |
| `BC_COMPANY_FQ88` | No | Company GUID for store FQ88 |
| `LOG_LEVEL` | No | `debug`, `info`, `warn`, `error` (default: `info`) |

## Chart of Accounts

10 expense categories mapped to account ranges 60000-99999:

1. **Planta Fisica** (60000-60999) — Rent, utilities
2. **Alquiler Equipos** (61000-61999) — Equipment rental
3. **Logistica** (62000-62999) — Vehicles, delivery
4. **Marketing** (63000-63999) — Advertising, commissions
5. **Administrativos** (64000-64999) — Office, software
6. **Seguros** (65000-65999) — Insurance
7. **Bancarios** (67000-67999) — Banking fees, interest
8. **Servicios Contratados** (68000-68999) — Contracted services
9. **Nomina** (70000-74999) — Payroll, benefits
10. **Otros** (80000-99999) — Depreciation, other

## Architecture

```
mcp-fullqueso-bc-gastos/
├── server.js              # MCP server entry point (22 tools)
├── lib/
│   ├── bc-client.js       # OAuth + BC API (v2.0, OData V4, Beta)
│   ├── expense-analyzer.js
│   ├── ratio-calculator.js
│   ├── anomaly-detector.js
│   ├── trend-analyzer.js
│   └── formatter.js
├── config/
│   ├── expense-accounts.js
│   ├── income-accounts.js
│   ├── benchmarks.js
│   ├── company-config.js
│   └── bank-keywords.js
├── tools/
│   ├── [9 expense/vendor tools]
│   ├── auditoria/         # 7 bank reconciliation tools
│   └── cobranzas/         # 6 AR/AP tools
└── utils/
    ├── date-helper.js
    ├── currency-converter.js
    └── logger.js
```

## License

MIT