Guida rapida: Utilizzare il server SQL MCP con .NET Aspire

• Azure IA Foundry
• .NET Aspire
• Visual Studio Code
• App per container di Azure

Importante

SQL MCP Server è disponibile in anteprima e questa documentazione e l'implementazione del motore è soggetta a modifiche durante questo periodo di valutazione.

Questa guida rapida utilizza Aspire per creare una soluzione basata su contenitori. Questa soluzione comprende:

• Un database SQL con dati di esempio
• Un server SQL Model Context Protocol (MCP) basato su Data API Builder
• Ispettore MCP per i test

Aspire esegue tutto per l'utente, avvia i servizi, connette i contenitori e arresta i servizi quando viene chiuso.

Questo diagramma dell'architettura illustra un ambiente di test in contenitori in un computer locale con un ambiente Docker (rettangolo con bordo tratteggiato). All'interno del contenitore Docker sono disposti tre componenti: uno strumento MCP Inspector (casella arancione), un server MCP (Model Context Protocol) (casella 3D verde) e un database SQL (cilindro blu). Una freccia curva passa dal controllo MCP al server MCP, che dispone di una connessione bidirezionale al database. Questa configurazione consente agli sviluppatori di testare, eseguire il debug e controllare le interazioni del server MCP con un database SQL in un ambiente in contenitori isolato, con MCP Inspector che funge da strumento di diagnostica per convalidare la comunicazione tra gli agenti di intelligenza artificiale e il database.

Prerequisiti

Installare questi strumenti prima di iniziare.

1. .NET 10

In questo passaggio si prepara la macchina con i prerequisiti necessari per questa procedura rapida.

Importante

Questo strumento potrebbe essere già installato. Testarlo eseguendo dotnet --version e confermando che segnala la versione 10 o successiva. Se si esegue questa installazione e .NET è già presente, il sistema viene aggiornato senza causare problemi.

Windows

winget install Microsoft.DotNet.SDK.10

Oppure scaricare

https://get.dot.net

2. Runtime del contenitore

In questo passaggio si installa Docker Desktop per supportare il progetto Aspira.

Importante

Questo strumento potrebbe essere già installato. Testarlo eseguendo docker --version per verificare che Docker sia disponibile. Se si esegue questa installazione e Docker è già presente, il sistema viene aggiornato senza causare problemi.

Windows

winget install Docker.DockerDesktop

macOS

brew install --cask docker

Annotazioni

Podman funziona anche, ma la configurazione varia. Gli sviluppatori che preferiscono Podman possono adattare questi passaggi.

3. Aspire e strumenti per la generazione di API dei dati

In questo passaggio si creano i file di progetto Aspire predefiniti usati in un secondo momento.

Eseguire i comandi seguenti

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

Annotazioni

SQL MCP Server è attualmente in versione preliminare. L'uso del --prerelease flag garantisce di ottenere la versione più recente di Data API Builder con tutte le funzionalità usate in questa guida introduttiva.

Quando richiesto, selezionare tutte le impostazioni predefinite.

Questo comando installa gli strumenti e crea i file seguenti

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

4. Completare il file di AppHost.cs

In questo passaggio, aggiorni AppHost.cs con il codice corretto per eseguire rapidamente questa guida introduttiva.

Sostituire il contenuto di AppHost.cs con il codice seguente

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

Questo codice configura le risorse seguenti

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

5. Creare il file dab-config.json

Eseguire questi comandi nella cartella del progetto (la stessa cartella in cui AppHost.cs si trova).

La @env('MSSQL_CONNECTION_STRING') sintassi indica al generatore di API dati di leggere la stringa di connessione da una variabile di ambiente in fase di esecuzione. Aspire imposta automaticamente questa variabile quando avvia il contenitore, quindi non è necessario impostarla manualmente.

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

Annotazioni

L'espressione @env(...) è una funzionalità di configurazione DAB che risolve le variabili di ambiente in fase di esecuzione, non durante dab init. L'oggetto generato contiene la stringa dab-config.json letterale @env('MSSQL_CONNECTION_STRING'), che DAB risolve quando il contenitore si avvia.

Il dab-config.json file configura SQL MCP Server per connettersi al database e identifica gli oggetti da esporre. In questo caso, Products viene esposto.

Questo comando aggiunge un nuovo file al progetto

dab-config.json

Importante

Il dab-config.json file deve trovarsi nella stessa directory in cui si esegue aspire run, perché il montaggio bind usa un percorso relativo (./dab-config.json).

Facoltativamente, aggiungere descrizioni dei campi

Questi metadati consentono ai modelli linguistici di comprendere lo schema.

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"

Testare la soluzione personalizzata

In questo passaggio si esegue l'ambiente Aspira e si verifica che SQL Server, SQL MCP Server e MCP Inspector funzionino insieme.

1. Inizia Aspire

aspire run

Importante

Assicurarsi che Docker sia in esecuzione. Aspire richiede che il tuo host del contenitore funzioni correttamente.

Quando si apre il dashboard, vengono visualizzati i collegamenti per Swagger, MCP e Inspector.

URL previsti

Il dashboard Aspire visualizza questi link (le porte sono assegnate dinamicamente):

Conto risorse	Link	Description
sql-mcp-server	Swagger	Documentazione relativa all'API REST
sql-mcp-server	MCP	Endpoint MCP (/mcp)
ispettore	Ispettore	Interfaccia utente dell'Ispettore MCP

2. Testare l'API REST con Swagger

Selezionare Swagger nel dashboard.

Provare l'operazione GET per Prodotti. Questo test conferma che SQL MCP Server è in esecuzione e può connettersi al database.

3. Esplorare gli strumenti MCP

Selezionare Inspector nel dashboard.

Try:

• list_tools per visualizzare gli strumenti MCP disponibili
• read_recordsper l'entità Products

Provare un filtro (sintassi di esempio):

{ "filter": "Price gt 20" }

Questo test conferma il funzionamento di MCP.

4. Smettere di aspirare

Per fermare Aspire, premere Ctrl+C.

Aspire arresta tutti i servizi. I dati di SQL Server vengono mantenuti tra le esecuzioni perché il codice usa .WithDataVolume() e .WithLifetime(ContainerLifetime.Persistent).

Risoluzione dei problemi

L'avvio del contenitore di SQL MCP Server non riesce

• Per informazioni dettagliate sull'errore, controllare i registri del contenitore nel dashboard di Aspire.
• Verificare che l'argomento --config corrisponda alla sintassi prevista del contenitore DAB (alcune versioni potrebbero invece usare --ConfigFileName )
• Verificare che dab-config.json esista nella stessa directory in cui si esegue aspire run

Script di inizializzazione del database non trovato

• Verificare che init-db.sql si trovi nella directory del progetto AppHost
• Verificare che il file sia incluso nel progetto e sia copiato nell'output, se necessario

Il controllo MCP non è in grado di connettersi

• Verificare che il contenitore SQL MCP Server sia in esecuzione e integro
• Verificare che il percorso dell'endpoint MCP (/mcp) corrisponda alla configurazione DAB

Contenuti correlati

• Panoramica di SQL MCP Server
• Strumenti di manipolazione dei dati in SQL MCP Server
• Aggiunta di descrizioni semantiche al server SQL MCP