MaxCompute:Layanan MaxCompute MCP

Kemampuan inti

• Penelusuran dan pencarian metadata katalog: Jelajahi proyek, skema, tabel, bidang, dan partisi secara hierarkis. Pencarian dengan bahasa alami didukung.

• Manajemen tabel dan pemeliharaan metadata: Buat tabel (dengan opsi siklus hidup, primary key, dan pembaruan kolom parsial), masukkan data dalam jumlah kecil, serta perbarui komentar tabel, tag, atau deskripsi kolom.

• Pemeriksaan identitas dan izin: Lihat identitas akun saat ini dan gunakan informasi otorisasi MaxCompute untuk menangani masalah akses.

• Otentikasi dan otorisasi:

  • MCP jarak jauh menggunakan OAuth Alibaba Cloud untuk otorisasi.

  • MCP lokal mendukung AccessKey/SecretKey (AK/SK), Security Token Service (STS), Credentials URI, Peran RAM Instans ECS, dan rantai kredensial default Alibaba Cloud.

• Pendaftaran klien sisi server (Dokumen Metadata Client ID, CIMD):

  Di lingkungan tempat fitur ini diaktifkan, klien sisi server atau self-hosted dapat menggunakan URL dokumen metadata HTTPS sebagai client_id untuk melewati Dynamic Client Registration (DCR). Namun, persetujuan eksplisit tetap diperlukan pada halaman konfirmasi otorisasi setelah login. Untuk informasi lebih lanjut, lihat Konfigurasi klien sisi server (Dokumen Metadata Client ID).

• Analisis dan eksekusi SQL:

  Mendukung validasi pernyataan, estimasi volume data yang dipindai dan penggunaan Compute Unit (CU), eksekusi kueri SQL read-only atau write, kueri status instans, dan pengambilan hasil. Kueri SQL write dan perubahan metadata memerlukan konfirmasi pengguna.

• Analis cerdas:

  Menghasilkan draf SQL read-only dari bahasa alami, mendiagnosis masalah pekerjaan, dan menganalisis penggunaan kuota komputasi. Hasilnya menunjukkan cakupan bukti dan memberikan tindakan yang direkomendasikan.

• Analis metadata tabel:

  Memeriksa struktur tabel dan metadata partisi tanpa memindai data tabel.

• Manajemen SemanticSpec:

  Buat dan kelola draf SemanticSpec yang menjelaskan semantik data, lihat versi yang dipublikasikan, dan gunakan DataScan untuk menghasilkan serta menerapkan rekomendasi berdasarkan penemuan semantik.

• Pencarian basis pengetahuan dan T&J:

  MCP jarak jauh menyertakan basis pengetahuan dokumentasi MaxCompute bawaan yang mendukung pencarian kata kunci dan T&J bahasa alami, serta mengembalikan jawaban dengan kutipan.

• Penemuan dan pembacaan Skill: MCP jarak jauh menyertakan resource MCP Skill bawaan. Klien dapat menggunakan tools/list untuk menemukan dan membaca konten Skill untuk skenario seperti analisis semantik Information Schema dan panduan umpan balik.

• Analis O&M dan tata kelola Information Schema:

  • MCP jarak jauh menyertakan paket semantik Information Schema bawaan.

  • MCP lokal memerlukan instalasi Skill terpisah.

• Informasi tool multibahasa: MCP jarak jauh menyediakan judul dan deskripsi tool dalam Bahasa Mandarin Sederhana, Bahasa Mandarin Tradisional, dan Bahasa Inggris dalam output tools/list, serta menunjukkan apakah suatu tool bergantung pada model.

Ikhtisar arsitektur

MCMCP memiliki arsitektur berlapis dengan lapisan-lapisan berikut dari atas ke bawah:

• Ekosistem agen pengguna: Mendukung koneksi dari klien MCP seperti Claude Code, Codex, Qwen Code, Cursor, dan Qoder.

• Koleksi Skill MaxCompute: Agen dapat menyelesaikan tugas yang lebih kompleks dengan menggunakan kombinasi paket semantik, perintah umum, templat pengembangan, dan batasan penggunaan.

