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

```bash
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)
```