Mulai cepat: Menggunakan SQL MCP Server dengan .NET Aspire

• Azure AI Foundry
• .NET Aspire
• Visual Studio Code
• Azure Container Apps

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.

Panduan memulai cepat ini menggunakan Aspire untuk membangun solusi berbasis kontainer. Solusinya meliputi:

• Database SQL dengan data sampel
• Server SQL Model Context Protocol (MCP) yang didukung oleh penyusun API Data
• Inspektur MCP untuk pengujian

Aspire menjalankan semuanya untuk Anda, memulai layanan dan menghubungkan kontainer, dan menghentikan layanan saat Anda menutupnya.

Prasyarat

Instal alat-alat ini sebelum Anda memulai.

1. .NET 10

Dalam langkah ini, Anda menyiapkan mesin Anda dengan prasyarat yang diperlukan untuk quickstart ini.

Penting

Anda mungkin sudah menginstal alat ini. Uji dengan menjalankan dotnet --version dan memastikan bahwa itu melaporkan versi 10 atau yang lebih baru. Jika Anda menjalankan penginstalan ini dan .NET sudah ada, itu menyegarkan sistem Anda tanpa menyebabkan masalah apa pun.

Windows

winget install Microsoft.DotNet.SDK.10

macOS

Unduh dan instal dari get.dot.net.

2. Runtime kontainer

Dalam langkah ini, Anda menginstal Docker Desktop untuk mendukung proyek Aspire.

Penting

Anda mungkin sudah menginstal alat ini. Uji dengan menjalankan docker --version untuk mengonfirmasi bahwa Docker tersedia. Jika Anda menjalankan penginstalan ini dan Docker sudah ada, itu menyegarkan sistem Anda tanpa menyebabkan masalah apa pun.

Windows

winget install Docker.DockerDesktop

macOS

brew install --cask docker

Nota

Podman juga berfungsi, tetapi pengaturan bervariasi. Pengembang yang lebih suka Podman dapat menyesuaikan langkah-langkah ini.

3. Alat pembangun Aspire dan Data API

Dalam langkah ini, Anda membuat file proyek Aspire default yang digunakan nanti. Jalankan perintah berikut:

dotnet new tool-manifest
dotnet tool install aspire.cli
dotnet tool install microsoft.dataapibuilder --prerelease
aspire init

Nota

SQL MCP Server saat ini sedang dalam prarilis. Menggunakan tanda --prerelease memastikan Anda mendapatkan versi terbaru dari Data API Builder dengan semua fitur yang digunakan dalam panduan cepat ini.

Saat diminta, pilih semua default.

Perintah ini menginstal alat dan membuat file berikut:

.
├── .config
│   └── dotnet-tools.json
├── AppHost.cs
└── apphost.run.json

4. Selesaikan file AppHost.cs

Dalam langkah ini, Anda memperbarui AppHost.cs dengan kode yang benar untuk menjalankan mulai cepat ini. Ganti konten AppHost.cs dengan yang berikut ini:

#:sdk Aspire.AppHost.Sdk@13.0.2
#:package Aspire.Hosting.SqlServer@13.0.2
#:package CommunityToolkit.Aspire.Hosting.McpInspector@9.8.0

using System.ComponentModel;
using Aspire.Hosting;
using Aspire.Hosting.ApplicationModel;

var builder = DistributedApplication.CreateBuilder(args);

var db = AddSqlServer(builder);
WithSqlCommander(db);

var mcp = AddMcpServer(db);
WithMcpInspector(mcp);

await builder.Build().RunAsync();

IResourceBuilder<SqlServerDatabaseResource> AddSqlServer(IDistributedApplicationBuilder builder) => builder
    .AddSqlServer("sql-server").WithDataVolume()
    .AddDatabase("sql-database", "productsdb")
    .WithCreationScript(SqlScript("productsdb"));

