# LightBill MCP Server

> mcp-name: io.github.lightnet19/lightbill-mcp-server

[![MCP Registry](https://img.shields.io/static/v1?label=MCP%20Registry&message=io.github.lightnet19%2Flightbill-mcp-server&color=blue)](https://registry.modelcontextprotocol.io/v0/servers/io.github.lightnet19%2Flightbill-mcp-server/versions)
[![PyPI version](https://img.shields.io/pypi/v/lightbill-mcp-server.svg)](https://pypi.org/project/lightbill-mcp-server/)
[![GitHub](https://img.shields.io/static/v1?label=GitHub&message=lightnet19%2Flightbill-mcp-server&color=181717&logo=github)](https://github.com/lightnet19/lightbill-mcp-server)

MCP (Model Context Protocol) server untuk mengelola **LightBill** — ISP billing & client management platform — melalui AI agents (Hermes/ARKA, Claude, n8n, dll).

Membungkus 124+ API routes LightBill menjadi **134 tools** dengan autentikasi AI API key (`X-AI-Key`) — tanpa flow login JWT manual.

## ✨ Fitur

- **👥 Pelanggan** — CRUD penuh + isolir/reaktivasi + sesi PPPoE + pemakaian
- **👷 Karyawan** — CRUD (owner/admin/noc/kasir/teknisi/reseller)
- **🔧 Router MikroTik** — CRUD + sinkronisasi + monitoring (traffic, resource, syslog, ip-pools, ping, top-consumers, active sessions)
- **⚡ OLT & ONT** — CRUD + ONT (create/delete/reboot/history) + ZTP + discovery + health
- **💵 Tagihan & Pembayaran** — konfirmasi lunas (auto-reaktivasi), generate, verifikasi bukti transfer approve/reject
- **📦 Paket & Template** — CRUD paket layanan + template pesan WhatsApp
- **💸 Keuangan** — pengeluaran CRUD, laporan daily/monthly/yearly
- **🎫 Hotspot, Mitra, ODC/ODP** — batch voucher, deposit reseller, topologi jaringan
- **🎟️ Helpdesk & Chat** — tiket (CLAIM/ASSIGN/RESOLVE/CLOSE), live chat
- **📋 Job & Backup** — tugas lapangan, export/restore data
- **📊 Analitik & Payroll** — churn prediction, forecasting, generate gaji
- **📦 Inventaris** — perangkat, bahan habis pakai, movement (borrow/return/install)
- **📡 Radius & Isolir** — kick sesi, enforce/reset FUP, lookup
- **⚙️ Pengaturan** — payment gateway (Tripay/Duitku/Midtrans/Xendit), profil tenant

## 🚀 Instalasi

### Prasyarat

- LightBill berjalan dengan `AI_API_KEY` di `.env` (lihat [API-AI-AGENT.md](https://github.com/lightnet19/LightBill/blob/main/lightbill-app/API-AI-AGENT.md))
- Python 3.10+

### Setup

```bash
git clone https://github.com/lightnet19/lightbill-mcp-server.git
cd lightbill-mcp-server
python3 -m venv venv
venv/bin/pip install fastmcp httpx
cp run.sh.example run.sh   # lalu isi LIGHTBILL_API_KEY
chmod +x run.sh
```

### Registrasi ke Hermes

```bash
hermes mcp add lightbill --command "$(pwd)/run.sh"
# → 134/134 tools enabled
```

### Registrasi ke client MCP lain (Claude Desktop, dll)

```json
{
  "mcpServers": {
    "lightbill": {
      "command": "/path/to/lightbill-mcp-server/run.sh"
    }
  }
}
```

## 🔑 Autentikasi

Server membaca `LIGHTBILL_API_KEY` dari environment (via `run.sh`). Key dikirim sebagai header `X-AI-Key` ke setiap request API LightBill.

```bash
# run.sh
export LIGHTBILL_BASE_URL="https://your-lightbill-domain.com"
export LIGHTBILL_API_KEY="your-ai-api-key"
```

## 🛠️ Daftar Tools (134)

| Kategori | Tools |
|---|---|
| Dashboard | `lb_dashboard` |
| Pelanggan | `lb_list_customers`, `lb_customer_create`, `lb_customer_update`, `lb_customer_delete`, `lb_customer_suspend`, `lb_customer_reactivate`, `lb_customer_sessions`, `lb_customer_usage` |
| Karyawan | `lb_staff_list`, `lb_staff_create`, `lb_staff_update`, `lb_staff_delete` |
| Router | `lb_list_routers`, `lb_router_create`, `lb_router_update`, `lb_router_delete`, `lb_router_sync`, `lb_router_test`, `lb_router_traffic`, `lb_router_resource`, `lb_router_syslog`, `lb_router_ip_pools`, `lb_router_ping_stats`, `lb_router_top_consumers`, `lb_router_active_sessions` |
| OLT | `lb_olt_health`, `lb_olt_create`, `lb_olt_update`, `lb_olt_delete`, `lb_olt_ont_list`, `lb_olt_ont_create`, `lb_olt_ont_delete`, `lb_olt_ont_reboot`, `lb_olt_ont_history`, `lb_olt_discovery`, `lb_olt_test`, `lb_olt_ztp_list`, `lb_olt_ztp_create` |
| Tagihan | `lb_list_invoices`, `lb_invoice_mark_paid`, `lb_invoice_generate` |
| Pembayaran | `lb_payment_verification_list`, `lb_payment_verification_approve`, `lb_payment_verification_reject`, `lb_payment_gateway_settings`, `lb_payment_gateway_set` |
| Paket & Template | `lb_list_packages`, `lb_package_create`, `lb_package_update`, `lb_package_delete`, `lb_list_templates`, `lb_template_create`, `lb_template_update`, `lb_template_delete` |
| Keuangan | `lb_finance_monthly`, `lb_finance_daily`, `lb_finance_yearly`, `lb_finance_overview`, `lb_expense_list`, `lb_expense_create`, `lb_expense_update`, `lb_expense_delete` |
| Hotspot & Mitra | `lb_hotspot_list`, `lb_hotspot_batch_detail`, `lb_hotspot_create_batch`, `lb_mitra_list`, `lb_mitra_create`, `lb_mitra_deposit`, `lb_mitra_edit` |
| Network | `lb_odc_list`, `lb_odc_create`, `lb_odc_update`, `lb_odc_delete`, `lb_odp_list`, `lb_odp_create`, `lb_odp_update`, `lb_odp_delete`, `lb_network_topology` |
| Helpdesk | `lb_ticket_list`, `lb_ticket_create`, `lb_ticket_action`, `lb_ticket_message`, `lb_chat_list`, `lb_chat_unread`, `lb_chat_reply`, `lb_chat_resolve` |
| Job & Backup | `lb_job_list`, `lb_job_create`, `lb_job_update_status`, `lb_job_delete`, `lb_activity_logs`, `lb_backup_export`, `lb_backup_logs`, `lb_backup_restore` |
| Analitik & HR | `lb_analytics_churn`, `lb_analytics_forecasting`, `lb_analytics_settings`, `lb_analytics_settings_set`, `lb_attendance_list`, `lb_attendance_check_in`, `lb_hr_incentives`, `lb_payroll_profiles`, `lb_payroll_profile_create`, `lb_payroll_generate`, `lb_hr_settings` |
| Inventaris | `lb_inventory_devices`, `lb_inventory_device_create`, `lb_inventory_device_update`, `lb_inventory_device_delete`, `lb_inventory_consumables`, `lb_inventory_consumable_create`, `lb_inventory_consumable_adjust`, `lb_inventory_logs`, `lb_inventory_borrow`, `lb_inventory_return`, `lb_inventory_install` |
| Lapangan & Radius | `lb_field_registrations`, `lb_field_registration_approve`, `lb_field_registration_reject`, `lb_isolir_lookup`, `lb_radius_sessions`, `lb_radius_kick`, `lb_radius_enforce_fup`, `lb_radius_reset_fup` |
| WhatsApp | `lb_whatsapp_status`, `lb_whatsapp_start`, `lb_whatsapp_stop`, `lb_whatsapp_send` |
| Tenant & Sistem | `lb_tenant_update`, `lb_tenant_subscription`, `lb_changelog`, `lb_api_get`, `lb_api_post` |

## ⚠️ Catatan Keamanan

- Aksi destruktif (delete) & berdampak layanan (reboot ONT, kick radius, restore backup) — konfirmasi manusia disarankan.
- Password router/OLT dienkripsi di database LightBill.
- Jangan commit `AI_API_KEY` ke repo — simpan di `run.sh` lokal (tidak di-versioned).

## 📦 Struktur

```
lightbill-mcp-server/
├── README.md
├── LICENSE
├── pyproject.toml
├── server.json              # MCP Registry manifest
├── run.sh                   # shell wrapper (WAJIB untuk FastMCP + Hermes)
├── run.sh.example           # template wrapper
└── lightbill_mcp_server/
    ├── __init__.py
    ├── __main__.py
    └── server.py            # 134 tools FastMCP
```

## 🤝 Kontribusi

Silakan buat issue/PR. Semua endpoint API LightBill baru bisa dibungkus dengan mudah — tambahkan `@mcp.tool()` di `server.py`.

## 📄 Lisensi

MIT — lihat [LICENSE](LICENSE).