🔌 Apa itu MCP?

MCP (Model Context Protocol) adalah protokol yang menghubungkan asisten suara XiaoZhi dengan knowledge base Xiaozhi Indonesia. Dengan MCP, XiaoZhi bisa membaca materi, mengontrol smarthome, memutar lagu, dan lainnya.

📋 Langkah-Langkah Setup MCP

Buka Website XiaoZhi

Kunjungi https://xiaozhi.me dan login ke akun XiaoZhi kamu.

Ambil Token MCP

Di halaman XiaoZhi, cari menu "MCP Endpoint" atau "Koneksi MCP".
Salin URL yang dimulai dengan wss://

Contoh: wss://api.xiaozhi.me/mcp/?token=eyJhbGciOiJFUzI1Ni...

💡 Tips: Pastikan menyalin URL LENGKAP, bukan hanya token-nya saja!

Tempel di Dashboard Xiaozhi Indonesia

Kembali ke halaman Dashboard Xiaozhi Indonesia.
Cari bagian "Koneksi XiaoZhi" di sidebar kanan.
Tempel URL MCP yang sudah disalin, lalu klik "Simpan".

Tunggu Koneksi

Setelah menyimpan, sistem akan mencoba menghubungkan ke XiaoZhi.
Tunggu beberapa detik hingga status berubah menjadi "Terhubung".

Verifikasi di XiaoZhi

Kembali ke https://xiaozhi.me.
Cek apakah status MCP sudah "Online" atau "Terhubung".
Jika sudah, XiaoZhi sudah bisa membaca data dari Xiaozhi Indonesia!

⚠️ Troubleshooting MCP

Jika koneksi gagal:

Pastikan URL dimulai dengan wss://
Pastikan menyalin URL LENGKAP (bukan hanya token)
Coba hapus dan simpan ulang token
Periksa koneksi internet

🎵 Cara Kerja YouTube Music

Fitur YouTube Music memungkinkan XiaoZhi mencari dan memutar lagu dari YouTube. Audio akan di-stream langsung ke perangkat ESP32 yang terhubung ke speaker.

🔄 Arsitektur Sistem

┌─────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────┐
│   User      │────▶│   XiaoZhi API   │────▶│  Xiaozhi Indo   │────▶│   YouTube   │
│  (Suara)    │     │   (xiaozhi.me)  │     │   (Server)      │     │   (yt-dlp)  │
└─────────────┘     └─────────────────┘     └─────────────────┘     └─────────────┘
                                              │           ▲
                                              │           │
                                              ▼           │
                                        ┌─────────────────┐
                                        │    ESP32        │
                                        │  (Audio Player) │
                                        └─────────────────┘
                                              │
                                              ▼
                                        ┌─────────────────┐
                                        │    Speaker      │
                                        └─────────────────┘

⚙️ Alur Kerja Detail

User Minta Lagu via Suara

Kamu katakan ke XiaoZhi: "Putar lagu Bohemian Rhapsody"
XiaoZhi (di xiaozhi.me) akan mengirim permintaan ke server Xiaozhi Indonesia melalui MCP.

Server Xiaozhi Indonesia Menerima Request

Server menerima request MCP dan memanggil tool play_youtube_song.
Tool ini menggunakan library yt-dlp untuk mencari lagu di YouTube.

# Dipanggil otomatis oleh MCP:
play_youtube_song(query="Bohemian Rhapsody")

yt-dlp Mencari & Mengambil Audio Stream

yt-dlp akan:
• Mencari video di YouTube berdasarkan query
• Mengambil URL audio stream (format m4a/webm)
• Mengembalikan title, duration, dan stream_url

Server Menyimpan ke Audio Queue

Server menyimpan perintah audio ke database (tabel audio_queue):
• title: Judul lagu
• stream_url: URL audio stream
• video_url: URL video YouTube
• status: pending

ESP32 Polling ke Server

ESP32 secara berkala (setiap 2-5 detik) melakukan polling ke server untuk mengecek apakah ada perintah audio baru.

GET https://xiaozhiscig.biz.id/api/audio/commands/{device_id}

ESP32 Menerima & Memutar Audio

ESP32 menerima response berisi stream_url, lalu:
• Download audio dari stream_url
• Decode audio (m4a/webm → PCM)
• Putar melalui speaker via I2S/DAC

ESP32 Kirim Konfirmasi

