Stdio transportasi untuk SQL MCP Server

Penting

Server Protokol Konteks Model SQL (MCP) tersedia di pembuat API Data versi 1.7 dan yang lebih baru.

SQL MCP Server mendukung dua transportasi: HTTP yang dapat dialirkan untuk skenario yang dihosting dan cloud, dan stdio untuk pengembangan lokal dan integrasi agen langsung. Artikel ini membahas stdio transportasi.

Dalam stdio mode, Penyusun API Data (DAB) berkomunikasi dengan klien MCP sepenuhnya melalui input/output standar (stdin/stdout). Tidak ada server HTTP atau port jaringan yang berjalan. Klien MCP meluncurkan DAB sebagai proses turunan dan menyalurkan pesan bolak-balik dengan menggunakan Protokol Konteks Model (MCP).

Kapan menggunakan stdio transportasi

Skenario Transportasi yang direkomendasikan
Pengembangan lokal di stasiun kerja pengembang stdio
Visual Studio Code dengan GitHub Copilot (mode Asisten) stdio
Alur CI/CD atau otomatisasi agen berskrip stdio
Cloud Hosting (Container Apps, App Service) HTTP
Agen AI Foundry dengan titik akhir MCP jarak jauh HTTP
Tim agen yang berbagi titik akhir yang sama HTTP

Pilih stdio kapan Anda menginginkan penyiapan lokal paling sederhana tanpa port terbuka. Pilih HTTP ketika server MCP perlu dijangkau di seluruh jaringan.

Prasyarat

  • CLI penyusun API Data terinstal (versi 1.7 atau yang lebih baru)
  • Yang sudah ada dab-config.json dengan MCP diaktifkan (lihat Konfigurasi yang diperlukan)
  • Klien yang kompatibel dengan MCP (Visual Studio Code dengan GitHub Copilot, Claude Desktop, atau agen kustom)

Konfigurasi yang diperlukan

Sebelum menggunakan stdio transport, aktifkan MCP di 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,
      "aggregate-records": true
    }
  }
}

Bidang path ini hanya digunakan untuk transportasi HTTP dan diabaikan dalam stdio mode. Blok dml-tools kontrol operasi manipulasi data mana yang tersedia sebagai alat MCP.

Penting

Jika "mcp": { "enabled": false } atau mcp blok hilang, DAB gagal memulai dalam stdio mode.

Mulai dalam stdio mode

Gunakan --mcp-stdio tanda pada dab start

dab start --mcp-stdio --config ./dab-config.json

Untuk menjalankan di bawah peran izin tertentu:

dab start --mcp-stdio role:authenticated --config ./dab-config.json

Argumen role:<name> bersifat posisi dan harus segera mengikuti --mcp-stdio. Jika dihilangkan, fungsi menjadi anonymous. Nama peran harus sesuai dengan peran yang telah ditetapkan di bagian permissions dari setidaknya satu entitas dalam konfigurasi Anda.

Cara kerja stdio mode

Ketika --mcp-stdio terdeteksi, DAB membuat perubahan berikut secara internal:

Pengodean UTF-8 (tanpa tanda urutan byte)

Input dan output konsol dikonfigurasi menjadi UTF-8 tanpa penanda urutan byte (BOM). Pengaturan UTF-8 ini diperlukan untuk komunikasi yang bersih JSON-over-stdio karena banyak klien MCP menolak aliran awalan BOM.

Autentikasi simulator

Penyedia autentikasi diubah menjadi mode Simulator, terlepas dari apa pun yang ditentukan file konfigurasi Anda. Mode Simulator ini memungkinkan peran yang ditentukan diterapkan secara langsung tanpa JSON Web Token (JWT) nyata atau penyedia identitas. Penyedia layanan simulasi dirancang untuk skenario pengembangan dan tidak direkomendasikan untuk mengamankan endpoint HTTP produksi, namun sangat sesuai untuk sesi lokal stdio .

Nilai berikut diterapkan dalam memori dan mengambil alih konfigurasi Anda selama sesi:

Kunci Nilai
MCP:StdioMode "true"
MCP:Role "<role-name>" atau "anonymous"
Runtime:Host:Authentication:Provider "Simulator"

Tidak ada pendengar HTTP

Host ASP.NET Core dimulai dan semua layanan terdaftar, tetapi DAB memanggil stdio.RunAsync() alih-alih host.Run(). Tidak ada port Protokol Kontrol Transmisi (TCP) yang terikat. Semua pesan protokol MCP mengalir melalui stdin/stdout.

Alat MCP yang tersedia

Alat berikut tersedia dalam mode stdio, dengan ketentuan konfigurasi Anda dan izin entitas dml-tools.

Alat Deskripsi
describe_entities Mencantumkan entitas yang tersedia beserta bidang dan izinnya
create_record Menyisipkan rekaman baru (hanya tabel)
read_records Membaca catatan dari entitas
update_record Memperbarui rekaman yang sudah ada
delete_record Menghapus rekaman yang sudah ada (tabel dan tampilan)
execute_entity Menjalankan entitas prosedur tersimpan
aggregate_records Melakukan kueri agregasi pada tabel dan tampilan

Alat MCP kustom yang didukung oleh prosedur tersimpan juga terdaftar saat Anda menggunakan --mcp-stdio.

Mengonfigurasi klien MCP untuk stdio

Klien MCP yang mendukung stdio meluncurkan transport sebagai subproses dan menyalurkan stdin/stdout. Sintaks konfigurasi klien bervariasi menurut klien.

Visual Studio Code (mcp.json)

{
  "servers": {
    "sql-mcp-server": {
      "type": "stdio",
      "command": "dab",
      "args": [
        "start",
        "--mcp-stdio", "role:anonymous",
        "--config", "{path}/dab-config.json",
        "--LogLevel", "error"
      ]
    }
  }
}

Simpan file ini seperti .vscode/mcp.json di dalam folder proyek Anda. VS Code mendeteksi konfigurasi secara otomatis dan menunjukkan server di MCP: Daftar Server. Karena klien mengelola siklus hidup proses, Anda tidak perlu berjalan dab start secara terpisah di terminal.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "sql-mcp-server": {
      "type": "stdio",
      "command": "dab",
      "args": [
        "start",
        "--mcp-stdio", "role:anonymous",
        "--config", "{path}/dab-config.json",
        "--LogLevel", "error"
      ]
    }
  }
}

Gabungkan dengan opsi lain dab start

--mcp-stdio kompatibel dengan semua opsi lainnya dab start :

Option Perilaku dengan --mcp-stdio
--config Menggunakan file konfigurasi yang ditentukan (sama dengan mode HTTP)
--LogLevel Menerapkan tingkat log yang ditentukan (error: disarankan untuk stdio) 
dab start \
  --mcp-stdio role:api-reader \
  --config ./dab-config.json \
  --LogLevel Error

Mode pemecahan masalah stdio

Failed to start the engine in MCP stdio mode

DAB tidak dapat memulai. Periksa apakah:

  • File konfigurasi Anda valid: silakan jalankan perintah dab validate --config <path>
  • String koneksi database Anda benar dan dapat dijangkau
  • MCP diaktifkan dalam konfigurasi Anda: "mcp": { "enabled": true }

Izin ditolak pada panggilan alat MCP

Peran yang ditentukan oleh role:<name> tidak memiliki izin yang diperlukan untuk entitas dan operasi. Periksa bagian permissions entitas yang relevan di konfigurasi Anda.

Alat MCP tidak tercantum

Entah dml-tools disetel ke false secara global, atau entitas memiliki pengaturan "dml-tools": falsemcp. Verifikasi juga bahwa mcp.enabled adalah true.

Kesalahan penguraian output yang acak atau JSON

Pastikan tidak ada dalam kode startup Anda yang menulis teks non-JSON ke stdout sebelum server MCP dimulai. Output log harus masuk ke stderr atau file log, bukan stdout. Gunakan --LogLevel untuk menekan pesan startup yang berlebihan jika diperlukan.

Konten terkait

  • Last updated on