Tablestore mengintegrasikan protokol MCP dan menyediakan solusi penyimpanan serta pengambilan data yang efisien dengan memanfaatkan kemampuan pencarian vektor dan skalar hibrida. Berikut ini menjelaskan cara menggunakan layanan Tablestore MCP.
Pengenalan Fungsi
Layanan Tablestore MCP menyediakan dua tool:
-
Tool penyimpanan (tablestore-store): Mengonversi teks input menjadi vektor menggunakan model embedding (default: BAAI/bge-base-zh-v1.5) dan menyimpan teks asli beserta representasi vektornya ke dalam Tablestore.
-
Tool pencarian (tablestore-search): Mengonversi teks kueri menjadi vektor menggunakan model embedding, lalu mengambil hasil relevan dari indeks pencarian Tablestore melalui kueri vektor dan skalar hibrida.
Persiapan
-
Buat AccessKey untuk Akun Alibaba Cloud Anda atau Pengguna Resource Access Management (RAM) dengan izin akses Tablestore.
-
Siapkan server untuk menerapkan MCP Server. Anda dapat menggunakan Alibaba Cloud ECS.
CatatanContoh ini menggunakan instans ECS yang menjalankan Alibaba Cloud Linux 3.2104 LTS 64-bit, Python 3.13.2, dan Java 17.0.15.
Langkah Penggunaan
Langkah 1: Unduh kode sumber
-
Instal Git. Lewati langkah ini jika Git sudah terinstal.
yum -y install git -
Unduh kode sumber.
git clone https://github.com/aliyun/alibabacloud-tablestore-mcp-serverJika masalah jaringan menghalangi pengunduhan, unduh langsung tablestore-mcp-server, unggah ke server Anda, lalu ekstrak. Gunakan perintah berikut:
tar -zxvf alibabacloud-tablestore-mcp-server.tar.gz
Langkah 2: Jalankan layanan
Tablestore menyediakan layanan MCP dalam versi Python dan Java.
Python
Versi Python dari layanan Tablestore MCP memerlukan Python 3.10 atau lebih baru dan menggunakan uv untuk manajemen paket dan lingkungan.
Alibaba Cloud Linux 3.2104 LTS 64-bit secara default dilengkapi Python 3.6.8. Untuk instruksi peningkatan versi Python, lihat Peningkatan versi Python.
-
Masuk ke direktori sumber MCP.
cd alibabacloud-tablestore-mcp-server/tablestore-python-mcp-server -
Buat dan aktifkan lingkungan virtual.
python3 -m venv .venv && source .venv/bin/activate -
Instal uv.
pip3 install uv -
Tetapkan variabel lingkungan.
export HF_ENDPOINT=https://huggingface.co export TABLESTORE_ACCESS_KEY_ID=LTAI******************** export TABLESTORE_ACCESS_KEY_SECRET=****************************** export TABLESTORE_ENDPOINT=https://k01r********.cn-hangzhou.ots.aliyuncs.com export TABLESTORE_INSTANCE_NAME=k01r********Variabel lingkungan dijelaskan di bawah ini.
Nama variabel
Deskripsi
HF_ENDPOINT
Titik akhir HuggingFace.
TABLESTORE_ACCESS_KEY_ID
ID AccessKey Akun Alibaba Cloud atau Pengguna RAM Anda.
TABLESTORE_ACCESS_KEY_SECRET
Rahasia AccessKey Akun Alibaba Cloud atau Pengguna RAM Anda.
TABLESTORE_ENDPOINT
Titik akhir instans Tablestore Anda. Jika Anda menggunakan ECS, pilih titik akhir berdasarkan wilayah:
-
Jika ECS dan Tablestore berada di wilayah yang sama: gunakan alamat jaringan publik atau alamat VPC.
-
Jika ECS dan Tablestore berada di wilayah berbeda: gunakan alamat jaringan publik.
PentingInstans Tablestore yang baru dibuat tidak mengaktifkan akses jaringan publik secara default. Untuk menggunakan titik akhir publik, buka Konsol Tablestore, navigasi ke Manajemen Instans > Network Management, pilih Allowed Network Type, centang Internet, lalu klik Configure untuk menyimpan.
TABLESTORE_INSTANCE_NAME
Nama instans Tablestore Anda.
-
-
Jalankan layanan MCP.
uv run tablestore-mcp-serverJalankan pertama kali akan mengunduh dependensi. Tunggu dengan sabar. Jika pengunduhan gagal karena masalah jaringan, jalankan ulang perintah tersebut. Setelah berhasil dieksekusi, Anda akan melihat log seperti:
INFO:tablestore_mcp_server.server:mcp host:0.0.0.0, port:8001 INFO:root:run tablestore-mcp-server by: sse
Java
Menjalankan layanan Tablestore MCP memerlukan JDK 17.
-
Instal JDK.
yum -y install java-17-openjdk-devel.x86_64 -
Masuk ke direktori sumber MCP.
cd alibabacloud-tablestore-mcp-server/tablestore-java-mcp-server -
Kompilasi kode sumber.
./mvnw package -DskipTests -s settings.xmlSetelah kompilasi berhasil, Anda akan melihat log seperti:
[INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 01:58 min [INFO] Finished at: 2025-03-26T11:31:21+08:00 [INFO] ------------------------------------------------------------------------ -
Tetapkan variabel lingkungan.
export HF_ENDPOINT=http://hf-mirror.com export TABLESTORE_ACCESS_KEY_ID=LTAI******************** export TABLESTORE_ACCESS_KEY_SECRET=****************************** export TABLESTORE_ENDPOINT=https://k01r********.cn-hangzhou.ots.aliyuncs.com export TABLESTORE_INSTANCE_NAME=k01r********Variabel lingkungan dijelaskan di bawah ini.
Nama variabel
Deskripsi
HF_ENDPOINT
Titik akhir mirror HuggingFace.
TABLESTORE_ACCESS_KEY_ID
ID AccessKey Akun Alibaba Cloud atau Pengguna RAM Anda.
TABLESTORE_ACCESS_KEY_SECRET
Rahasia AccessKey Akun Alibaba Cloud atau Pengguna RAM Anda.
TABLESTORE_ENDPOINT
Titik akhir instans Tablestore Anda. Jika Anda menggunakan ECS, pilih titik akhir berdasarkan wilayah:
-
Jika ECS dan Tablestore berada di wilayah yang sama: gunakan alamat jaringan publik atau alamat VPC.
-
Jika ECS dan Tablestore berada di wilayah berbeda: gunakan alamat jaringan publik.
PentingInstans Tablestore yang baru dibuat tidak mengaktifkan akses jaringan publik secara default. Untuk menggunakan titik akhir publik, buka konsol Tablestore, navigasikan ke Instance Management > Network Management, pilih Allowed Network Type, centang Internet, lalu klik Configure untuk menyimpan.
TABLESTORE_INSTANCE_NAME
Nama instans Tablestore Anda.
-
-
Jalankan layanan MCP.
java -jar target/tablestore-java-mcp-server-1.0-SNAPSHOT.jarSetelah berhasil dieksekusi, Anda akan melihat log seperti:
2025-03-26T11:35:31.519+08:00 INFO 5116 --- [ main] o.s.b.web.embedded.netty.NettyWebServer : Netty started on port 8080 (http) 2025-03-26T11:35:31.534+08:00 INFO 5116 --- [ main] c.a.openservices.tablestore.sample.App : Started App in 44.143 seconds (process running for 44.766)
Langkah 3: Gunakan layanan MCP
-
Buka situs web Cherry Studio untuk mengunduh dan menginstal klien.
-
Klik tombol Settings di pojok kiri bawah untuk mengonfigurasi layanan model, model default, dan server MCP.
-
Layanan model: Cherry Studio mencakup beberapa penyedia model. Pilih salah satu sesuai kebutuhan Anda, dapatkan Kunci API-nya, lalu masukkan kunci tersebut di Layanan Model untuk mengelola model. Contoh ini menggunakan qwen-max dari Alibaba Cloud Model Studio. Sebelum menggunakannya, dapatkan Kunci API.
-
Model default: Tetapkan model default, atau pilih model saat percakapan.
Di bilah alat input pesan, klik ikon @ untuk membuka panel pemilihan model. Anda dapat memilih model Alibaba Cloud Model Studio seperti
qwen-vl-plus,qwen-coder-plus,qwen-turbo,qwen-plus, danqwen-max. -
Server MCP: Klik Add Server. Anda dapat menyesuaikan nama dan deskripsi. Atur Type ke SSE. Format URL adalah
http://server_ip:port/sse. Port default adalah 8001 untuk Python dan 8080 untuk Java. Saat pertama kali mengunjungi halaman pengaturan server MCP, instal UV dan Bun sesuai permintaan.PentingJika Anda menggunakan ECS, tambahkan aturan grup keamanan. Di aturan masuk, izinkan traffic TCP kustom ke port yang digunakan oleh layanan MCP.
Di bagian Request Headers, atur
Content-Type=application/jsondanAuthorization=Bearer token.
-
-
Pilih server MCP di antarmuka obrolan.
Klik ikon terminal hijau di bilah alat bawah. Panel muncul menunjukkan bahwa Tablestore berhasil terhubung. Alamat koneksi ditampilkan sebagai
http://<alamat IP>:8001/sse. Tanda centang hijau menunjukkan koneksi dalam kondisi sehat. -
Berkomunikasi dengan asisten untuk menulis dokumen ke dalam Tablestore.
Masukkan pertanyaan seperti
Apa saja metode penagihan dasar untuk Alibaba Cloud ECS? Harap buat dokumen dan tulis ke Tablestore. Balasan asisten menampilkan kartu panggilan tool tablestore-store dengan status Completed ✓, menunjukkan dokumen berhasil ditulis ke Tablestore melalui tool MCP.Anda dapat melihat log panggilan MCP di server:
INFO:mcp.server.lowlevel.server:Processing request of type CallToolRequest Batches: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 13.82it/s] INFO:tablestore_mcp_server.tablestore_connector:Storing Node ID: 2d80f2ab-9996-49d4-b23f-28b3d02b70bc Text: There are two base billing models for Alibaba Cloud ECS: Pay-As- You-Go and Subscription.Anda juga dapat melihat data yang ditulis di Konsol Tablestore.
Di tab Data Management tabel
ts_mcp_server_py_v1, Anda melihat baris yang dimasukkan berisi kolomid(kunci primer),_content,_embedding, dantitle, yang mengonfirmasi penyimpanan berhasil. -
Berkomunikasi dengan asisten untuk mengambil dokumen yang relevan dari Tablestore.
Balasan asisten menampilkan status panggilan tool tablestore-search "Completed ✓", menunjukkan layanan MCP berhasil mengambil dokumen relevan dari Tablestore dan menghasilkan respons berdasarkan dokumen tersebut.
Anda dapat melihat log panggilan MCP di server:
INFO:mcp.server.lowlevel.server:Processing request of type CallToolRequest INFO:tablestore_mcp_server.tablestore_connector:Search query: Alibaba Cloud ECS billing models, size: 5 Batches: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 14.34it/s] INFO:llama_index.vector_stores.tablestore.base:Tablestore search successfully. request_id:000639da-cc10-5075-8fac-bb0a59c4b4bd
Debugging lokal dan pengembangan kustom
Anda dapat menjalankan kode sumber MCP di IDE lokal dan melakukan debugging menggunakan tool MCP Inspector.
Langkah 1: Konfigurasi variabel lingkungan
Sebelum menjalankan kode, konfigurasikan variabel lingkungan sistem. Setelah dikonfigurasi, restart atau refresh IDE, antarmuka baris perintah, aplikasi desktop, dan layanan latar belakang Anda untuk memastikan variabel lingkungan baru berlaku.
Linux
-
Di antarmuka baris perintah, tambahkan variabel lingkungan ke file
~/.bashrc.echo "export TABLESTORE_ACCESS_KEY_ID='LTAI********************'" >> ~/.bashrc echo "export TABLESTORE_ACCESS_KEY_SECRET='******************************'" >> ~/.bashrc echo "export TABLESTORE_ENDPOINT='https://k01r********.cn-hangzhou.ots.aliyuncs.com'" >> ~/.bashrc echo "export TABLESTORE_INSTANCE_NAME='k01r********'" >> ~/.bashrc echo "export HF_ENDPOINT='http://hf-mirror.com'" >> ~/.bashrc -
Terapkan perubahan.
source ~/.bashrc -
Verifikasi variabel lingkungan.
echo $TABLESTORE_ACCESS_KEY_ID echo $TABLESTORE_ACCESS_KEY_SECRET echo $TABLESTORE_ENDPOINT echo $TABLESTORE_INSTANCE_NAME echo $HF_ENDPOINT
macOS
-
Di Terminal, periksa shell default Anda.
echo $SHELL -
Lanjutkan berdasarkan jenis shell Anda.
Zsh
-
Tambahkan variabel lingkungan ke
~/.zshrc.echo "export TABLESTORE_ACCESS_KEY_ID='LTAI********************'" >> ~/.zshrc echo "export TABLESTORE_ACCESS_KEY_SECRET='******************************'" >> ~/.zshrc echo "export TABLESTORE_ENDPOINT='https://k01r********.cn-hangzhou.ots.aliyuncs.com'" >> ~/.zshrc echo "export TABLESTORE_INSTANCE_NAME='k01r********'" >> ~/.zshrc echo "export HF_ENDPOINT='http://hf-mirror.com'" >> ~/.zshrc -
Terapkan perubahan.
source ~/.zshrc -
Verifikasi variabel lingkungan.
echo $TABLESTORE_ACCESS_KEY_ID echo $TABLESTORE_ACCESS_KEY_SECRET echo $TABLESTORE_ENDPOINT echo $TABLESTORE_INSTANCE_NAME echo $HF_ENDPOINT
Bash
-
Tambahkan variabel lingkungan ke
~/.bash_profile.echo "export TABLESTORE_ACCESS_KEY_ID='LTAI********************'" >> ~/.bash_profile echo "export TABLESTORE_ACCESS_KEY_SECRET='******************************'" >> ~/.bash_profile echo "export TABLESTORE_ENDPOINT='https://k01r********.cn-hangzhou.ots.aliyuncs.com'" >> ~/.bash_profile echo "export TABLESTORE_INSTANCE_NAME='k01r********'" >> ~/.bash_profile echo "export HF_ENDPOINT='http://hf-mirror.com'" >> ~/.bash_profile -
Terapkan perubahan.
source ~/.bash_profile -
Jalankan perintah berikut untuk memeriksa apakah variabel lingkungan telah berlaku.
echo $TABLESTORE_ACCESS_KEY_ID echo $TABLESTORE_ACCESS_KEY_SECRET echo $TABLESTORE_ENDPOINT echo $TABLESTORE_INSTANCE_NAME echo $HF_ENDPOINT
-
Windows
CMD
-
Di CMD, atur variabel lingkungan.
setx TABLESTORE_ACCESS_KEY_ID "LTAI********************" setx TABLESTORE_ACCESS_KEY_SECRET "******************************" setx TABLESTORE_ENDPOINT "https://k01r********.cn-hangzhou.ots.aliyuncs.com" setx TABLESTORE_INSTANCE_NAME "k01r********" setx HF_ENDPOINT "http://hf-mirror.com" -
Setelah merestart CMD, verifikasi variabel lingkungan.
echo %TABLESTORE_ACCESS_KEY_ID% echo %TABLESTORE_ACCESS_KEY_SECRET% echo %TABLESTORE_ENDPOINT% echo %TABLESTORE_INSTANCE_NAME% echo %HF_ENDPOINT%
PowerShell
-
Di PowerShell, jalankan:
[Environment]::SetEnvironmentVariable("TABLESTORE_ACCESS_KEY_ID", "LTAI********************", [EnvironmentVariableTarget]::User) [Environment]::SetEnvironmentVariable("TABLESTORE_ACCESS_KEY_SECRET", "******************************", [EnvironmentVariableTarget]::User) [Environment]::SetEnvironmentVariable("TABLESTORE_ENDPOINT", "https://k01r********.cn-hangzhou.ots.aliyuncs.com", [EnvironmentVariableTarget]::User) [Environment]::SetEnvironmentVariable("TABLESTORE_INSTANCE_NAME", "k01r********", [EnvironmentVariableTarget]::User) [Environment]::SetEnvironmentVariable("HF_ENDPOINT", "http://hf-mirror.com", [EnvironmentVariableTarget]::User) -
Verifikasi variabel lingkungan.
[Environment]::GetEnvironmentVariable("TABLESTORE_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User) [Environment]::GetEnvironmentVariable("TABLESTORE_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User) [Environment]::GetEnvironmentVariable("TABLESTORE_ENDPOINT", [EnvironmentVariableTarget]::User) [Environment]::GetEnvironmentVariable("TABLESTORE_INSTANCE_NAME", [EnvironmentVariableTarget]::User) [Environment]::GetEnvironmentVariable("HF_ENDPOINT", [EnvironmentVariableTarget]::User)
Langkah 2: Jalankan kode sumber
Python
Persyaratan untuk menjalankan kode sumber MCP secara lokal:
-
Python 3.10 atau lebih baru.
-
PyCharm 2024.3.2 atau lebih baru.
Setelah mengonfigurasi lingkungan, buka direktori tablestore-python-mcp-server di PyCharm dan jalankan src/tablestore_mcp_server/main.py. Setelah berhasil dieksekusi, konsol mencetak:
INFO:tablestore_mcp_server.server:mcp host:0.0.0.0, port:8001
INFO:root:run tablestore-mcp-server by: sse
Java
Persyaratan untuk menjalankan kode sumber MCP secara lokal: JDK 17.
Setelah mengonfigurasi lingkungan, buka direktori tablestore-java-mcp-server di IDEA dan jalankan src/main/java/com.alicloud.openservices.tablestore.sample/App.java. Setelah berhasil dieksekusi, konsol mencetak:
2025-03-31T16:50:50.582+08:00 INFO 27160 --- [ main] o.s.b.web.embedded.netty.NettyWebServer : Netty started on port 8080 (http)
2025-03-31T16:50:50.594+08:00 INFO 27160 --- [ main] c.a.openservices.tablestore.sample.App : Started App in 79.764 seconds (process running for 80.524)
Langkah 3: Debugging tool
-
Instal Node.js.
-
Di terminal Anda, jalankan perintah berikut. Masukkan
ysaat diminta untuk meluncurkan MCP Inspector.npx @modelcontextprotocol/inspector node build/index.jsJalankan pertama kali akan mengunduh tool. Tunggu sebentar. Setelah berhasil, terminal mencetak sesuatu seperti (port dapat berbeda):
MCP Inspector is up and running at: http://localhost:6274 -
Di browser Anda, buka alamat yang ditampilkan di terminal untuk membuka dasbor MCP Inspector. Pilih jenis transport dan masukkan URL, lalu klik Connect untuk terhubung ke layanan MCP. Klik List Tools untuk melihat tool yang tersedia.
Sebagai contoh, atur Transport Type ke SSE dan URL ke
http://localhost:8001/sse. Setelah koneksi berhasil, status berubah menjadi hijau ("Connected"). Mengklik List Tools menampilkan tool yang terdaftar: tablestore-store (menyimpan dokumen di Tablestore untuk pengambilan selanjutnya) dan tablestore-search (mencari dokumen di Tablestore yang mirip secara semantik menggunakan bahasa alami). -
Pilih tool tablestore-store. Masukkan konten di bidang information lalu klik Run Tool untuk menulis data ke Tablestore.
Anda dapat melihat log di konsol IDE atau login ke Konsol Tablestore untuk memverifikasi data.
Di tab Data Management, Anda melihat satu baris dimasukkan ke tabel
ts_mcp_server_py_v1, berisi tiga kolom: id (kunci primer), _content (teks), dan _embedding (vektor), yang mengonfirmasi penyisipan berhasil. -
Pilih tool tablestore-search. Masukkan kueri dan ukuran (jumlah hasil) di bidang query, lalu klik Run Tool untuk mencari di Tablestore.
Jika berhasil, hasilnya menampilkan dokumen yang mirip secara semantik dengan kueri Anda, termasuk teks yang cocok (_content) dan skor kemiripan (_score).
Peningkatan versi Python
Langkah-langkah berikut menunjukkan cara meningkatkan ke Python 3.13.2.
-
Unduh Python.
wget https://www.python.org/ftp/python/3.13.2/Python-3.13.2.tgzJika masalah jaringan menghalangi pengunduhan, unduh langsung Python-3.13.2 dan unggah ke server Anda.
-
Ekstrak file.
tar -zxvf Python-3.13.2.tgz -
Instal dependensi.
yum -y install zlib-devel bzip2-devel openssl-devel ncurses-devel sqlite-devel readline-devel tk-devel gdbm-devel xz-devel libffi-devel libuuid-devel libtirpc-devel libnsl2-devel -
Masuk ke direktori Python.
cd Python-3.13.2 -
Konfigurasi path instalasi.
./configure -
Kompilasi Python.
make -
Instal Python.
make install -
Periksa versi yang terinstal.
-
Periksa versi Python.
python3 --version -
Periksa versi Pip.
pip3 --version
-