Setelah audio selesai diputar, ESP32 mengirim konfirmasi ke server bahwa perintah sudah dieksekusi.

POST https://xiaozhiscig.biz.id/api/audio/ack/{command_id}
Body: { "device_id": "esp32-xxx" }

📡 Endpoint API untuk Firmware ESP32

Berikut adalah endpoint yang perlu diimplementasikan di firmware ESP32. Copy URL ini ke kode firmware.

Base URL

https://xiaozhiscig.biz.id

1. Polling Perintah Audio

ESP32 harus melakukan polling ke endpoint ini setiap 2-5 detik untuk mengecek perintah audio baru.

GET https://xiaozhiscig.biz.id/api/audio/commands/{device_id}

Response (200 OK):
{
  "commands": [
    {
      "id": 123,
      "title": "Bohemian Rhapsody - Queen",
      "stream_url": "https://rr3---sn-a5mlrned.googlevideo.com/...",
      "video_url": "https://www.youtube.com/watch?v=...",
      "duration": "5:55"
    }
  ]
}

💡 Tips: Jika commands kosong, berarti tidak ada perintah audio baru. Lanjutkan polling.

2. Konfirmasi Audio Diputar

Setelah audio berhasil diputar, ESP32 harus mengirim konfirmasi agar tidak diputar ulang.

POST https://xiaozhiscig.biz.id/api/audio/ack/{command_id}

Request Body:
{
  "device_id": "esp32-xxx"
}

Response (200 OK):
{
  "success": true,
  "message": "Audio command acknowledged"
}

3. Registrasi Device (Opsional)

ESP32 bisa mendaftarkan diri ke server untuk monitoring.

POST https://xiaozhiscig.biz.id/api/devices/register

Request Body:
{
  "device_id": "esp32-living-room",
  "device_name": "Speaker Ruang Tamu",
  "device_type": "audio_player"
}

Response (200 OK):
{
  "success": true,
  "device": { "id": 1, "device_id": "esp32-living-room" }
}

💻 Contoh Kode Firmware ESP32

// Konfigurasi const char* SERVER_URL = "https://xiaozhiscig.biz.id"; const char* DEVICE_ID = "esp32-living-room"; const int POLL_INTERVAL = 3000; // 3 detik // Polling audio commands void pollAudioCommands() { String url = String(SERVER_URL) + "/api/audio/commands/" + DEVICE_ID; HTTPClient http; http.begin(url); int httpCode = http.GET(); if (httpCode == 200) { String payload = http.getString(); // Parse JSON dan ambil stream_url // Putar audio dari stream_url } http.end(); } // Konfirmasi audio diputar void acknowledgeAudio(int commandId) { String url = String(SERVER_URL) + "/api/audio/ack/" + String(commandId); HTTPClient http; http.begin(url); http.addHeader("Content-Type", "application/json"); http.POST("{\"device_id\": \"" + String(DEVICE_ID) + "\"}"); http.end(); }

📋 Persyaratan

Fitur YouTube Music harus diaktifkan oleh admin.
Hubungi admin jika fitur ini belum aktif di akun kamu.

💡 Tips:

Pastikan MCP dalam status Online
Pastikan ESP32 terdaftar dan terhubung ke WiFi
Pastikan speaker terhubung ke ESP32
Gunakan perintah yang jelas: "Putar lagu [judul]"
ESP32 harus support HTTPS untuk koneksi ke server

🏠 Smart Home Virtual

Smart Home Virtual adalah simulasi kontrol perangkat rumah menggunakan relay virtual. Kamu bisa mengontrol lampu, AC, alarm, dll melalui perintah suara.

📋 Daftar Ruangan

Channel	Ruangan	Perangkat	Contoh Perintah
1	Ruang Tamu	Lampu utama	"Nyalakan lampu ruang tamu"
2	Dapur	Lampu dapur	"Matikan lampu dapur"
3	Kamar Mandi	Lampu kamar mandi	"Nyalakan lampu kamar mandi"
4	Kamar Tidur Utama	Lampu kamar utama	"Matikan lampu kamar tidur"
5	Teras	Lampu teras	"Nyalakan lampu teras"
6	Basement	Alarm	"Nyalakan alarm"
7	Kamar Tidur 2	Lampu kamar kedua	"Matikan lampu kamar 2"
8	Ruang AC	AC	"Nyalakan AC"

🎤 Contoh Perintah Suara

