Hızlı Başlangıç: SQL MCP Server'ı .NET Aspire ile kullanma

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

Önemli

SQL Model Bağlam Protokolü (MCP) Sunucusu önizleme aşamasındadır ve bu belgeler ve altyapı uygulaması değişebilir. Veri API oluşturucusu sürüm 1.7 önizleme aşamasındayken, MCP özellikleri henüz etikete dahil 1.7.83-rc edilmediğinden yayın öncesi sürümü açıkça kullanmanız gerekir (örneğin, :latest).

Bu hızlı başlangıçta kapsayıcı tabanlı bir çözüm oluşturmak için Aspire kullanılır. Çözüm şunları içerir:

• Örnek veri içeren bir SQL veritabanı
• Veri API oluşturucusu tarafından desteklenen bir SQL Modeli Bağlam Protokolü (MCP) Sunucusu
• Test için MCP Denetçisi

Aspire sizin için her şeyi çalıştırır, hizmetleri başlatır ve kapsayıcıları bağlar ve kapattığınızda hizmetleri durdurur.

Önkoşullar

Başlamadan önce bu araçları yükleyin.

1. .NET 10

Bu adımda, makinenizi bu hızlı başlangıç için gereken önkoşullarla hazırlarsınız.

Önemli

Bu aracı zaten yüklemiş olabilirsiniz. Çalıştırarak dotnet --version test edin ve sürüm 10 veya üzerini bildirdiğinden emin olun. Bu yüklemeyi çalıştırırsanız ve .NET zaten varsa, herhangi bir soruna neden olmadan sisteminizi yeniler.

Windows

winget install Microsoft.DotNet.SDK.10

macOS

get.dot.net'dan indirin ve yükleyin.

2. Kapsayıcı çalışma zamanı

Bu adımda, Aspire projesini desteklemek için Docker Desktop'ı yüklersiniz.

Önemli

Bu aracı zaten yüklemiş olabilirsiniz. Docker'ın kullanılabilir olduğunu onaylamak için komutunu çalıştırarak docker --version test edin. Bu yüklemeyi çalıştırırsanız ve Docker zaten varsa, herhangi bir soruna neden olmadan sisteminizi yeniler.

Windows

winget install Docker.DockerDesktop

macOS

brew install --cask docker

Uyarı

Podman da çalışır, ancak kurulum değişir. Podman'ı tercih eden geliştiriciler bu adımları uyarlayabilir.

3. Aspire ve Data API oluşturucu araçları

Bu adımda, daha sonra kullanılan varsayılan Aspire proje dosyalarını oluşturursunuz. Aşağıdaki komutları çalıştırın:

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

Uyarı

SQL MCP Server şu anda ön sürümdedir. bayrağını --prerelease kullanmak, bu hızlı başlangıçta kullanılan tüm özelliklerle Data API builder'ın en son sürümünü edinmenizi sağlar.

İstendiğinde tüm varsayılanları seçin.

Bu komut aracı yükler ve aşağıdaki dosyaları oluşturur:

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

4. AppHost.cs dosyasını tamamlayın

Bu adımda, bu hızlı başlangıç kılavuzunu çalıştırmak için AppHost.cs doğru kodla güncelleyin. öğesinin içeriğini AppHost.cs aşağıdakilerle değiştirin:

