Alat bahasa manipulasi data (DML) di SQL MCP Server

Penting

Server Protokol Konteks Model SQL (MCP) sedang dalam pratinjau, dan dokumentasi ini serta implementasi mesin dapat berubah. Saat Data API Builder versi 1.7 dalam pratinjau, Anda harus menggunakan versi prarilis secara eksplisit (misalnya, 1.7.83-rc) karena fitur MCP belum disertakan dalam tag :latest.

SQL MCP Server memaparkan enam alat Data Manipulation Language (DML) ke agen AI. Alat-alat ini menyediakan permukaan CRUD yang diketik untuk operasi database—membuat, membaca, memperbarui, dan menghapus rekaman ditambah menjalankan prosedur tersimpan. Semua alat menghormati kontrol akses berbasis peran (RBAC), izin entitas, dan kebijakan yang ditentukan dalam konfigurasi Anda.

Apa itu alat DML?

Alat DML (Bahasa Manipulasi Data) menangani operasi data: membuat, membaca, memperbarui, dan menghapus rekaman, ditambah menjalankan prosedur tersimpan. Tidak seperti DDL (Bahasa Definisi Data) yang memodifikasi skema, DML bekerja secara eksklusif pada bidang data dalam tabel dan tampilan yang ada.

Enam alat DML tersebut adalah:

• describe_entities - Menemukan entitas dan operasi yang tersedia
• create_record - Menyisipkan baris baru
• read_records - Kueri tabel dan tampilan
• update_record - Memodifikasi baris yang ada
• delete_record - Menghapus baris
• execute_entity - Menjalankan prosedur tersimpan

Ketika alat DML diaktifkan secara global dan untuk entitas, SQL MCP Server mengeksposnya melalui protokol MCP. Agen tidak pernah berinteraksi langsung dengan skema database Anda - mereka bekerja melalui lapisan abstraksi penyusun API Data.

Alat-alat

list_tools respons

Saat agen memanggil list_tools, SQL MCP Server mengembalikan:

{
  "tools": [
    { "name": "describe_entities" },
    { "name": "create_record" },
    { "name": "read_records" },
    { "name": "update_record" },
    { "name": "delete_record" },
    { "name": "execute_entity" }
  ]
}

jelaskan_entitas

Mengembalikan entitas yang tersedia untuk peran saat ini. Setiap entri mencakup nama bidang, jenis data, kunci primer, dan operasi yang diizinkan. Alat ini tidak mengkueri database. Sebaliknya, ia membaca dari konfigurasi di dalam memori yang dibangun dari file konfigurasi Anda.

{
  "entities": [
    {
      "name": "Products",
      "description": "Product catalog with pricing and inventory",
      "fields": [
        {
          "name": "ProductId",
          "type": "int",
          "isKey": true,
          "description": "Unique product identifier"
        },
        {
          "name": "ProductName",
          "type": "string",
          "description": "Display name of the product"
        },
        {
          "name": "Price",
          "type": "decimal",
          "description": "Retail price in USD"
        }
      ],
      "operations": [
        "read_records",
        "update_record"
      ]
    }
  ]
}

Nota

Opsi entitas yang digunakan oleh salah satu ALAT CRUD dan menjalankan DML berasal langsung dari describe_entities. Deskripsi semantik internal yang dilampirkan ke setiap alat memberlakukan alur dua langkah ini.

buat_rekam

Membuat baris baru dalam tabel. Memerlukan izin buat pada entitas untuk peran saat ini. Alat ini memvalidasi input terhadap skema entitas, memberlakukan izin tingkat bidang, menerapkan kebijakan pembuatan, dan mengembalikan rekaman yang dibuat dengan nilai yang dihasilkan.

read_records

Melakukan kueri pada tabel atau tampilan. Mendukung pemfilteran, pengurutan, penomoran halaman, dan pemilihan bidang. Alat ini membangun SQL deterministik dari parameter terstruktur, menerapkan izin baca dan proyeksi lapangan, dan memberlakukan kebijakan keamanan tingkat baris.