Kontrol satu ruangan:
"Nyalakan lampu ruang tamu"
"Matikan AC"
"Hidupkan alarm"

Kontrol semua perangkat:
"Nyalakan semua lampu"
"Matikan semua perangkat"

Cek status:
"Status smarthome"
"Lampu mana yang menyala?"

🔧 Daftar 38 Tools MCP Xiaozhi

Xiaozhi terhubung dengan 38 Tools MCP berstandar ilmiah, memori semantik vektor, profil persona pengguna, dan realtime. Tools ini otomatis dipanggil oleh Xiaozhi saat mendengarkan pertanyaan atau instruksi suara kamu.

🎓 1. Pembelajaran & Akademik (Study Suite)

solve_study_problem

Menyelesaikan soal latihan/ujian secara bertahap: Identifikasi data (Diketahui/Ditanya), Teori/Rumus dasar, Langkah kalkulasi step-by-step, Jawaban akhir, dan Tips agar tidak terjebak.

🗣️ "Xiaozhi, bantu selesaikan soal bola dilempar ke atas dengan kecepatan awal 20 m/s, berapa tinggi maksimumnya?"

explain_concept

Menjelaskan konsep rumit dengan 2 tingkat penjelasan: Definisi Akademik Resmi (cocok untuk ujian/tugas) dan Analogi Sederhana Dunia Nyata (ELI5) agar langsung paham logikanya.

🗣️ "Jelaskan apa itu Polymorphism dalam pemrograman dengan analogi sederhana."

quiz_me

Membuat kuis latihan interaktif (pilihan ganda atau esai singkat) berdasarkan topik yang sedang dipelajari lengkap dengan kunci jawaban dan pembahasan.

🗣️ "Xiaozhi, uji saya dengan 3 soal kuis tentang Hukum Termodinamika."

lookup_formula

Mencari rumus cepat, unit satuan SI, dan variabel untuk Matematika, Fisika, Kimia, atau Ekonomi.

🗣️ "Apa rumus menghitung gaya gravitasi Newton?"

academic_english_helper

Membantu penulisan akademik bahasa Inggris: proofreading grammar, pemilihan kata formal untuk abstrak/skripsi, dan parafrase anti-plagiarisme.

🗣️ "Perbaiki kalimat abstrak bahasa Inggris ini agar lebih formal dan akademis."

lookup_kbbi

Mengecek ejaan baku, bentuk tidak baku, kelas kata (nomina, verba, adjektiva), dan definisi resmi bahasa Indonesia menurut KBBI.

🗣️ "Kata yang baku itu mempesona atau memukau menurut KBBI?"

search_wikipedia

Mengambil informasi ensiklopedia faktual resmi dari Wikipedia bahasa Indonesia secara ringkas dan bebas halusinasi.

🗣️ "Siapa itu Alan Turing dan apa pengaruhnya bagi dunia komputer menurut Wikipedia?"

🧠 2. Analisis Spesialis (Filsafat, Psikologi & IT)

detect_logical_fallacy

Membedah argumen, opini, atau teks debat untuk mendeteksi cacat logika (Ad Hominem, Straw Man, False Dilemma, Slippery Slope, Circular Reasoning, dll) serta teknik rekonstruksi argumen (steel-manning).

🗣️ "Bedah argumen ini apakah ada sesat pikirnya: 'Kamu masih bocah tahu apa tentang negara ini!'."

identify_cognitive_bias

Menganalisis distorsi pola pikir dan bias kognitif (Confirmation Bias, Sunk Cost Fallacy, Dunning-Kruger, Catastrophizing), dilengkapi pertanyaan sokratik refleksi dan teknik pembingkaian ulang (CBT Reframing).

🗣️ "Saya takut gagal terus sampai tidak mau mulai kerjaan baru, bias kognitif apa yang terjadi pada saya?"

it_code_and_architecture_helper

Panduan berstandar Senior Software Engineer untuk debugging kode (root cause & Big-O), GoF Design Patterns, arsitektur Clean/Microservices, optimasi database SQL/NoSQL, dan DevOps (Docker & Git CLI).

🗣️ "Kapan saya harus memakai Repository Pattern dibanding arsitektur MVC sederhana?"

🕊️ 3. Kitab Suci, Doa & Tata Cara Ibadah Lintas Agama

lookup_scripture_and_verse