#: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);
    """;

Bu kod aşağıdaki kaynakları yapılandırıyor:

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

5. dab-config.json dosyanızı oluşturma

Bu komutları proje klasörünüzde (bulunduğu AppHost.cs klasörle aynı klasör) çalıştırın:

Söz dizimi, @env('MSSQL_CONNECTION_STRING') Veri API'sinin oluşturucusunun çalışma zamanında bir ortam değişkeninden bağlantı dizesini okumasını söyler. Aspire kapsayıcıyı başlattığında bu değişkeni otomatik olarak ayarlar, bu nedenle yerel olarak ayarlamanız gerekmez.

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

Uyarı

** @env(...) ifadesi, dab init sırasında değil, çalışma zamanında ortam değişkenlerini çözümleyen bir DAB yapılandırma özelliğidir. Oluşturulan dab-config.json, sabit dize @env('MSSQL_CONNECTION_STRING')'yi içerir ve bu dize, kapsayıcı başlatıldığında DAB tarafından çözümlenir.

Dosya, dab-config.json SQL MCP Server'ı veritabanınıza bağlanacak şekilde yapılandırarak hangi nesnelerin kullanıma açılabilir olduğunu tanımlar. Bu durumda, Products açığa çıkar.

Bu komut projenize yeni bir dosya ekler:

dab-config.json

Önemli

dab-config.json dosyasının, aspire run çalıştırdığınız dizinde olması gerekir, çünkü bind mount göreli bir yol kullanır (./dab-config.json).

İsteğe bağlı olarak, alan açıklamaları ekleyin. Bu meta veriler dil modellerinin şemanızı anlamasına yardımcı olabilir.

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"

Çözümünüzü test edin

Bu adımda Aspire ortamınızı çalıştırır ve SQL Server, SQL MCP Server ve MCP Denetçisi'nin birlikte çalıştığını onaylarsınız.

1. Aspire'i başlatma

aspire run

Önemli

Docker'ın çalıştığından emin olun. Aspire, kapsayıcı ana bilgisayarınızın düzgün bir şekilde çalışmasını gerektirir.

Pano açıldığında Swagger, MCP ve Inspector bağlantılarını görürsünüz.

Beklenen URL'ler

Aspire panosu şu bağlantıları görüntüler (bağlantı noktaları dinamik olarak atanır):

Resource	Link	Description
sql-mcp-server	Swagger	REST API belgeleri
sql-mcp-server	MCP	MCP uç noktası (/mcp)
müfettiş	Müfettiş	MCP Denetçisi UI

2. REST API'yi Swagger ile test edin

Panodan Swagger'ı seçin.

Ürünler için GET işlemini deneyin. Bu test, SQL MCP Server'ın çalıştığını ve veritabanına bağlanabildiğini onaylar.

3. MCP araçlarını keşfedin

Panodan Denetçi'yi seçin.

Try:

• list_tools kullanılabilir MCP araçlarını görmek için
• read_records Products varlık için

Filtreyi deneyin (örnek söz dizimi):

{ "filter": "Price gt 20" }

Bu test MCP'nin çalıştığını doğrular.

4. Aspire'i Durdur

Aspire'i durdurmak için tuşuna basın Ctrl+C.

Aspire tüm hizmetleri durdurur. Kod .WithDataVolume() ve .WithLifetime(ContainerLifetime.Persistent) kullandığı için, SQL Server verileri çalıştırmalar arasında kalır.

Sorun giderme

SQL MCP Server kapsayıcısı başlatılamıyor

• Hata ayrıntıları için Aspire kontrol panelindeki kapsayıcı günlüklerini kontrol edin
• --config bağımsız değişkeninin DAB kapsayıcısının beklenen söz dizimine uygun olup olmadığını doğrulayın (bazı sürümler bunun yerine --ConfigFileName kullanabilir)
• dab-config.json'ın, aspire run çalıştırdığınız dizinde bulunduğundan emin olun.

Veritabanı başlatma betiği bulunamadı

• init-db.sql AppHost proje dizininde doğrulayın
• Dosyanın projeye eklenip eklenmediğini ve gerekirse çıkışa kopyalanıp kopyalanmadığını denetleyin

MCP Denetçisi bağlanamıyor

• SQL MCP Server kapsayıcısının çalıştığını ve iyi durumda olduğunu onaylayın
• MCP uç noktası yolunun (/mcp) DAB yapılandırmasıyla eşleştiğinden emin olun

İlgili içerik

• SQL MCP Server'a genel bakış
• SQL MCP Server'da veri işleme araçları
• SQL MCP Server'a anlamsal açıklamalar ekleme