Tablestore mengintegrasikan protokol MCP untuk menyediakan penyimpanan dan pengambilan data yang efisien melalui kemampuan hibrida vektor dan skalar. Topik ini menjelaskan cara menggunakan layanan Tablestore MCP.
Latar Belakang
Layanan Tablestore MCP menyediakan dua tool berikut:
Storage tool (tablestore-store): Data dikonversi menjadi vektor melalui model embedding (default: BAAI/bge-base-zh-v1.5) dan ditulis ke Tablestore bersama teks aslinya.
Retrieval tool (tablestore-search): Teks kueri pengguna dikonversi menjadi vektor melalui model embedding, lalu indeks pencarian Tablestore dicari (menggunakan vektor dan skalar untuk kueri hibrida) guna mengambil hasil yang diharapkan pengguna.
Persiapan
Buat AccessKey untuk akun Alibaba Cloud Anda atau Pengguna Resource Access Management (RAM) yang memiliki izin akses ke Tablestore.
Persiapkan server untuk menerapkan server MCP. Anda dapat menggunakan Alibaba Cloud ECS.
CatatanTopik ini menggunakan server ECS dengan sistem operasi Alibaba Cloud Linux 3.2104 LTS 64-bit, Python 3.13.2, dan Java 17.0.15.
Prosedur
Langkah 1: Unduh kode sumber
Instal Git. Lewati langkah ini jika Git sudah terinstal di server Anda.
yum -y install gitUnduh kode sumber.
git clone https://github.com/aliyun/alibabacloud-tablestore-mcp-serverJika Anda tidak dapat mengunduh karena masalah jaringan, unduh langsung tablestore-mcp-server, unggah ke server Anda, lalu ekstrak. Jalankan perintah berikut untuk mengekstrak:
tar -zxvf alibabacloud-tablestore-mcp-server.tar.gz
Langkah 2: Jalankan layanan
Tablestore menyediakan versi Python dan Java dari layanan MCP.
Python
Versi Python dari layanan Tablestore MCP memerlukan Python 3.10 atau lebih baru, dan menggunakan uv untuk manajemen paket dan lingkungan.
Versi Python 3 default pada sistem Alibaba Cloud Linux 3.2104 LTS 64-bit adalah 3.6.8. Untuk petunjuk peningkatan versi Python, lihat Peningkatan versi Python.
Buka direktori kode sumber MCP.
cd alibabacloud-tablestore-mcp-server/tablestore-python-mcp-serverBuat dan aktifkan lingkungan virtual.
python3 -m venv .venv && source .venv/bin/activateInstal uv.
pip3 install uvKonfigurasikan 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 tersebut dijelaskan sebagai berikut.
Nama variabel
Deskripsi
HF_ENDPOINT
Alamat 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. Jika Anda menggunakan ECS, pilih titik akhir berdasarkan wilayah:
Jika ECS dan Tablestore berada di wilayah yang sama: Pilih titik akhir publik atau titik akhir VPC.
Jika ECS dan Tablestore tidak berada di wilayah yang sama: Pilih titik akhir publik.
PentingInstans Tablestore yang baru dibuat tidak memiliki akses publik yang diaktifkan secara default. Untuk menggunakan titik akhir publik, buka Konsol Tablestore, masuk ke tab Network Management pada halaman Instance Management, pilih Internet untuk Allowed Network Type, lalu klik Settings untuk menyimpan konfigurasi.
TABLESTORE_INSTANCE_NAME
Nama instans Tablestore.
Jalankan layanan MCP.
uv run tablestore-mcp-serverJalankan pertama kali memerlukan pengunduhan dependensi. Harap bersabar. Jika pengunduhan terganggu karena masalah jaringan, cukup jalankan perintah lagi. Saat layanan berhasil berjalan, log berikut akan dicetak.
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 JDK17.
Instal JDK.
yum -y install java-17-openjdk-devel.x86_64Buka direktori kode sumber MCP.
cd alibabacloud-tablestore-mcp-server/tablestore-java-mcp-serverKompilasi kode sumber.
./mvnw package -DskipTests -s settings.xmlSaat kompilasi berhasil, log berikut akan dicetak.
[INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 01:58 min [INFO] Finished at: 2025-03-26T11:31:21+08:00 [INFO] ------------------------------------------------------------------------Konfigurasikan 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 tersebut dijelaskan sebagai berikut.
Nama variabel
Deskripsi
HF_ENDPOINT
Alamat 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. Jika Anda menggunakan ECS, pilih titik akhir berdasarkan wilayah:
Jika ECS dan Tablestore berada di wilayah yang sama: Pilih titik akhir publik atau titik akhir VPC.
Jika ECS dan Tablestore tidak berada di wilayah yang sama: Pilih titik akhir publik.
PentingInstans Tablestore yang baru dibuat tidak mengaktifkan akses publik secara default. Untuk menggunakan titik akhir publik, buka Konsol Tablestore, pilih Instance Management, masuk ke tab Network Management, pilih Allowed Network Types, centang Public, lalu klik Set untuk menyimpan konfigurasi.
TABLESTORE_INSTANCE_NAME
Nama instans Tablestore.
Jalankan layanan MCP.
java -jar target/tablestore-java-mcp-server-1.0-SNAPSHOT.jarSaat layanan berhasil berjalan, log berikut akan dicetak.
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 pengaturan di pojok kiri bawah untuk mengonfigurasi layanan model, model default, dan server MCP.
Model Service: Cherry Studio memiliki banyak penyedia layanan model bawaan. Pilih penyedia layanan model sesuai kebutuhan, dapatkan Kunci API penyedia tersebut, lalu isi kunci tersebut di layanan model untuk mengelola model. Topik ini menggunakan model qwen-max dari Alibaba Cloud Model Studio, yang mengharuskan Anda mendapatkan Kunci API sebelum digunakan.
Default Model: Tetapkan model default. Anda juga dapat memilih model di halaman percakapan.

MCP Server: Tambahkan server. Nama dan deskripsi dapat dikustomisasi. Pilih SSE untuk tipe. Format URL adalah
http://server_ip:port/sse. Port default untuk Python adalah 8001, dan port default untuk Java adalah 8080. Saat pertama kali masuk ke halaman pengaturan server MCP, Anda perlu menginstal UV dan Bun sesuai permintaan.PentingJika Anda menggunakan ECS, tambahkan aturan grup keamanan untuk mengizinkan akses ke port TCP kustom dalam aturan inbound. Port tujuan harus merupakan port tempat layanan MCP berjalan.

Pilih server MCP di halaman percakapan.

Berinteraksi dengan asisten untuk menulis dokumen ke Tablestore.

Lihat 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.

Berinteraksi dengan asisten untuk mengambil dokumen relevan dari Tablestore.

Lihat 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
Jalankan kode sumber MCP secara lokal di IDE Anda dan gunakan tool MCP Inspector untuk debugging.
Langkah 1: Konfigurasikan variabel lingkungan
Sebelum menjalankan kode, Anda perlu mengonfigurasi variabel lingkungan sistem. Setelah dikonfigurasi, restart atau refresh lingkungan kompilasi dan runtime Anda, termasuk IDE, antarmuka baris perintah, aplikasi desktop lainnya, dan layanan latar belakang untuk memastikan variabel lingkungan sistem terbaru berhasil dimuat.
Linux
Jalankan perintah berikut di antarmuka baris perintah untuk menambahkan pengaturan 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'" >> ~/.bashrcJalankan perintah berikut untuk menerapkan perubahan:
source ~/.bashrcJalankan 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
macOS
Jalankan perintah berikut di terminal untuk memeriksa jenis Shell default.
echo $SHELLLakukan operasi berdasarkan jenis Shell default.
Zsh
Jalankan perintah berikut untuk menambahkan pengaturan variabel lingkungan ke file
~/.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'" >> ~/.zshrcJalankan perintah berikut untuk menerapkan perubahan:
source ~/.zshrcJalankan 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
Bash
Jalankan perintah berikut untuk menambahkan pengaturan variabel lingkungan ke file
~/.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_profileJalankan perintah berikut untuk menerapkan perubahan:
source ~/.bash_profileJalankan 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
Jalankan perintah berikut di CMD untuk mengatur 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, 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%
PowerShell
Jalankan perintah berikut di PowerShell:
[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)Jalankan perintah berikut untuk memeriksa apakah variabel lingkungan telah berlaku:
[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 lingkungan untuk menjalankan kode sumber MCP secara lokal adalah:
Python 3.10 atau lebih baru.
PyCharm 2024.3.2 atau lebih baru.
Konfigurasikan lingkungan uv di PyCharm.
Setelah menyelesaikan konfigurasi lingkungan, buka direktori kode sumber MCP tablestore-python-mcp-server di PyCharm dan jalankan file src/tablestore_mcp_server/main.py. Saat layanan berhasil berjalan, konsol akan mencetak log berikut.
INFO:tablestore_mcp_server.server:mcp host:0.0.0.0, port:8001
INFO:root:run tablestore-mcp-server by: sseJava
Persyaratan lingkungan untuk menjalankan kode sumber MCP secara lokal adalah: JDK17.
Setelah menyelesaikan konfigurasi lingkungan, buka direktori kode sumber MCP tablestore-java-mcp-server di IDEA dan jalankan file src/main/java/com.alicloud.openservices.tablestore.sample/App.java. Saat layanan berhasil berjalan, konsol akan mencetak log berikut.
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.
Jalankan perintah berikut di tool terminal, masukkan
ysaat diminta, lalu jalankan MCP Inspector.npx @modelcontextprotocol/inspector node build/index.jsJalankan pertama kali memerlukan pengunduhan tool. Tunggu sebentar. Saat layanan berhasil berjalan, terminal akan mencetak konten berikut. Port tergantung pada situasi aktual.
MCP Inspector is up and running at: http://localhost:6274Akses URL yang dikeluarkan terminal di browser Anda untuk masuk ke halaman manajemen MCP Inspector. Lalu pilih tipe transmisi sesuai situasi lokal Anda, isi URL, dan klik Connect untuk menghubungkan ke layanan MCP. Klik List Tools untuk melihat tool yang tersedia untuk debugging.

Pilih tool tablestore-store, masukkan konten di information, lalu klik Run Tool untuk menulis data ke Tablestore.

Lihat log di konsol IDE atau login ke Konsol Tablestore untuk melihat data.

Pilih tool tablestore-search, masukkan konten kueri dan ukuran (jumlah entri data yang akan dikembalikan) di query, lalu klik Run Tool untuk mengkueri data di Tablestore.

Peningkatan versi Python
Bagian ini menjelaskan cara meningkatkan versi Python menggunakan contoh Python 3.13.2.
Unduh Python.
wget https://www.python.org/ftp/python/3.13.2/Python-3.13.2.tgzJika Anda tidak dapat mengunduh karena masalah jaringan, unduh langsung Python-3.13.2 dan unggah ke server Anda.
Ekstrak paket.
tar -zxvf Python-3.13.2.tgzInstal 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-develBuka direktori Python.
cd Python-3.13.2Konfigurasikan path instalasi.
./configureKompilasi Python.
makeInstal Python.
make installPeriksa versi yang terinstal.
Periksa versi Python.
python3 --versionPeriksa versi Pip.
pip3 --version