• Layanan MCMCP: Membungkus kemampuan seperti MaxCompute OpenAPI, StorageAPI, dan CatalogAPI ke dalam tool MCP.

• Kemampuan MaxCompute dasar: Mencakup kemampuan produk seperti metadata, Mesin Komputasi, dan penyimpanan.

Informasi tampilan daftar tool

• Informasi tampilan tool multibahasa

  MCP Jarak Jauh menyediakan informasi tampilan multibahasa untuk setiap objek tool dalam respons tools/list. Klien yang mendukung ekstensi ini dapat membaca _meta["com.aliyun.maxcompute/display"] dan menampilkan judul serta deskripsi dalam Bahasa Mandarin Sederhana (zh-CN), Bahasa Mandarin Tradisional (zh-TW), atau Bahasa Inggris (en) berdasarkan bahasa antarmuka.

  Klien harus mengandalkan set tool yang dikembalikan oleh setiap panggilan tools/list dan tidak memelihara katalog tool terpisah. Jika bahasa yang dipilih tidak tersedia atau versi ekstensi tidak didukung, kembali ke field standar title, name, dan description. Untuk menunjukkan ketergantungan model, tandai tool sebagai didukung MaxAgent hanya ketika _meta["com.aliyun.maxcompute/model_backed"] bernilai true. Informasi tampilan hanya untuk presentasi UI dan tidak boleh digunakan untuk keputusan izin, penagihan, atau keamanan.

• Kemampuan Analisis Cerdas

  SQL bahasa alami, diagnosis pekerjaan, dan analis kuota adalah tiga tool analis cerdas MCP Jarak Jauh. Semuanya bersifat read-only. Tool tidak secara otomatis mengeksekusi SQL yang dihasilkan, menjalankan ulang atau membatalkan pekerjaan, atau memodifikasi kapasitas kuota dan konfigurasi penjadwalan.

  Analis model dapat mengonsumsi MaxAgent Credits, dan satu panggilan tool dapat memicu beberapa panggilan model. Saat kemampuan model atau bukti yang diperlukan tidak tersedia, tool dapat mengembalikan hasil partial. Gunakan field warnings dan missing_evidence untuk menilai kesimpulan mana yang dapat Anda percayai.

Prasyarat untuk analisis cerdas

• Klien MCP terhubung ke MCP Jarak Jauh melalui OAuth berbasis browser atau peluncur lokal.

• Identitas terautentikasi saat ini memiliki izin yang diperlukan untuk proyek, pekerjaan, atau kuota MaxCompute target.

• Wilayah dalam permintaan sesuai dengan wilayah tempat sumber daya target berada.

• Saat menggunakan kemampuan model MaxAgent, identitas saat ini memiliki kuota MaxAgent yang valid dan MaxAgent Credits yang cukup di wilayah yang dipilih.

• Untuk mengkueri metadata penyewa atau pekerjaan historis menggunakan tool Generate SQL, identitas saat ini harus memenuhi persyaratan Information Schema.

• Jika Anda memerlukan data pemanfaatan kapasitas kuota historis atau data konsumsi pekerjaan, kemampuan observasi historis yang sesuai harus tersedia di wilayah layanan target.

Umumnya, Anda hanya perlu menyatakan tujuan Anda dalam percakapan, dan Agent memilih tool serta mengisi parameternya. Anda juga dapat memanggil tool MCP secara langsung menggunakan contoh JSON dalam topik ini.

Hasil analis cerdas

Ketiga tool mengembalikan hasil MCP terstruktur. Perhatikan baik-baik field berikut:

• ok: Menunjukkan apakah protokol panggilan tool selesai berhasil. ok=true tidak menjamin bahwa buktinya lengkap.

• data: Berisi data bisnis, seperti draf SQL, hasil diagnostik, atau observasi kuota.

• meta.outcome atau metadata.outcome: Status hasil bisnis.

• warnings: Menggambarkan batasan, degradasi, atau perilaku fallback non-fatal.

• missing_evidence: Mencantumkan bukti apa saja yang tidak dapat diperoleh dan alasannya.

• usage: Menunjukkan jumlah panggilan model dan penggunaan token yang dilaporkan oleh model.

Nilai outcome umum:

Jangan perlakukan hasil partial sebagai panggilan API yang gagal. Gunakan field missing_evidence untuk menentukan pertanyaan apa yang dapat dijawab oleh kesimpulan saat ini dan apakah Anda perlu melengkapi izin, cakupan, atau melakukan diagnosis lebih dalam. Saat troubleshooting, jangan salin informasi autentikasi atau respons backend lengkap.

Generate SQL

Di sales_dw.dwd di wilayah China (Shanghai), hasilkan kueri SQL untuk menghitung jumlah pesanan berbayar dan total jumlah pembayaran untuk setiap saluran selama 30 hari terakhir, diurutkan berdasarkan jumlah pembayaran secara menurun. Hanya hasilkan dan validasi SQL, jangan eksekusi dulu.

{
  "question": "Hitung jumlah pesanan berbayar dan total jumlah pembayaran untuk setiap saluran selama 30 hari terakhir, diurutkan berdasarkan jumlah pembayaran secara menurun",
  "region": "cn-shanghai",
  "sources": [
    {
      "project": "sales_dw",
      "schema": "dwd"
    }
  ],
  "analysis_context": {
    "project": "sales_dw",
    "schema": "dwd"
  }
}

{
  "question": "Temukan tim dengan poin tertinggi di setiap balapan dan hitung poin musim kumulatif mereka",
  "region": "cn-shanghai",
  "sources": [
    {
      "project": "analytics",
      "schema": "formula_1",
      "tables": ["constructors", "constructorresults", "races"]
    }
  ]
}

{
  "question": "Kueri 20 pekerjaan dengan konsumsi CU tertinggi dalam 7 hari terakhir. Kembalikan ID instans, proyek, pengirim, dan jam CU",
  "region": "cn-shanghai",
  "analysis_context": {
    "project": "<Proyek tempat identitas saat ini dapat membuat instans kueri di wilayah ini>"
  }
}

Diagnosis pekerjaan

{
  "instance_id": "<INSTANCE_ID>",
  "project": "sales_dw",
  "region": "cn-shanghai",
  "depth": "standard"
}

Diagnosis pekerjaan <INSTANCE_ID> di sales_dw. Pertama, identifikasi tahap yang gagal dan penyebab paling mungkin. 
Berikan rekomendasi yang dapat ditindaklanjuti untuk perbaikan. Jangan jalankan ulang atau batalkan pekerjaan.

Lakukan penyelidikan mendalam pada pekerjaan ini. Analisis awal tidak menjelaskan akar penyebabnya. 
Periksa log yang tersedia dari pekerja yang gagal dan bukti tahap. 
Beda kan antara fakta yang dikonfirmasi, inferensi, dan bukti yang hilang.

Analisis kuota

{
  "region": "cn-shanghai",
  "quota_nickname": "team_etl_quota",
  "question": "Analisis 10 pekerjaan dengan penggunaan CPU tertinggi dalam 7 hari terakhir dan jelaskan sinyal abnormal yang dapat diverifikasi"
}

Analisis team_etl_quota di cn-shanghai. Temukan pekerjaan dengan konsumsi CPU tertinggi dalam 7 hari terakhir. Anggap pekerjaan sebagai abnormal hanya jika ada sinyal abnormal langsung untuk pekerjaan tersebut. Jika tidak, nyatakan bahwa penyebabnya tidak diketahui. Berikan hanya rekomendasi. Jangan modifikasi kuota atau pekerjaan.

{
  "region": "cn-shanghai",
  "question": "Bandingkan kuota komputasi dengan pekerjaan aktif dalam 7 hari terakhir, diurutkan berdasarkan penggunaan CPU pekerjaan. Cantumkan pemanfaatan kapasitas secara terpisah untuk kuota Langganan, tetapi jangan hitung persentase kapasitas untuk kuota Bayar-Sesuai-Pemakaian dan Spot"
}

Bandingkan kuota komputasi saya di cn-shanghai yang memiliki pekerjaan aktif dalam 7 hari terakhir, termasuk Langganan, Bayar-Sesuai-Pemakaian, dan Spot.
Urutkan berdasarkan penggunaan CPU pekerjaan dan cantumkan pekerjaan konsumsi tinggi. Tambahkan pemanfaatan kapasitas hanya untuk kuota Langganan.