Mencari nama surat, kitab suci, pasal, dan nomor ayat untuk 7 tradisi agama (Islam, Kristen, Katolik, Hindu, Buddha, Konghucu, Yahudi) lengkap dengan transliterasi fonetik latin, terjemahan Indonesia, dan hikmahnya.

🗣️ "Xiaozhi, bacakan surat Al-Ikhlas beserta arti dan transliterasinya", atau "Bacakan Mazmur 23".

get_prayer_and_worship_guide

Bimbingan doa harian dan tata cara ibadah langkah-demi-langkah (Sholat 5 waktu & wudhu, Doa Bapa Kami & Salam Maria, Liturgi Misa Katolik, Puja Tri Sandhya Hindu, Meditasi Metta Buddhis, Sembahyang Tian Konghucu, Doa Shabbat Yahudi).

🗣️ "Pandu saya tata cara Sholat Subuh lengkap dengan niat dan doanya", atau "Bagaimana lafal doa Bapa Kami?"

🌍 4. Realtime Cuaca, Gempa BMKG & Kurs

get_weather

Mengecek kondisi cuaca, suhu (°C), kelembapan, dan prakiraan cuaca realtime untuk kota/kabupaten di seluruh Indonesia.

🗣️ "Xiaozhi, bagaimana cuaca di Jakarta hari ini?"

get_earthquake_info

Mengambil data resmi BMKG Indonesia tentang gempa bumi terkini (magnitudo, kedalaman, koordinat pusat gempa, potensi tsunami, dan daftar wilayah yang merasakan).

🗣️ "Apakah ada info gempa terkini dari BMKG hari ini?"

convert_currency

Mengonversi nilai tukar mata uang global (USD, IDR, EUR, JPY, SGD, MYR, dll) menggunakan kurs pasar terbaru.

🗣️ "Berapa rupiah untuk 50 dolar Amerika saat ini?"

📚 5. Knowledge Base Pribadi

search_course_materials

Mencari materi perkuliahan, catatan tugas, atau jadwal ujian di database materi akun kamu.

read_live_api_data

Membaca data API realtime dinamis yang dikonfigurasi di dashboard.

read_material_database

Membaca daftar seluruh materi kuliah/dokumen yang tersimpan di akun.

read_material_detail

Membaca satu materi secara mendalam berdasarkan ID atau judul materi.

🏠 6. Smart Home Virtual & Relay Fisik ESP32

control_relay

Mengontrol relay virtual berdasarkan nomor channel (1-8) atau nama ruangan (Ruang Tamu, Kamar Tidur, Dapur, dll).

control_smart_home_room

Mengontrol perangkat pintar rumah virtual berdasarkan nama ruangan langsung.

get_relay_status

Membaca status semua saklar relay virtual (apakah sedang menyala atau mati).

all_relays_on / all_relays_off

Menyalakan atau mematikan seluruh perangkat virtual secara serentak.

control_real_relay_by_voice

Mengontrol modul relay fisik nyata yang terhubung ke mikrokontroler ESP32 via polling HTTP token perangkat.

get_real_relay_status

Membaca status relay fisik ESP32 secara realtime.

all_real_relays_on / off

Menyalakan atau mematikan seluruh saluran relay nyata ESP32 secara bersamaan.

🎵 7. Multimedia & Utilitas Tambahan

play_youtube_song

Mencari lagu di YouTube dan mengirim streaming audio ke speaker perangkat ESP32.

🗣️ "Xiaozhi, putar lagu Indonesia Raya di YouTube."

search_web & search_news

Mencari informasi artikel umum dan berita terkini dari media terpercaya.

calculate

Menghitung ekspresi matematika kompleks, persentase, atau konversi satuan.

translate_text

Menerjemahkan kalimat ke berbagai bahasa asing dengan tata bahasa natural.

set_reminder

Membuat pengingat alarm atau pengingat jadwal kegiatan tertentu.

save_chat_history

Menyimpan catatan riwayat percakapan penting secara otomatis ke database dan dashboard akun.

recall_chat_memory Semantic Vector AI

Mengingat kembali riwayat obrolan masa lalu (long-term memory) berbasis makna/semantik (semantic vector recall). Mampu menemukan percakapan meski menggunakan sinonim atau konsep serupa (misal: "masalah keuangan" menemukan chat tentang "biaya skripsi dan kos").