Hasil dari read_records secara otomatis dicache menggunakan sistem caching Data API builder. Anda dapat mengonfigurasi cache time-to-live (TTL) secara global atau per entitas untuk mengurangi beban database.

perbarui_catatan

Memodifikasi baris yang sudah ada. Memerlukan kunci utama dan bidang yang akan diperbarui. Alat ini memvalidasi kunci utama yang sudah ada, menegakkan izin dan kebijakan pembaruan, dan hanya memperbarui bidang yang dapat diubah oleh peran pengguna saat ini.

delete_record

Menghapus baris yang sudah ada. Memerlukan kunci primer. Alat ini memvalidasi kunci utama yang ada, memberlakukan izin dan kebijakan penghapusan, dan melakukan penghapusan yang aman dengan dukungan transaksi.

Peringatan

Beberapa skenario produksi akan menonaktifkan alat ini secara global untuk membatasi model secara luas.

execute_entity

Menjalankan prosedur tersimpan. Mendukung parameter input dan hasil output. Alat ini memvalidasi parameter input terhadap tanda tangan prosedur, memberlakukan izin eksekusi, dan melewati parameter dengan aman.

Konfigurasi runtime

Konfigurasikan alat DML secara global di bagian runtime Anda dab-config.json:

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "path": "/mcp",
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true
      }
    }
  }
}

Menggunakan CLI

Atur properti satu per satu menggunakan CLI penyusun API Data:

dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true

Menonaktifkan alat

Saat Anda menonaktifkan alat di tingkat runtime, alat tersebut tidak pernah muncul untuk agen, terlepas dari izin entitas atau konfigurasi peran. Pengaturan ini berguna ketika Anda memerlukan batas operasional yang ketat.

Skenario umum

• Nonaktifkan delete-record untuk mencegah kehilangan data dalam produksi
• Nonaktifkan create-record untuk titik akhir pelaporan baca-saja
• Nonaktifkan execute-entity saat prosedur tersimpan tidak digunakan

Ketika alat dinonaktifkan secara global, alat disembunyikan dari list_tools respons dan tidak dapat dipanggil.

Pengaturan entitas

Entitas berpartisipasi dalam MCP secara otomatis kecuali Anda secara eksplisit membatasinya. Properti dml-tools ada sehingga Anda dapat mengecualikan entitas dari MCP atau mempersempit kemampuannya, tetapi Anda tidak perlu mengatur apa pun untuk penggunaan normal.

{
  "entities": {
    "Products": {
      "mcp": {
        "dml-tools": true
      }
    },
    "SensitiveData": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

Jika Anda tidak menentukan mcp.dml-tools pada entitas, secara default akan beralih ke true ketika MCP diaktifkan secara global.

Kontrol terperinci

Anda dapat menonaktifkan alat tertentu untuk entitas individual:

{
  "entities": {
    "AuditLogs": {
      "mcp": {
        "dml-tools": {
          "create-record": true,
          "read-records": true,
          "update-record": false,
          "delete-record": false
        }
      }
    }
  }
}

Konfigurasi ini memungkinkan agen untuk membuat dan membaca log audit tetapi mencegah modifikasi atau penghapusan.

Integrasi RBAC

Setiap operasi alat DML memberlakukan aturan kontrol akses berbasis peran Anda. Peran agen menentukan entitas mana yang terlihat, operasi mana yang diizinkan, kolom mana yang disertakan, dan apakah kebijakan tingkat baris berlaku.

Jika peran anonymous hanya mengizinkan izin baca pada Products:

• describe_entities hanya menampilkan read_records dalam operasi
• create_record, update_record, dan delete_record tidak tersedia
• Hanya bidang yang diizinkan untuk anonymous muncul dalam skema

Konfigurasikan peran di dab-config.json:

{
  "entities": {
    "Products": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["ProductId", "ProductName", "Price"],
                "exclude": ["Cost"]
              }
            }
          ]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Konten terkait

• Gambaran Umum SQL MCP Server
• Menambahkan deskripsi semantik ke SQL MCP Server
• Referensi konfigurasi penyusun API Data (DAB)
• Menyebarkan SQL MCP Server ke Azure Container Apps