Persyaratan Information Schema

Generate SQL dapat menggunakan tampilan Information Schema tingkat penyewa. Analis kuota untuk pemanfaatan kapasitas dan bukti pekerjaan tidak menggunakan Information Schema. Generate SQL hanya mengizinkan tampilan yang ada dalam daftar putih sisi server, seperti:

• SYSTEM_CATALOG.INFORMATION_SCHEMA.TASKS

• SYSTEM_CATALOG.INFORMATION_SCHEMA.TASKS_HISTORY

Saat Generate SQL menggunakan tampilan ini, harus memenuhi kondisi berikut:

1. Identitas terautentikasi saat ini harus memiliki izin baca untuk Information Schema tingkat penyewa. Akun root biasanya memiliki akses ini secara default. Akses untuk pengguna RAM atau peran RAM tergantung pada konfigurasi yang ditetapkan oleh administrator penyewa.

2. Identitas saat ini harus memiliki setidaknya satu proyek MaxCompute yang terlihat di wilayah target. Proyek ini digunakan untuk mengirim kueri SQL Information Schema read-only. Identitas juga harus memiliki izin yang diperlukan untuk membuat instans kueri.

3. Wilayah target harus menyediakan tampilan tingkat penyewa yang disebutkan di atas dan dependensi backend-nya.

Batasan keamanan dan cakupan:

• Generate SQL membaca tampilan tingkat penyewa yang dicatat oleh Skill bawaan, tetapi tidak dapat mengkueri tampilan sistem yang tidak dikenal atau mencampur kueri dengan tabel fisik.

• Sebelum model memilih tampilan sistem, Generate SQL memuat Skill root Information Schema. Tool menggunakan granularitas data, ketepatan waktu, dan kolom tampilan untuk menentukan sumber fakta yang diperlukan. Setelah tampilan dipilih, Generate SQL memuat dokumentasi kolom lengkap untuk tampilan tersebut.

• Draf tampilan sistem untuk Generate SQL harus mencakup rentang waktu dan klausa LIMIT.

• Kueri selalu read-only. Tidak memodifikasi kuota, konfigurasi penjadwalan, atau pekerjaan.

Kasus penggunaan untuk tool analis cerdas

1. Gunakan maxcompute_generate_sql untuk menghasilkan dan memvalidasi SQL untuk pendapatan saluran selama 30 hari terakhir.
2. Setelah meninjau dan mengonfirmasi SQL, gunakan maxcompute_sql_execute untuk menjalankan execute_args.
3. Jika pekerjaan gagal atau melambat secara signifikan, gunakan maxcompute_diagnose_job untuk menganalisis instans.

1. Hilangkan quota_nickname dan gunakan maxcompute_analyze_quota_usage untuk menemukan kuota komputasi yang memiliki pekerjaan dalam 7 hari terakhir.
2. Temukan pekerjaan konsumsi tinggi berdasarkan konsumsi pekerjaan aktual. Periksa pemanfaatan kapasitas hanya untuk kuota Langganan.
3. Panggil maxcompute_diagnose_job untuk instans dengan sinyal abnormal.
4. Optimalkan SQL atau penjadwalan berdasarkan bukti pekerjaan. Jangan secara otomatis meningkatkan berdasarkan hanya konsumsi historis.

Analisis distribusi pemilik dan konsumsi CPU pekerjaan yang gagal untuk team_etl_quota selama 7 hari terakhir.
Selidiki penyebab untuk instans yang gagal dengan konsumsi CPU tertinggi.

Rekomendasi untuk menggunakan tool analis cerdas

• Berikan hanya field cakupan yang didukung oleh tool saat ini. Untuk generasi SQL, gunakan region, sources, dan analysis_context opsional. Untuk diagnosis pekerjaan, gunakan proyek dan ID Instans atau URL Logview. Untuk analis kuota, gunakan region dan nama panggilan kuota yang tepat. Jangan sertakan field konteks dari tool lain dalam panggilan saat ini.

