accurate-mcp-server

MCP server yang menghubungkan AI assistant (Claude, dll.) ke data Accurate Online secara langsung — tanya soal barang, stok, faktur, dan laporan keuangan dalam bahasa natural, dan AI menjawabnya dengan data asli dari Accurate, bukan perkiraan.

Alur: pertanyaan bahasa natural → server menerjemahkannya ke panggilan API Accurate → data asli dikembalikan ke AI untuk dirangkum.

Fitur

• 7 tools MCP untuk barang, faktur penjualan/pembelian, laba rugi, kas & bank, dan umur piutang.
• Login OAuth otomatis (bun run login) — sekali login, token di-refresh otomatis, tidak perlu copy-paste access token.
• Keandalan: retry otomatis saat session basi, retry dengan backoff saat kena rate limit (429), caching ringan untuk master data, dan log error yang jelas tanpa membocorkan token.

Daftar tools

Tool	Kegunaan	Endpoint Accurate
list_items	Daftar barang/jasa + stok	item/list.do, item/list-stock.do
get_item_detail	Detail satu barang/jasa	item/detail.do
list_sales_invoices	Daftar faktur penjualan	sales-invoice/list.do
list_purchase_invoices	Daftar faktur pembelian	purchase-invoice/list.do
profit_loss_report	Laporan laba rugi	glaccount/get-pl-account-amount.do
cash_flow_report	Saldo kas & bank	glaccount/get-bs-account-amount.do
accounts_receivable_aging	Umur piutang per jatuh tempo	sales-invoice/list.do (belum lunas)

Kebutuhan

