BILLZ MCP ko'prik serveri

Bu loyiha BILLZ 2.0 REST API (https://api-admin.billz.ai) bilan Claude o'rtasida "ko'prik" vazifasini bajaradi. Claude bu server orqali BILLZ'dagi mahsulotlar, savdolar, mijozlar va boshqa ma'lumotlarni o'qiy oladi.

1. Nima kerak bo'ladi

• Node.js 18+ (loyihani ishga tushirish uchun)
• BILLZ 2.0 dan olingan Client ID (login) va API kalit (secret) (rasmda ko'rgan "Advanced settings" ichidagi ikkita maydon)
• Serverni internetga chiqarish uchun bepul hosting hisobi (masalan Render.com yoki Railway.app)

2. Endpoint yo'llari haqida

✅ Autentifikatsiya (login) qismi tasdiqlangan va to'g'ri ishlaydi — rasmiy BILLZ hujjatidagi "Аутентификация" bo'limiga asosan yozilgan: POST /v1/auth/login + {"secret_token": "..."}.

⚠️ Mahsulotlar/savdolar/mijozlar uchun ishlatilgan yo'llar (/v1/products, /v1/orders, /v1/clients, /v1/categories) hali taxminiy — chunki BILLZ hujjatidagi "Методы" bo'limi hali tasdiqlanmagan. Bu bo'limni ochib, aniq yo'llarni tekshiring: https://billzuz.notion.site/API-c2f91aa254f94f8eb7c1b26415dcb25b

Shuning uchun avvaliga faqat billz_request (umumiy so'rov) vositasini ishlating — u har qanday to'g'ri yo'l bilan ishlaydi, chunki faqat to'g'ri autentifikatsiyaga bog'liq. Masalan Claude'ga: "billz_request orqali GET /v1/products yo'liga so'rov yubor" deb aytishingiz mumkin — agar yo'l noto'g'ri bo'lsa, xatolik xabari chiqadi va tuzatib beraman.

3. Kompyuteringizda sinab ko'rish (ixtiyoriy)

cd billz-mcp-server
npm install
cp .env.example .env
# .env faylini ochib, BILLZ_LOGIN, BILLZ_SECRET va MCP_BRIDGE_SECRET
# qiymatlarini to'ldiring
npm start

Brauzerda http://localhost:3000/health ochilsa, server ishlayapti degani.

4. Internetga chiqarish (Render.com misolida)

1. Bu loyihani GitHub'ga yuklang (yangi repository yarating, fayllarni push qiling).
2. https://render.com saytida ro'yxatdan o'ting.
3. New + → Web Service → GitHub repositoryingizni tanlang.
4. Sozlamalar:
   • Build Command: npm install
   • Start Command: npm start
5. Environment bo'limida quyidagilarni qo'shing:
   • BILLZ_BASE_URL = https://api-admin.billz.ai
   • BILLZ_LOGIN = (sizning Client ID'ingiz, masalan 200400493)
   • BILLZ_SECRET = (sizning API kalitingiz)
   • MCP_BRIDGE_SECRET = (o'zingiz o'ylab topgan uzun tasodifiy matn)
6. Create Web Service tugmasini bosing va deploy tugashini kuting.
7. Render sizga shunga o'xshash manzil beradi: https://billz-mcp-server-xxxx.onrender.com

5. Claude'ga ulash

1. Claude'da Customize → Connectors → "+" → Add custom connector oynasini oching (yoki tashkilot Owner'i Organization Settings orqali).
2. Name: BILLZ
3. Remote MCP server URL: https://billz-mcp-server-xxxx.onrender.com/mcp (albatta oxirida /mcp bilan tugashi kerak — bu Notion yoki dashboard havolasi emas, endi bu sizning o'z serveringiz manzili)
4. Advanced settings ichidagi maydonlarga (agar OAuth emas, oddiy token so'ralsa) MCP_BRIDGE_SECRET qiymatini kiriting.
5. Add tugmasini bosing.

Shundan keyin Claude'ga: "BILLZ'dagi mahsulotlar ro'yxatini ko'rsat" yoki "BILLZ'dan oxirgi 30 kunlik savdolarni ol" deb yozsangiz, u avtomatik ravishda billz_get_products yoki billz_get_orders vositalarini chaqiradi.

6. Xavfsizlik eslatmalari

• .env faylini hech qachon GitHub'ga (ochiq repositoryga) yuklamang — .gitignore fayliga .env qatorini albatta qo'shing.
• MCP_BRIDGE_SECRET — bu serveringizni begonalardan himoya qiladi. Uni ham hech kimga bermang.
• Agar BILLZ_SECRET biror joyda oshkor bo'lsa (masalan chatga yozib yuborilsa), BILLZ panelida darhol uni bekor qilib, yangisini yarating.

7. Fayllar tuzilishi

billz-mcp-server/
├── package.json          # bog'liqliklar ro'yxati
├── .env.example           # sozlamalar namunasi
├── README.md               # ushbu qo'llanma
└── src/
    ├── billzClient.js     # BILLZ API bilan gaplashish (autentifikatsiya + so'rov)
    └── server.js          # MCP server (Claude bilan gaplashadigan qism)