• Untuk menghasilkan SQL untuk cakupan data yang diketahui, berikan sources. Ini menghindari proses penemuan luas yang mungkin menghasilkan nol kandidat atau beberapa dataset ambigu.

• Untuk diagnosis pekerjaan, gunakan standard terlebih dahulu. Gunakan deep hanya saat hasil tidak meyakinkan atau saat diperlukan investigasi lebih lanjut.

• Untuk analis kuota, pertama bandingkan data konsumsi pekerjaan yang dikembalikan. Kemudian, selidiki beberapa kuota dan instans permintaan tinggi secara detail. Jangan perlakukan hasil parsial sebagai daftar lengkap.

• Selalu bedakan antara fakta yang dikonfirmasi, penilaian model, dan missing_evidence.

• Pengguna harus mengonfirmasi secara terpisah operasi penskalaan, penjadwalan, migrasi, eksekusi SQL, pengulangan, atau pembatalan.

Aturan pemanggilan umum

• Tool hanya dapat mengakses sumber daya MaxCompute yang diizinkan untuk diakses oleh identitas saat ini. Jangan samakan visibilitas tool dengan otorisasi sumber daya.

• Setelah menemukan tabel kandidat, baca struktur tabel yang akurat sebelum menghasilkan atau mengeksekusi SQL. Jangan menebak kolom, partisi, atau skema berdasarkan nama tabel.

• Klien harus mendapatkan konfirmasi eksplisit pengguna sebelum melakukan operasi write. Operasi ini termasuk menulis SQL, membuat tabel, memasukkan data, memperbarui metadata, dan memodifikasi SemanticSpec. Gerbang tidak melakukan konfirmasi sekunder interaktif untuk klien.

• Untuk set hasil besar, gunakan pagination, persempit cakupan kueri, atau baca dari instans asinkron. MCP Lokal juga dapat menulis ke file menggunakan file://output_uri lokal. Path ini mengacu pada mesin tempat MCP Lokal berjalan, bukan mesin klien MCP.

• execution_mode untuk maxcompute_sql_execute default ke wlm. Saat menggunakan MaxQA (MCQA v2), teruskan secara eksplisit execution_mode=maxqa dan quota_name interaktif. Jangan teruskan settings.odps.task.wlm.quota secara bersamaan. Untuk panggilan status, hasil, atau pembatalan selanjutnya, teruskan hanya project dan instance_id. Jangan teruskan atau simpan koneksi atau cookie MaxQA sisi server.

Klien MCP tidak dapat menemukan tool

• Untuk koneksi langsung OAuth berbasis browser, pastikan endpoint layanan MCP Jarak Jauh mencakup /mcp dan konfigurasi klien yang sama tidak mencampur endpoint jaringan publik dan VPC.

• Pastikan klien yang digunakan untuk koneksi langsung OAuth berbasis browser mendukung Streamable HTTP, OAuth, dan tools/list.

• Apakah command peluncur lokal mengarah ke alibabacloud-maxcompute-mcp-server yang diinstal, dan apakah alibabacloud-maxcompute-mcp-server --help berjalan berhasil di lingkungan runtime yang sama.

• Apakah MAXCOMPUTE_CATALOG_CONFIG mengarah ke file konfigurasi yang dapat dibaca, atau MAXCOMPUTE_REGION dan MAXCOMPUTE_NETWORK keduanya diatur.

• Periksa apakah default memilih local karena MCP Jarak Jauh tidak tersedia. Jika dependensi lokal hilang, instal alibabacloud-maxcompute-mcp-server[local] seperti yang diminta oleh pesan error.

• Periksa apakah daftar tool yang tersedia mencakup tool target. MCP Jarak Jauh menggunakan nama tool maxcompute_*, sedangkan mode local menggunakan nama tool SDK asli. Keduanya tidak dapat dipertukarkan secara langsung.

• Setelah memodifikasi konfigurasi, restart Cursor, Claude Code, atau klien MCP yang sesuai.

Kegagalan autentikasi, koneksi, atau izin

• Untuk koneksi langsung OAuth berbasis browser, verifikasi bahwa pengguna telah menyelesaikan otorisasi OAuth Alibaba Cloud. Jika halaman OAuth tidak terbuka, periksa apakah klien mendukung OAuth MCP dan apakah browser lokal atau port callback diblokir.