IResourceBuilder<ContainerResource> WithSqlCommander(IResourceBuilder<SqlServerDatabaseResource> db) => db
    .ApplicationBuilder.AddContainer("sql-cmdr", "jerrynixon/sql-commander", "latest")
    .WithImageRegistry("docker.io")
    .WithHttpEndpoint(targetPort: 8080, name: "http")
    .WithEnvironment("ConnectionStrings__db", db)
    .WithParentRelationship(db)
    .WaitFor(db)
    .WithUrls(x =>
    {
        x.Urls.Clear();
        x.Urls.Add(new() { Url = "/", DisplayText = "Commander", Endpoint = x.GetEndpoint("http") });
    });

IResourceBuilder<ContainerResource> AddMcpServer(IResourceBuilder<SqlServerDatabaseResource> db) => db
    .ApplicationBuilder.AddContainer("sql-mcp-server", "azure-databases/data-api-builder", "1.7.83-rc")
    .WithImageRegistry("mcr.microsoft.com")
    .WithHttpEndpoint(targetPort: 5000, name: "http")
    .WithEnvironment("MSSQL_CONNECTION_STRING", db)
    .WithBindMount("dab-config.json", "/App/dab-config.json", true)
    .WaitFor(db)
    .WithUrls(x =>
    {
        x.Urls.Clear();
        x.Urls.Add(new() { Url = "/swagger", DisplayText = "Swagger", Endpoint = x.GetEndpoint("http") });
    });

IResourceBuilder<McpInspectorResource> WithMcpInspector(IResourceBuilder<ContainerResource> mcp) => mcp
    .ApplicationBuilder.AddMcpInspector("mcp-inspector")
    .WithMcpServer(mcp)
    .WithParentRelationship(mcp)
    .WaitFor(mcp)
    .WithUrls(x =>
    {
        x.Urls[0].DisplayText = "Inspector";
    });

string SqlScript(string db) => $"""
    CREATE DATABASE {db};
    GO

    SELECT *
    INTO {db}.dbo.Products
    FROM (VALUES
        (1, 'Action Figure', 40, 14.99, 5.00),
        (2, 'Building Blocks', 25, 29.99, 10.00),
        (3, 'Puzzle 500 pcs', 30, 12.49, 4.00),
        (4, 'Toy Car', 50, 7.99, 2.50),
        (5, 'Board Game', 20, 34.99, 12.50),
        (6, 'Doll House', 10, 79.99, 30.00),
        (7, 'Stuffed Bear', 45, 15.99, 6.00),
        (8, 'Water Blaster', 35, 19.99, 7.00),
        (9, 'Art Kit', 28, 24.99, 8.00),
        (10,'RC Helicopter', 12, 59.99, 22.00)
    ) AS x (Id, Name, Inventory, Price, Cost);

    ALTER TABLE {db}.dbo.Products
    ADD CONSTRAINT PK_Products PRIMARY KEY (Id);
    """;

Kode ini mengonfigurasi sumber daya berikut:

.
├── SQL Server (sql)
│   └── SQL Database (productsdb)
└── SQL MCP Server (sql-mcp-server)
    └── MCP Inspector (inspector)

5. Buat file dab-config.json Anda

Jalankan perintah ini di folder proyek Anda (folder yang sama di mana AppHost.cs berada):

@env('MSSQL_CONNECTION_STRING') Sintaksnya memberi tahu pembuat API Data untuk membaca string koneksi dari variabel lingkungan saat runtime. Aspire mengatur variabel ini secara otomatis saat memulai kontainer, sehingga Anda tidak perlu mengaturnya secara lokal.

dab init --database-type mssql --connection-string "@env('MSSQL_CONNECTION_STRING')" --host-mode Development --config dab-config.json
dab add Products --source dbo.Products --permissions "anonymous:read" --description "Toy store products with inventory, price, and cost."

Nota