🗣️ "Xiaozhi, kemarin apa masalah keuanganku?", atau "Ingat nggak kita tadi bahas apa?"

remember_user_profile User Persona

Mencatat dan menyimpan preferensi pribadi, hobi, makanan favorit, cita-cita, nama panggilan, atau gaya bicara yang disukai pengguna ke profil jangka panjang.

🗣️ "Xiaozhi, panggil aku Kak Frank ya dan hobiku main catur", atau "Aku suka kopi susu aren"

get_user_profile Personalized

Mengambil profil dan preferensi pengguna yang tersimpan agar gaya bicara, pendekatan, dan jawaban Xiaozhi terasa sangat akrab, intim, dan personal layaknya asisten pribadi setia.

🗣️ "Xiaozhi, sesuaikan jawaban dengan gaya favoritku"

📖 Apa itu Knowledge Base?

Knowledge Base adalah database materi yang bisa dibaca oleh XiaoZhi. Kamu bisa menyimpan materi perkuliahan, tugas, catatan, jadwal, dan data API realtime. Saat kamu bertanya ke XiaoZhi, dia akan mencari jawaban dari knowledge base ini.

📋 Jenis Materi

Materi Perkuliahan

Materi kuliah, modul, atau bahan belajar. Bisa berupa teks panjang yang dipecah per topik.

Tugas Mahasiswa

Daftar tugas, deadline, dan instruksi pengerjaan.

Catatan Dosen

Catatan penting dari dosen atau pengumuman resmi.

Jadwal Kuliah

Jadwal perkuliahan, ujian, atau kegiatan akademik.

Pengumuman & Info

Pengumuman umum, informasi penting, atau berita kampus.

Data dari API (Realtime)

Data yang diambil dari API eksternal seperti cuaca, suhu, harga, dll. Data ini bersifat realtime dan selalu diperbarui.

➕ Cara Menambah Materi

Buka Dashboard

Klik menu "Dashboard" di sidebar.

Klik "Tambah Materi"

Klik tombol "+ Tambah Materi" di bagian atas.

Isi Form

Judul: Nama materi
Kategori: Pilih kategori yang sesuai
Konten: Isi materi (bisa teks panjang)
Keywords: Kata kunci untuk pencarian

Simpan

Klik tombol "Simpan". Materi akan langsung tersedia untuk dibaca oleh XiaoZhi.

🔍 Cara XiaoZhi Membaca Materi

Saat kamu bertanya ke XiaoZhi, dia akan:

Menerima pertanyaan dari kamu
Memanggil tool search_course_materials atau read_material_database
Mencari materi yang relevan di database
Membaca isi materi yang ditemukan
Menjawab pertanyaan berdasarkan isi materi

💡 Tips Menulis Materi

Agar XiaoZhi bisa menjawab dengan akurat:

Gunakan judul yang jelas dan deskriptif
Tambahkan keywords yang relevan
Gunakan format yang terstruktur (heading, list)
Pecah materi panjang menjadi beberapa bagian
Hindari singkatan yang tidak umum

❓ Pertanyaan Umum

Q: XiaoZhi tidak bisa membaca materi saya?

A: Pastikan koneksi MCP sudah Online di Dashboard. Jika belum, ulangi langkah setup MCP.

Q: Lagu YouTube tidak bisa diputar?

A: Periksa:

Fitur YouTube harus diaktifkan oleh admin
ESP32 terhubung ke WiFi
Speaker terhubung ke ESP32
MCP dalam status Online

Q: Smart home tidak merespons?

A: Pastikan:

MCP dalam status Online
Perintah suara sesuai dengan nama ruangan
Gunakan perintah yang jelas seperti "Nyalakan" atau "Matikan"

Q: Berapa banyak materi yang bisa disimpan?

A: Tergantung batas yang ditetapkan. Hubungi admin jika butuh kapasitas lebih.

Q: Bagaimana cara mengubah tema?

A: Di sidebar bawah, ada dropdown "Tema". Pilih tema yang diinginkan: Neo Brutalism, Dark, atau Original.

Q: Apakah data saya aman?

A: Ya! Semua data dienkripsi menggunakan Fernet encryption. Token MCP disimpan dalam bentuk terenkripsi di database.

Q: Bagaimana cara menghubungi admin?

A: Hubungi admin melalui kontak yang tersedia di aplikasi atau melalui kontak resmi.

Halaman Terkunci

Dokumentasi Pengguna