• Bun terinstall (curl -fsSL https://bun.sh/install | bash)
• Akun developer Accurate Online (daftar gratis di area developer Accurate)
• Akun Accurate Online aktif (trial pun cukup untuk uji coba)

1. Install dependencies

bun install

2. Login OAuth otomatis (disarankan)

Cara paling nyaman: server login ke Accurate atas nama kamu lewat browser, lalu menyimpan token secara otomatis — tidak perlu copy-paste access token lagi.

1. Daftar aplikasi di area developer Accurate Online, pilih platform Website (agar bisa pakai authorization code + refresh token).
2. Isi URL OAuth Callback dengan http://localhost:8000/callback.
3. Catat Client ID dan Client Secret aplikasi.
4. Salin .env.example jadi .env dan isi:

cp .env.example .env

ACCURATE_CLIENT_ID=<client id kamu>
ACCURATE_CLIENT_SECRET=<client secret kamu>

5. Jalankan login sekali:

bun run login

Browser akan terbuka ke halaman login Accurate. Setelah kamu izinkan, token disimpan di ~/.accurate-mcp/credentials.json. Refresh token dipakai otomatis saat access token kedaluwarsa, jadi kamu cukup login sekali.

Scope default yang diminta: item_view sales_invoice_view purchase_invoice_view. Kalau sudah pernah login dengan scope lama dan list_purchase_invoices error soal scope, jalankan bun run login sekali lagi untuk memperbarui izin.

Kalau redirect URI / scope ingin berbeda, set ACCURATE_REDIRECT_URI dan ACCURATE_SCOPE di .env — redirect URI harus sama persis dengan yang didaftarkan di area developer.

3. Dapatkan Access Token dari Accurate Online (cara manual)

Alternatif jika tidak mau pakai OAuth otomatis: ikuti alur OAuth 2.0 standar Accurate untuk mendapat Access Token — pilih scope minimal yang dibutuhkan: item_view, sales_invoice_view, purchase_invoice_view. Lalu isi di .env:

ACCURATE_ACCESS_TOKEN=<access token kamu>

4. Cari ID database (kalau akun kamu punya lebih dari satu perusahaan)

Jalankan server sekali:

bun run start

Kalau ACCURATE_DB_ID kosong dan akun kamu punya lebih dari satu database, server akan otomatis pakai database pertama dan menulis ke stderr database mana yang dipakai (plus daftar pilihan lain). Kalau mau pilih yang lain, isi ACCURATE_DB_ID di .env dengan ID dari log tersebut (atau lihat kode di src/accurate-client.ts).

Penting: akun Accurate kamu harus punya minimal satu database/perusahaan (bisa yang trial). Kalau db-list.do mengembalikan daftar kosong, server akan melaporkan "Token ini tidak punya akses ke database manapun" — buat/aktifkan dulu database di akun Accurate sebelum menguji tools.

5. Sambungkan ke Claude Desktop

Tambahkan ke config MCP Claude Desktop kamu (claude_desktop_config.json):

{
  "mcpServers": {
    "accurate-online": {
      "command": "bun",
      "args": ["run", "/path/lengkap/ke/accurate-mcp-server/src/index.ts"],
      "env": {
        "ACCURATE_CLIENT_ID": "isi-client-id-kamu",
        "ACCURATE_CLIENT_SECRET": "isi-client-secret-kamu",
        "ACCURATE_DB_ID": ""
      }
    }
  }
}

Kalau sudah pernah login (bun run login), token diambil otomatis dari ~/.accurate-mcp/credentials.json — tanpa token statis di config. Kalau belum, server memakai ACCURATE_ACCESS_TOKEN dari config sebagai fallback.

Restart Claude Desktop, lalu coba tanya: "barang apa saja yang stoknya sedikit?" atau "tampilkan 5 faktur penjualan terbaru".

6. Contoh pertanyaan untuk diuji

Contoh pertanyaan natural language yang bisa dicoba di Claude Desktop:

1. "Barang apa saja yang stoknya mau habis?"
2. "Cek stok barang X" — ganti X dengan nama barang.
3. "List 5 barang dengan stok terbanyak."
4. "Tampilkan 5 faktur penjualan terbaru."
5. "Berapa omzet dari faktur-faktur terbaru?"
6. "Faktur penjualan mana saja yang paling besar nilainya?"
7. "Cari barang dengan nama mengandung kata 'kabel'."
8. "Detail barang dengan no 002?"
9. "Barang apa yang paling banyak stoknya?"
10. "Berapa total penjualan bulan ini?"
11. "Tampilkan 5 faktur pembelian terbaru."
12. "Berapa laba bersih bulan ini?" (pakai profit_loss_report)
13. "Berapa saldo kas dan bank saya?" (pakai cash_flow_report)
14. "Berapa piutang yang sudah lewat jatuh tempo?" (pakai accounts_receivable_aging)

Catatan: jawaban AI sebaiknya selalu memanggil tool (list_items, get_item_detail, list_sales_invoices, dll.) supaya datanya asli dari Accurate, bukan perkiraan. Kalau AI menjawab tanpa memanggil tool, minta dia memakai tool.

7. Referensi konfigurasi (.env)

Variabel	Wajib?	Keterangan
ACCURATE_CLIENT_ID	untuk mode OAuth	Client ID aplikasi dari area developer Accurate
ACCURATE_CLIENT_SECRET	untuk mode OAuth	Client Secret aplikasi
ACCURATE_ACCESS_TOKEN	mode token statis	Access Token manual (fallback kalau belum bun run login)
ACCURATE_DB_ID	opsional	ID database/perusahaan yang dipakai; kosong = database pertama
ACCURATE_REDIRECT_URI	opsional	Redirect URI OAuth; default http://localhost:8000/callback
ACCURATE_SCOPE	opsional	Scope OAuth; default item_view sales_invoice_view purchase_invoice_view
ACCURATE_CREDENTIALS_PATH	opsional	Lokasi file kredensial OAuth; default ~/.accurate-mcp/credentials.json

8. Pesan error yang dikenal

Error mentah dari Accurate API sudah dipetakan ke pesan ramah di src/accurate-client.ts:

Error mentah dari Accurate	Pesan yang ditampilkan ke AI/user
HTTP 401 {"error":"invalid_token"}	Token tidak valid atau sudah kedaluwarsa. Perbarui ACCURATE_ACCESS_TOKEN di .env.
{"s":false,"d":["Data Usaha tidak tepat"]}	Database/perusahaan tidak ditemukan atau tidak bisa dibuka. Periksa ACCURATE_DB_ID.
{"s":false,"d":["Barang & Jasa tidak tepat"]}	Barang/jasa dengan ID tersebut tidak ditemukan. Gunakan list_items untuk melihat ID yang valid.
{"s":false,"d":["Pelanggan ... tidak ditemukan"]}	Customer tidak ditemukan atau sudah dihapus. Periksa nomor customer pada transaksi.
{"s":false,"d":["Barang ... tidak ditemukan"]}	Barang tidak ditemukan. Gunakan list_items untuk melihat kode barang yang valid.
HTTP 403 XML InsufficientScopeException	Token tidak punya izin (scope) untuk fitur ini. Buat ulang access token dengan scope yang dibutuhkan.
Daftar database kosong d:[]	Token ini tidak punya akses ke database manapun. (Akun harus punya minimal satu perusahaan/database di Accurate.)
HTTP 429 (rate limit)	Terlalu banyak permintaan ke Accurate (rate limit). Coba lagi beberapa saat.
HTTP 5xx	Server Accurate sedang bermasalah (HTTP xxx). Coba lagi nanti.

9. Demo & screenshot

Jalankan bun run demo untuk menampilkan transkrip "pertanyaan → jawaban" dari seluruh tools dengan data Accurate sungguhan (butuh login + database aktif):

bun run demo

Transkrip ini bisa kamu pakai sebagai bahan screenshot atau video singkat pemakaian di Claude Desktop.

Struktur project

src/
  accurate-client.ts   # auth, session/host management, HTTP calls, cache & retry
  oauth.ts              # OAuth flow otomatis (login, refresh token, kredensial)
  login.ts              # CLI `bun run login`
  demo.ts               # CLI `bun run demo` (transkrip untuk screenshot/video)
  tools/index.ts        # definisi tools MCP (list_items, laporan, dll)
  tools/report-utils.ts # helper murni laporan (tanggal, laba rugi, aging)
  index.ts              # entry point, wiring stdio server

Yang perlu diperhatikan (dari dokumentasi resmi Accurate)

• Host API bisa berubah sewaktu-waktu dan Accurate akan mengirim redirect HTTP 308 ke host baru. fetch di Bun mengikuti redirect secara default, jadi ini sudah tertangani — tapi jangan set redirect: "manual" di tempat lain.
• Session basi: kalau dapat error 401, client akan otomatis buka ulang database dan retry sekali.
• Rate limit: Accurate membatasi jumlah pemanggilan API. Server sudah melakukan retry dengan backoff saat kena HTTP 429, dan master data di-cache ringan biar tidak boros panggilan.
• Access token bisa bersifat personal (satu user, satu akun Accurate) via bun run login yang menyimpan token di ~/.accurate-mcp/credentials.json (di luar repo). Token di-refresh otomatis saat kedaluwarsa. Untuk versi multi-user/hosted, tetap perlu redesign ke arah OAuth per-request.

FAQ

Kenapa list_purchase_invoices error soal scope? Token yang tersimpan belum punya scope purchase_invoice_view. Jalankan bun run login sekali lagi untuk meminta scope baru.

Data AI tidak sama dengan yang di Accurate? Pastikan AI memanggil tool (bukan menebak). Kalau jawaban datang tanpa memanggil tool, minta dia memakai tool yang tersedia.

Stok barang tidak muncul di list_items? Stok diambil dari endpoint terpisah (item/list-stock.do) dan di-cache 1 menit. Kalau baru saja ada transaksi, tunggu sebentar atau mulai ulang proses server.

Berkontribusi

• Laporkan bug atau minta fitur lewat Issues.
• Pull request dipersilakan. Jalankan bun test dan bun run typecheck sebelum mengirim PR.
• Komentar, pesan error, dan deskripsi tool ditulis dalam Bahasa Indonesia.

Lisensi

MIT