# 🚀 Superset MCP Server (Streamable HTTP)

MCP (Model Context Protocol) Server untuk Apache Superset yang memungkinkan integrasi chatbot dengan Superset untuk membuat dashboard, chart, dan mengeksekusi query SQL secara programatis.

## ✨ Fitur

- 📊 **Dashboard Management** - List, get, create dashboard dan tambahkan chart ke dashboard
- 📈 **Chart Management** - List, get, create chart dengan auto-detection schema
- 🗃️ **Dataset Management** - List datasets dan get schema kolom
- 🔍 **SQL Execution** - Eksekusi query SQL langsung ke database Superset
- 🔄 **Stateless HTTP** - Menggunakan Streamable HTTP transport untuk kompatibilitas dengan Open WebUI
- 🔐 **Auto Authentication** - Otomatis login dan refresh token ke Superset

## 🛠️ Teknologi

- **Runtime**: Node.js + TypeScript
- **Transport**: Express.js + JSON-RPC 2.0
- **Protocol**: MCP (Model Context Protocol)
- **Client**: Axios untuk HTTP requests

## 📋 Prasyarat

- Node.js v18 atau lebih baru
- Apache Superset yang sudah running
- NPM atau Yarn

## ⚡ Quick Start

### 1. Clone & Install Dependencies

```bash
git clone <repository-url>
cd superset-mcp
npm install
```

### 2. Konfigurasi Environment

Salin file `.env.example` ke `.env` dan sesuaikan konfigurasinya:

```bash
cp .env.example .env
```

Isi konfigurasi di file `.env`:

```env
# Superset Configuration
SUPERSET_URL=http://localhost:8088
SUPERSET_USERNAME=admin
SUPERSET_PASSWORD=admin

# MCP Server Configuration
MCP_PORT=3000
```

### 3. Build & Run

```bash
# Build TypeScript
npm run build

# Jalankan server
npm start
```

Atau untuk development dengan hot-reload:

```bash
npm run dev
```

### 4. Verifikasi Server

Akses health check endpoint:

```bash
curl http://localhost:3000/health
```

Response yang diharapkan:

```json
{
  "status": "ok",
  "server": "superset-mcp",
  "version": "1.0.0",
  "mode": "stateless",
  "tools": ["list_dashboards", "get_dashboard", "create_dashboard", ...]
}
```

## 🔌 Integrasi dengan Open WebUI

### Konfigurasi di Open WebUI

1. Buka **Admin Panel** → **Tools** → **Tool Connections**
2. Tambahkan MCP Server baru:
   - **Name**: Superset MCP
   - **Type**: MCP (Streamable HTTP)
   - **URL**: `http://YOUR_SERVER_IP:3000/mcp`
3. Save dan test koneksi

## 🔧 Available Tools

### Dashboard Tools

| Tool | Deskripsi |
|------|-----------|
| `list_dashboards` | Mendapatkan semua dashboard yang tersedia |
| `get_dashboard` | Detail dashboard termasuk chart-chart di dalamnya |
| `create_dashboard` | Membuat dashboard baru |
| `add_chart_to_dashboard` | Menambahkan satu chart ke dashboard |
| `add_charts_to_dashboard` | Menambahkan multiple charts ke dashboard (recommended) |

### Chart Tools

| Tool | Deskripsi |
|------|-----------|
| `list_charts` | Mendapatkan semua chart yang tersedia |
| `get_chart` | Detail konfigurasi chart |
| `get_chart_data` | Fetch data dari chart |
| `create_chart` | Membuat chart baru (manual config) |
| `create_chart_auto` | Membuat chart dengan auto-detection schema |

### Dataset Tools

| Tool | Deskripsi |
|------|-----------|
| `list_datasets` | Mendapatkan semua datasets/tables |
| `get_dataset_schema` | Mendapatkan definisi kolom dari dataset |

### SQL Tools

| Tool | Deskripsi |
|------|-----------|
| `list_databases` | Mendapatkan semua koneksi database |
| `execute_sql` | Eksekusi query SQL ke database |

## 📚 Contoh Penggunaan

### Membuat Chart dengan Auto-Detection

```
"Buatkan bar chart untuk dataset sales_data yang menampilkan total revenue per bulan"
```

AI akan menggunakan `create_chart_auto` untuk:
1. Menganalisis schema dataset
2. Mendeteksi kolom waktu (x_axis)
3. Mendeteksi kolom numeric untuk metrics
4. Membuat chart dengan konfigurasi optimal

### Membuat Dashboard dengan Multiple Charts

```
"Buatkan dashboard Sales Overview dengan 3 chart: line chart revenue, pie chart by category, dan table top products"
```

AI akan:
1. `create_dashboard` - Membuat dashboard baru
2. `create_chart_auto` (3x) - Membuat setiap chart
3. `add_charts_to_dashboard` - Menambahkan semua chart sekaligus dengan layout optimal

## 🏗️ Struktur Project

```
superset-mcp/
├── src/
│   ├── index.ts          # Entry point
│   ├── server.ts         # Express server & MCP tools
│   └── superset-client.ts # Superset API client
├── dist/                  # Compiled JavaScript
├── .env                   # Environment variables
├── .env.example           # Example environment
├── package.json
├── tsconfig.json
└── README.md
```

## 🔗 API Endpoints

| Endpoint | Method | Deskripsi |
|----------|--------|-----------|
| `/health` | GET | Health check |
| `/mcp` | POST | MCP JSON-RPC requests |
| `/mcp` | GET | SSE streaming (keepalive) |
| `/mcp` | DELETE | Session cleanup |

## ⚙️ Environment Variables

| Variable | Default | Deskripsi |
|----------|---------|-----------|
| `SUPERSET_URL` | `http://localhost:8088` | URL Superset instance |
| `SUPERSET_USERNAME` | `admin` | Username untuk login |
| `SUPERSET_PASSWORD` | `admin` | Password untuk login |
| `MCP_PORT` | `3000` | Port untuk MCP server |

## 🐛 Troubleshooting

### 1. Authentication Failed

Pastikan credentials di `.env` sudah benar. Server akan otomatis refresh token jika expired.

### 2. CORS Error

Server sudah dikonfigurasi untuk menerima requests dari semua origin. Jika masih error, pastikan firewall tidak memblokir port.

### 3. Chart Tidak Menampilkan Data

Gunakan `create_chart_auto` daripada `create_chart` untuk auto-detection metrics dan dimensions.

## 📄 License

MIT License

## 🤝 Contributing

Contributions are welcome! Feel free to open issues atau pull requests.