# STB MCP Server

> mcp-name: io.github.lightnet19/stb-mcp-server

[![MCP Registry](https://img.shields.io/static/v1?label=MCP%20Registry&message=io.github.lightnet19%2Fstb-mcp-server&color=blue)](https://registry.modelcontextprotocol.io/v0/servers/io.github.lightnet19%2Fstb-mcp-server/versions)
[![PyPI version](https://img.shields.io/pypi/v/stb-mcp-server.svg)](https://pypi.org/project/stb-mcp-server/)



MCP Server untuk kontrol penuh server STB (Amlogic S9xx / Armbian) — SSH via Cloudflare Tunnel + CasaOS + AdGuard Home.

Dibuat untuk [Hermes Agent](https://hermes-agent.nousresearch.com) oleh [Fuad Al Fajri](https://github.com/lightnet19).

## Tools

| # | Tool | Fungsi |
|---|------|--------|
| 1 | `stb_execute` | 🔧 Jalankan perintah shell |
| 2 | `stb_read_file` | 📄 Baca file |
| 3 | `stb_write_file` | ✏️ Tulis file |
| 4 | `stb_system_info` | 📊 Info sistem (OS, CPU, RAM, disk, uptime, suhu) |
| 5 | `stb_docker_list` | 🐳 Daftar container running |
| 6 | `stb_docker_logs` | 📋 Log container (tail N baris) |
| 7 | `stb_docker_restart` | 🔄 Restart container |
| 8 | `stb_docker_stats` | 📈 Resource CPU/RAM container |
| 9 | `stb_adguard_config` | 🛡️ Parameter utama AdGuard Home |
| 10 | `stb_adguard_full_config` | 📑 Full file YAML AdGuard |
| 11 | `stb_adguard_stats` | 📉 Statistik DNS AdGuard |
| 12 | `stb_cleanup_root` | 🧹 Bersihkan root filesystem |
| 13 | `stb_casaos_status` | 🏠 Status CasaOS |

## Instalasi

### Prasyarat
- Python 3.10+
- SSH key dengan akses ke server target
- `cloudflared` di PATH (untuk tunnel proxy)

### Instalasi dari PyPI (Recommended)

```bash
pip install stb-mcp-server
```

### Setup dari Source

```bash
git clone https://github.com/lightnet19/stb-mcp-server
cd stb-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -e .

# Register ke Hermes Agent
hermes mcp add stb --command "$(pwd)/run.sh"
```

### Konfigurasi SSH

Server membaca environment variables saat start. Default aman untuk publik (placeholder) — override per instance via env:

| Variabel | Default | Keterangan |
|----------|---------|------------|
| `STB_HOST` | `sshstb.your-domain.example.com` | Hostname/IP server target |
| `STB_USER` | `root` | User SSH |
| `STB_KEY` | `~/.ssh/stb_alfajri` | Path private key |
| `STB_PROXY_HOST` | nilai `STB_HOST` | Host untuk tunnel proxy (`cloudflared access ssh`); **kosongkan** jika koneksi langsung (OVPN/LAN) |

### Multi-Host (beberapa STB)

Satu codebase bisa melayani banyak STB sekaligus — daftarkan instance MCP terpisah, masing-masing dengan wrapper + file env sendiri:

```bash
# .stb1.env (STB1 — via Cloudflare Tunnel)
STB_HOST=stb1.your-domain.example.com
STB_USER=root
STB_KEY=/home/user/.ssh/stb1_key
STB_PROXY_HOST=stb1.your-domain.example.com
```

```bash
# .stb2.env (STB2 — via OVPN/LAN, tanpa proxy)
STB_HOST=10.0.0.5
STB_USER=root
STB_KEY=/home/user/.ssh/stb2_key
STB_PROXY_HOST=
```

```bash
# run-stb2.sh (wrapper instance kedua)
#!/bin/bash
cd /path/to/stb-mcp-server
export PYTHONUNBUFFERED=1
set -a; source /path/to/stb-mcp-server/.stb2.env; set +a
exec /path/to/stb-mcp-server/venv/bin/python3 -m stb_mcp_server
```

```bash
# Register instance kedua ke Hermes Agent
hermes mcp add stb2 --command "/path/to/stb-mcp-server/run-stb2.sh"
```

> ⚠️ File `.env` berisi kredensial — sudah ada `.env*` di `.gitignore`, JANGAN pernah di-commit ke repo publik.

## Cara Kerja

```
[Hermes Agent] → MCP stdio → [stb-mcp-server] → SSH → [Server STB]
```

Semua tool dieksekusi via SSH ke server target. SSH key + Cloudflare Tunnel digunakan untuk koneksi aman tanpa port terbuka.

## Struktur Project

```
stb-mcp-server/
├── pyproject.toml          # Package metadata
├── README.md               # Dokumentasi
├── CONTRIBUTING.md         # Panduan kontribusi
├── LICENSE                 # MIT License
├── run.sh                  # Wrapper script (Hermes entry point)
└── stb_mcp_server/
    ├── __init__.py
    ├── __main__.py          # python3 -m entry point
    └── server.py            # Tools MCP (FastMCP)
```

## Publikasi

- **GitHub**: [lightnet19/stb-mcp-server](https://github.com/lightnet19/stb-mcp-server)
- **Lisensi**: MIT

## Kontribusi

Silakan lihat [CONTRIBUTING.md](CONTRIBUTING.md) untuk panduan kontribusi.