Ekspresi @env(...) adalah fitur konfigurasi DAB yang menyelesaikan variabel lingkungan saat runtime, bukan selama dab init. Yang dihasilkan dab-config.json berisi string literal @env('MSSQL_CONNECTION_STRING'), yang akan diselesaikan oleh DAB ketika kontainer dimulai.

File dab-config.json mengonfigurasi SQL MCP Server untuk menyambungkan ke database Anda dan mengidentifikasi objek mana yang akan diekspos. Dalam hal ini, Products diekspos.

Perintah ini menambahkan file baru ke proyek Anda:

dab-config.json

Penting

File dab-config.json harus berada di direktori yang sama tempat Anda menjalankan aspire run, karena bind mount menggunakan path relatif (./dab-config.json).

Secara opsional, tambahkan deskripsi bidang. Metadata ini dapat membantu model bahasa memahami skema Anda.

dab update Products --fields.name Id --fields.primary-key true --fields.description "Product Id"
dab update Products --fields.name Name --fields.description "Product name"
dab update Products --fields.name Inventory --fields.description "Units in stock"
dab update Products --fields.name Price --fields.description "Retail price"
dab update Products --fields.name Cost --fields.description "Store cost"

Menguji solusi Anda

Dalam langkah ini, Anda menjalankan lingkungan Aspire dan mengonfirmasi bahwa SQL Server, SQL MCP Server, dan McP Inspector bekerja sama.

1. Mulai Aspire

aspire run

Penting

Pastikan Docker berjalan. Aspire mengharuskan host kontainer Anda berfungsi dengan baik.

Saat dasbor terbuka, Anda akan melihat tautan untuk Swagger, MCP, dan Inspector.

URL yang diharapkan

Dasbor Aspire menampilkan tautan ini (port ditetapkan secara dinamis):

Sumber Daya	Link	Description
sql-mcp-server	Swagger	Dokumentasi REST API
sql-mcp-server	MCP	Titik akhir MCP (/mcp)
Inspektur	Inspektur	Inspektur UI MCP

2. Uji REST API dengan Swagger

Pilih Swagger dari dasbor.

Coba operasi GET untuk Produk. Pengujian ini mengonfirmasi SQL MCP Server berjalan dan dapat tersambung ke database.

3. Jelajahi alat MCP

Pilih Pemeriksa dari dasbor.

Try:

• list_tools untuk melihat alat MCP yang tersedia
• untuk entitas read_recordsProducts

Coba sebuah filter (misalnya sintaks):

{ "filter": "Price gt 20" }

Tes ini mengonfirmasi MCP berfungsi.

4. Hentikan Aspire

Untuk menghentikan Aspire, tekan Ctrl+C.

Aspire menghentikan semua layanan. Data SQL Server bertahan di antara eksekusi karena kode menggunakan .WithDataVolume() dan .WithLifetime(ContainerLifetime.Persistent).

Troubleshooting

Kontainer SQL MCP Server gagal dimulai

• Periksa log kontainer di dasbor Aspire untuk detail kesalahan
• Verifikasikan bahwa argumen --config sesuai dengan sintaks yang diharapkan dari kontainer DAB (beberapa versi mungkin menggunakan --ConfigFileName sebagai gantinya)
• Pastikan dab-config.json ada di direktori yang sama tempat Anda menjalankan aspire run

Skrip inisialisasi database tidak ditemukan

• Verifikasi init-db.sql ada di direktori proyek AppHost
• Periksa apakah file disertakan dalam proyek dan menyalin ke output jika diperlukan.

Inspektur MCP tidak dapat tersambung

• Mengonfirmasi bahwa kontainer SQL MCP Server berjalan dan sehat
• Verifikasi jalur titik akhir MCP (/mcp) cocok dengan konfigurasi DAB

Konten terkait

• Gambaran Umum SQL MCP Server
• Alat manipulasi data di SQL MCP Server
• Menambahkan deskripsi semantik ke SQL MCP Server