# 🚀 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.
