Guida introduttiva: Usare SQL MCP Server con .NET Aspire

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.

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.

winget install Microsoft.DotNet.SDK.10

2. Runtime del contenitore

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

winget install Docker.DockerDesktop

brew install --cask docker

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
aspire init

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", "2.0.1-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 sintassi @env('MSSQL_CONNECTION_STRING') indica al generatore di API dati di leggere il 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."

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

Aggiungi descrizioni dei campi alle entità:

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 conferma che SQL Server, SQL MCP Server e MCP Inspector interagiscono.

1. Inizia Aspire

aspire run

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):

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. SQL Server i dati 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 venga 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