• Jika Anda menerima error 401 dengan koneksi langsung OAuth berbasis browser, otorisasi ulang dan verifikasi bahwa token akses yang disimpan klien valid.

• Verifikasi bahwa peluncur lokal telah memperoleh AccessKey yang valid, kredensial sementara STS, URI kredensial, atau kredensial dari rantai kredensial default. Pastikan token keamanan STS belum kedaluwarsa. Peluncur lokal tidak memerlukan OAuth berbasis browser.

• Verifikasi bahwa region dan network konsisten dengan lingkungan MaxCompute target dan alamat layanan FE dan CatalogAPI dalam konfigurasi asli mengarah ke wilayah dan jenis jaringan yang sama.

• Verifikasi bahwa lingkungan VPC Anda dapat mengakses endpoint CatalogAPI VPC dan endpoint MCP VPC di wilayah yang sama. Konfigurasi VPC tidak dapat digunakan untuk terhubung ke endpoint MCP jaringan publik.

• Mode remote mengembalikan error saat MCP Jarak Jauh tidak tersedia. Mode default mencoba menggunakan tool SDK lokal.

• Jika terjadi error 403, pastikan akun Alibaba Cloud saat ini memiliki izin MaxCompute dan RAM untuk proyek target.

• Verifikasi bahwa ID wilayah target dalam percakapan atau parameter tool benar. Jika tidak ditentukan secara eksplisit, layanan menggunakan wilayah default titik masuk saat ini.

• Saat menggunakan URI kredensial, pastikan mesin yang menjalankan peluncur dapat mengakses ALIBABA_CLOUD_CREDENTIALS_URI.

• Gunakan maxcompute_access_check MCP Jarak Jauh atau check_access mode local untuk memverifikasi identitas Anda saat ini sebelum melakukan troubleshooting tool spesifik.

Kegagalan pencarian metadata

maxcompute_schema_search_metadata untuk MCP Jarak Jauh dan search_meta_data untuk mode local menggunakan sintaks kueri Catalog yang sama. Penyebab umum error meliputi:

• Anda menggunakan search_meta_data dalam mode local, tetapi namespaceId atau MAXCOMPUTE_NAMESPACE_ID tidak dikonfigurasi. MCP Jarak Jauh tidak memerlukan konfigurasi ini.

• Pernyataan kueri tidak memiliki type=TABLE, type=RESOURCE, atau type=SCHEMA.

• Menggunakan kondisi proyek dan wilayah yang tidak kompatibel dalam kueri yang sama.

Kegagalan parsing, eksekusi, atau pengambilan hasil SQL

Jika resolusi nama tabel SQL gagal, pertama gunakan maxcompute_schema_describe_table MCP Jarak Jauh atau get_table_schema MCP Lokal untuk membaca skema tabel, sehingga agen dapat menggunakan referensi tabel akurat yang dikembalikan. Format nama tabel umum adalah schema.table atau project.schema.table untuk model 3-layer, dan table atau project.table untuk model 2-layer.

Jika MCP Jarak Jauh menolak pernyataan SQL sebagai operasi write, konfirmasi bahwa pengguna bermaksud melakukan write, dan gunakan secara eksplisit mode=write setelah menerima konfirmasi. Jangan modifikasi mode untuk melewati pemeriksaan read-only.

Jika eksekusi SQL timeout atau hasilnya terpotong:

• Utamakan eksekusi asinkron.

  • MCP Jarak Jauh menggunakan maxcompute_sql_get_status dan maxcompute_sql_fetch_result untuk melanjutkan kueri.

  • MCP Lokal melakukan kueri lanjutan menggunakan get_instance_status dan get_instance.

• MCP Jarak Jauh menggunakan limit dan cursor untuk membagi halaman dan mempersempit cakupan kueri. MCP Lokal juga dapat menggunakan output_uri=file:///path/to/result.jsonl untuk menulis ke mesin tempat MCP Lokal berjalan.

• Sebelum menjalankan operasi, panggil tool estimasi penggunaan sumber daya yang sesuai dan batasi konsumsi sumber daya berdasarkan definisi parameter dalam tools/list.