Rychlý start: Použití SQL MCP Serveru s .NET Aspire

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

Důležité

Sql Model Context Protocol (MCP) Server je ve verzi Preview a tato dokumentace a implementace modulu se může změnit. I když je Tvůrce rozhraní API pro Data ve verzi 1.7 v režimu Preview, musíte explicitně použít předběžnou verzi (například 1.7.83-rc), protože funkce MCP ještě nejsou součástí značky :latest.

V tomto rychlém startu se k sestavení řešení založeného na kontejneru používá Aspire. Řešení zahrnuje:

• Databáze SQL s ukázkovými daty
• Server PROTOKOLU MCP (SQL Model Context Protocol) využívající tvůrce rozhraní Data API
• Inspektor MCP pro testování

Aspire spustí vše za vás, spustí služby a připojí kontejnery a zastaví služby, když ho zavřete.

Požadavky

Než začnete, nainstalujte tyto nástroje.

1. .NET 10

V tomto kroku připravíte počítač s požadavky požadovanými pro účely tohoto rychlého startu.

Důležité

Tento nástroj už možná máte nainstalovaný. Otestujte ho spuštěním dotnet --version a ověřením, že hlásí verzi 10 nebo novější. Pokud tuto instalaci spustíte a rozhraní .NET už existuje, aktualizuje systém bez jakýchkoli problémů.

Windows

winget install Microsoft.DotNet.SDK.10

macOS

Stáhněte a nainstalujte z get.dot.net.

2. Modul runtime kontejneru

V tomto kroku nainstalujete Docker Desktop pro podporu projektu Aspire.

Důležité

Tento nástroj už možná máte nainstalovaný. Otestujte ho spuštěním docker --version a ověřte, že je Docker dostupný. Pokud spustíte tuto instalaci a Docker už existuje, aktualizuje systém bez jakýchkoli problémů.

Windows

winget install Docker.DockerDesktop

macOS

brew install --cask docker

Poznámka:

Podman také funguje, ale nastavení se liší. Vývojáři, kteří dávají přednost podmanu, můžou tyto kroky přizpůsobit.

3. Nástroje Aspire a nástroje pro tvorbu rozhraní Data API

V tomto kroku vytvoříte výchozí soubory projektu Aspire použité později. Spusťte následující příkazy:

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

Poznámka:

SQL MCP Server je aktuálně v předběžné verzi. Použití příznaku --prerelease zajišťuje, že získáte nejnovější verzi Tvůrce rozhraní Data API se všemi funkcemi použitými v tomto rychlém startu.

Po zobrazení výzvy vyberte všechny výchozí hodnoty.

Tento příkaz nainstaluje nástroje a vytvoří následující soubory:

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

4. Dokončete soubor AppHost.cs

V tomto kroku provedete aktualizaci AppHost.cs správným kódem pro spuštění tohoto rychlého startu. AppHost.cs Obsah nahraďte následujícím kódem:

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

Tento kód konfiguruje následující prostředky:

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

5. Vytvoření souboru dab-config.json

Spusťte tyto příkazy ve složce projektu (stejná složka, ve které AppHost.cs se nachází):

Syntaxe @env('MSSQL_CONNECTION_STRING') určuje aplikaci Data API Builder, aby načetla připojovací řetězec z proměnné prostředí za běhu. Aspire nastaví tuto proměnnou automaticky při spuštění kontejneru, takže ji nemusíte nastavovat místně.

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

Poznámka:

Výraz @env(...) je konfigurační funkce DAB, která za běhu řeší proměnné prostředí, nikoli během dab init. Vygenerovaný dab-config.json obsahuje textový řetězec @env('MSSQL_CONNECTION_STRING'), který DAB vyřeší při spuštění kontejneru.

Soubor dab-config.json nakonfiguruje SQL MCP Server pro připojení k vaší databázi a identifikuje objekty, které mají být vystaveny. V tomto případě je Products vystavený.

Tento příkaz přidá do projektu nový soubor:

dab-config.json

Důležité

Soubor dab-config.json musí být ve stejném adresáři, ve kterém spouštíte aspire run, protože vazební připojení používá relativní cestu (./dab-config.json).

Volitelně můžete přidat popisy polí. Tato metadata můžou pomoct jazykové modely porozumět vašemu schématu.

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"

Testování řešení

V tomto kroku spustíte prostředí Aspire a potvrdíte, že SQL Server, SQL MCP Server a kontrola MCP spolupracují.

1. Spustit Aspire

aspire run

Důležité

Ujistěte se, že je Docker spuštěný. Aspire vyžaduje, aby hostitel kontejneru fungoval správně.

Po otevření řídicího panelu se zobrazí odkazy pro Swagger, MCP a Inspector.

Očekávané adresy URL

Řídicí panel Aspire zobrazí tyto odkazy (porty se přiřazují dynamicky):

Resource	Link	Description
sql-mcp-server	Swagger	Dokumentace k rozhraní REST API
sql-mcp-server	MCP	Koncový bod MCP (/mcp)
inspektor	Inspektor	Uživatelské rozhraní inspektoru MCP

2. Testování rozhraní REST API pomocí Swaggeru

Na řídicím panelu vyberte Swagger .

Zkuste operaci GET pro produkty. Tento test potvrzuje, že je spuštěný SQL MCP Server a může se připojit k databázi.

3. Prozkoumání nástrojů MCP

Na řídicím panelu vyberte inspektor .

Try:

• list_tools k zobrazení dostupných nástrojů MCP
• read_recordspro entitu Products

Zkuste filtr (ukázková syntaxe):

{ "filter": "Price gt 20" }

Tento test potvrzuje, že MCP funguje.

4. Zastavit Aspire

Chcete-li zastavit Aspire, stiskněte Ctrl+C.

Aspire zastaví všechny služby. Data SQL Serveru se uchovávají mezi spuštěními, protože kód používá .WithDataVolume() a .WithLifetime(ContainerLifetime.Persistent).

Řešení problémů

Kontejner SQL MCP Serveru se nespustí

• Podrobnosti o chybě najdete v protokolech kontejneru na řídicím panelu Aspire.
• Ověřte, že --config argument odpovídá očekávané syntaxi kontejneru DAB (některé verze můžou místo toho použít --ConfigFileName ).
• Ujistěte se, že dab-config.json existuje ve stejném adresáři, ve kterém spouštíte aspire run.

Skript inicializace databáze nebyl nalezen.

• Ověřte init-db.sql , že je v adresáři projektu AppHost.
• Zkontrolujte, jestli je soubor v projektu zahrnutý, a pokud je to potřeba, zkopíruje se do výstupu.

Kontrolor MCP se nemůže připojit

• Ověřte, že je kontejner SQL MCP Serveru spuštěný a v pořádku.
• Ověřte, že cesta ke koncovému bodu MCP (/mcp) odpovídá konfiguraci DAB.

Související obsah

• Přehled SQL MCP Serveru
• Nástroje pro manipulaci s daty na SQL MCP Serveru
• Přidání sémantických popisů na SQL MCP Server