Bilas.id MCP Server (v1.9.25)

Comprehensive Model Context Protocol (MCP) server for integrating AI Agents with the bilas.id POS & Laundry Management Platform.

🚀 Authentication & Session Isolation

The MCP server guarantees 100% session state isolation. Zero hardcoded credentials or JWT tokens exist in the codebase. User authentication is stored exclusively in ~/.bilas_id/token_state.json on the user's local machine.

🌐 System Default Browser Login (--browser-login / bilas_launch_browser_login)

When running on local or remote developer environments:

1. Step 1 (Open Browser): The server launches the system default browser to the official Bilas.id login page and opens a local bridge on 127.0.0.1:8765.

2. Step 2 (Login & Token Transfer): Log in using Google SSO or password. Use the 1-click bookmarklet or portal link to securely transfer extendedToken to the local bridge.

3. Auto-Outlet Resolution: The server automatically queries the user's outlet business profile to fetch their active outlet_id without requiring manual lookup.

⚡ Direct CLI Token Onboarding (--token)

Agents or automation scripts can save session credentials directly:

# Pass JWT token directly (outlet_id is auto-resolved via profile API)
bilas-mcp --token "eyJhbGci..."

# Pass both JWT token and explicit Outlet ID
bilas-mcp --token "eyJhbGci..." --outlet "outlet_abc123"

Related MCP server: KiotViet MCP Server

🛠️ Complete Feature & Tool Suite (34 Tools)

1. 🔐 Auth Tools

• bilas_launch_browser_login: Open system browser + local bridge on 127.0.0.1:8765 for 1-click bookmarklet token transfer (Google SSO compatible).

• bilas_set_manual_credentials: Save JWT token and optional Outlet ID into ~/.bilas_id/token_state.json.

2. 📊 Financials, Cashbox & Ledger Mutation

• bilas_get_cashbox_report: Computes exact 5-Column per-cashbox accounting matrix (Saldo Awal + Debit - Kredit = Saldo Akhir) using server-side aruskasneraca.

• bilas_get_financial_categories: Lists all operational expense & income categories configured for this outlet.

• bilas_add_expense: Records new operational expense (Pengeluaran) entries (e.g. Biaya Listrik, Beli Sabun).

• bilas_add_income: Records new operational income (Pemasukan) entries directly into specified cashbox with category and date.

• bilas_update_expense: Directly updates an existing financial record by keuanganId without needing delete+re-add cycles.

• bilas_delete_expense: Soft-deletes a financial record by keuanganId.

3. 🧾 Orders & Production Pipeline

• bilas_search_invoice: Look up customer orders across active and completed history by Nota Number (TRX/...), Customer Name, or Phone Number with optional tgl_awal and tgl_akhir (YYYY/MM/DD) date filtering.

• bilas_get_order_details: Comprehensive order breakdown with line-by-line item breakdown (Detail Layanan, package name, service item, weight/quantity in Kg/Satuan, unit price, total price, perfume, notes, and photos).

• bilas_create_order: Creates new regular laundry transactions with customer information, service items, and payment method.

• bilas_list_orders_by_status: Queries and filters active orders directly by production stage (Antrian, Proses, Setrika, Siap Ambil, Selesai, or all).

• bilas_get_production_summary: Real-time pipeline stage counters (Antrian, Proses, Siap Ambil, Siap Antar, Konfirmasi, Validasi, Penjemputan).

• bilas_update_order_status: Advances order or specific line item to the next production stage.

• bilas_revert_item_stage: Moves exactly one detail item backward through Koreksi/Riwayat with persistence verification.

4. 👥 Customer Management & Analytics

• bilas_list_customers: Lists and searches registered customer profiles with optional registered_after and registered_before (YYYY/MM/DD) date filtering.

• bilas_get_unique_customers: Multi-source customer deduplication combining paid transactions (pendapatan_transaksi), active orders (/all), and completed history orders (/riwayat), enriched with customer registry profiles (ID, registration date, email, spend, and order statuses).

5. 🤖 IoT Smart Machines & Outlet Profile

• bilas_list_machines: Real-time status, product types, and pulse metrics for IoT connected washers and dryers.

• bilas_get_outlet_profile: Business profile details, address, operating hours, delivery tariffs, and coordinates.

6. 📈 Dashboard Financial & Growth Reports (15 Reports)

All reporting tools accept tgl_awal and tgl_akhir in YYYY/MM/DD format:

• bilas_get_ringkasan_outlet: Outlet KPI summary with parsed KPI block (kiloan, satuan, meter, omzet, pendapatan, pengeluaran, labarugi, trxmasuk, trxbatal, graph).

• bilas_get_pendapatan_transaksi: Transaction revenue / Omzet breakdown.

• bilas_get_pengeluaran_transaksi: Itemized transaction expense report.

• bilas_get_topup_paket: Package top-ups report.

• bilas_get_topup_deposit: Deposit / e-money top-ups report.

• bilas_get_self_service_income: Self-service machine revenue.

• bilas_get_other_income: Other miscellaneous revenue.

• bilas_get_piutang: Accounts receivable and unpaid customer balances.

• bilas_get_pembulatan: Rounding adjustments report.

• bilas_get_merchant_fees: Biaya Layanan / merchant transaction fees.

• bilas_get_customer_growth: Customer registration growth over time.

• bilas_get_top_customers: Top customer ranking by revenue.

• bilas_get_package_quota: Active customer package quota usage and balances.

• bilas_get_deposit_balance: Customer deposit account balances.

• bilas_get_kasbon_history: Customer credit / kasbon history.

📦 MCP Resources & Prompts

Resources

• bilas://outlet/profile — Live outlet profile and operating configuration.

• bilas://machines/list — Real-time IoT washer and dryer statuses.

• bilas://production/summary — Real-time production stage counters.

• bilas://financial/categories — Active operational income and expense categories.

Prompts

• daily_summary — Generates daily business KPI summary (Omzet, expenses, production stages).

• check_production — Audits the production pipeline and highlights bottlenecks.

• expense_report — Breaks down operational expenses by category.

• customer_lookup — Looks up customer details and purchase history.

• cashbox_reconciliation — Audits cashbox balances against physical cash counts.

📦 Installation & Setup

pip install git+https://github.com/elony-7/Bilas.id-MCP-Server.git
playwright install

Self-Updating to Latest Version

bilas-mcp --update         # or --upgrade

The update command pulls and reinstalls the latest release directly from GitHub into your running Python environment.

🧪 Testing

Run the test suite:

pytest tests/ -v