mcp-sample-bip/README.md

Contoh server MCP sederhana untuk Flowise.

# mcp-sample-bip

Server [Model Context Protocol](https://modelcontextprotocol.io) yang siap dipakai bersama Flowise untuk melakukan proxy terhadap API berbasis OpenAPI. Proyek ini menampilkan bagaimana tool MCP dapat di-*register* secara dinamis dan dijalankan melalui STDIO.

## Fitur Utama
- Koneksi STDIO yang langsung kompatibel dengan Flowise.
- Dua tool bawaan (`greet_user`, `get_server_time`) untuk contoh dasar.
- Registrasi tool otomatis dari dokumen OpenAPI (`/docs/json`) lengkap dengan validator input.
- Mekanisme cache lokal (`.mcp-cache.json`) agar start-up cepat, dengan flag `--update` untuk refresh manual.
- Dukungan *environment variable* `JENNA_MCP_BASE_URL` dan `JENNA_MCP_API_TOKEN` untuk koneksi ke backend yang membutuhkan autentikasi.

## Menjalankan via npx
Gunakan paket npm (tanpa cloning repositori):

```bash
npx -y mcp-sample-bip
# atau: JENNA_MCP_BASE_URL=https://example.com npx -y mcp-sample-bip
```

Perintah di atas mem-boot server MCP melalui STDIO sehingga Flowise atau klien MCP lain dapat terhubung.

### Menyegarkan cache OpenAPI

```bash
npx -y mcp-sample-bip --update
```

Flag `--update` memaksa pengambilan ulang dokumen OpenAPI dan menimpa `.mcp-cache.json` pada direktori kerja saat ini.

## Integrasi dengan Flowise
1. Buka menu *Settings* → *MCP Servers* di Flowise.
2. Tambahkan entri baru dengan command `npx -y mcp-sample-bip`.
3. Jika backend membutuhkan autentikasi, tambahkan env `JENNA_MCP_API_TOKEN` dan `JENNA_MCP_BASE_URL` di form yang sama.
4. Simpan; tool MCP akan muncul di panel Flow builder dan siap digunakan.

Contoh konfigurasi (ditulis ulang dari *Flowise MCP JSON*):

```json
{
  "command": "npx",
  "args": ["-y", "mcp-sample-bip"],
  "env": {
    "JENNA_MCP_API_TOKEN": "<token-anda>",
    "JENNA_MCP_BASE_URL": "https://example.com"
  }
}
```

## Variabel Lingkungan
- `JENNA_MCP_BASE_URL` (**wajib** bila ingin memuat OpenAPI eksternal): Basis URL yang di-*fetch* untuk `GET /docs/json`.
- `JENNA_MCP_API_TOKEN`: Token yang otomatis disertakan pada header `Authorization: Bearer <token>`.

Apabila `JENNA_MCP_BASE_URL` tidak diisi, server masih berjalan dengan tool bawaan sehingga cocok untuk demonstrasi cepat.

## Pengembangan Lokal
Install dependensi, build TypeScript, lalu jalankan server:

```bash
npm install
npm run build
node dist/cli.js
# atau: npm start  # build lalu menjalankan server
```

Selama proses aktif, server siap menerima koneksi MCP melalui STDIO. File `.mcp-cache.json` akan tersimpan di direktori kerja; hapus file tersebut bila ingin memulai ulang tanpa cache.

## Troubleshooting
- Pastikan koneksi jaringan mengizinkan akses ke `JENNA_MCP_BASE_URL` ketika pertama kali menjalankan server.
- Bila tool OpenAPI tidak muncul, jalankan ulang dengan `--update` untuk memastikan cache terbaru terambil.
- Gunakan flag `--update` secara berkala jika skema OpenAPI backend sering berubah.