# MCP Server (Claude & Cursor)

`@omnistreams/mcp-server` adalah [Model Context Protocol](https://modelcontextprotocol.io)
server yang menjembatani OmniStream API ke klien MCP seperti **Claude Desktop**,
**Claude Code**, dan **Cursor**. Asisten AI dapat membaca inbox dan mengirim
pesan atas nama Anda lewat percakapan biasa.

## Tools yang tersedia

| Tool | Fungsi |
|---|---|
| `list_conversations` | Daftar percakapan (filter status/agen, paginasi) |
| `get_conversation` | Ambil satu percakapan |
| `list_messages` | Daftar pesan dalam percakapan |
| `send_message` | Kirim pesan keluar (teks atau konten kaya) |
| `list_contacts` | Daftar / cari kontak |
| `search_messages` | Cari teks pesan lintas percakapan |
| `list_templates` | Daftar template WhatsApp |

Semua tool baca bersifat read-only; hanya `send_message` yang melakukan
perubahan.

## Setup

### 1. Buat API key

Buat **REST API key** di **Developer → API Keys**. Disarankan mengunci key ke IP
server Anda lewat **Allowed IPs**.

### 2. Daftarkan di klien MCP

**Claude Desktop / Claude Code** (`claude_desktop_config.json` atau `.mcp.json`):

```json
{
  "mcpServers": {
    "omnistream": {
      "command": "npx",
      "args": ["-y", "@omnistreams/mcp-server"],
      "env": {
        "OMNISTREAM_API_KEY": "os_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "OMNISTREAM_BASE_URL": "https://api.omnistream.example"
      }
    }
  }
}
```

### 3. Coba

Minta asisten Anda, misalnya: *"tampilkan percakapan WhatsApp yang masih open"*
atau *"balas percakapan <id> dengan 'Segera saya proses'"*.

## Konfigurasi

| Variabel | Wajib | Default | Keterangan |
|---|---|---|---|
| `OMNISTREAM_API_KEY` | ✅ | — | REST API key (`os_..._...`) |
| `OMNISTREAM_BASE_URL` | | `http://localhost:3000` | Base URL API gateway |
| `OMNISTREAM_TIMEOUT_MS` | | `30000` | Timeout per request (ms) |

:::info Keamanan
API key dikirim sebagai header `X-API-Key` dan tidak pernah di-log. Output
diagnostik ditulis ke stderr agar tidak mengganggu stream JSON-RPC MCP di
stdout. Semua aksi mewarisi RBAC pemilik key.
:::