Schnellstart: Verwenden von SQL MCP Server mit .NET Aspire

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

Von Bedeutung

SQL MCP Server befindet sich in der Vorschau, und diese Dokumentation und die Modulimplementierung kann während dieses Auswertungszeitraums geändert werden.

Diese Schnellstartanleitung verwendet Aspire zum Erstellen einer containerbasierten Lösung. Die Lösung beinhaltet Folgendes:

• Eine SQL-Datenbank mit Beispieldaten
• Ein SQL Model Context Protocol (MCP)-Server, der vom Daten-API-Generator unterstützt wird
• MCP Inspector für Testzwecke

Aspire führt alles für Sie aus, startet Dienstleistungen und verbindet Container und stoppt Dienste, wenn Sie es schließen.

Dieses Architekturdiagramm veranschaulicht eine containerisierte Testumgebung auf einem lokalen Computer mit einer Docker-Umgebung (gestricheltes Rahmenrechteck). Innerhalb des Docker-Containers werden drei Komponenten angeordnet: ein MCP Inspector-Tool (orange), ein MCP-Server (Model Context Protocol) (grünes 3D-Feld) und eine SQL-Datenbank (blauer Zylinder). Ein gekrümmter Pfeil fließt vom MCP Inspector zum MCP-Server, der über eine bidirektionale Verbindung mit der Datenbank verfügt. Mit diesem Setup können Entwickler die Interaktionen des MCP-Servers mit einer SQL-Datenbank in einer isolierten containerisierten Umgebung testen, debuggen und prüfen, wobei der MCP-Inspektor als Diagnosetool dient, um die Kommunikation zwischen KI-Agents und der Datenbank zu überprüfen.

Voraussetzungen

Installieren Sie diese Tools, bevor Sie beginnen.

1. .NET 10

In diesem Schritt bereiten Sie Ihre Maschine mit den erforderlichen Voraussetzungen für diesen Schnellstart vor.

Von Bedeutung

Möglicherweise ist dieses Tool bereits installiert. Testen Sie das Programm, indem Sie dotnet --version ausführen und bestätigen, dass es Version 10 oder höher anzeigt. Wenn Sie diese Installation ausführen und .NET bereits vorhanden ist, wird Ihr System aktualisiert, ohne dass Probleme auftreten.

Fenster

winget install Microsoft.DotNet.SDK.10

Oder herunterladen

https://get.dot.net

2. Containerlaufzeit

In diesem Schritt installieren Sie Docker Desktop, um das Aspire-Projekt zu unterstützen.

Von Bedeutung

Möglicherweise ist dieses Tool bereits installiert. Testen Sie sie, indem Sie ausführen docker --version , um zu bestätigen, dass Docker verfügbar ist. Wenn Sie diese Installation ausführen und Docker bereits vorhanden ist, wird Ihr System aktualisiert, ohne dass Probleme auftreten.

Fenster

winget install Docker.DockerDesktop

macOS

brew install --cask docker

Hinweis

Podman funktioniert auch, aber Setup variiert. Entwickler, die Podman bevorzugen, können diese Schritte anpassen.

3. Tools zum Erstellen von Aspire- und Daten-API

In diesem Schritt erstellen Sie die standardmäßigen Projektdateien von Aspire, die später verwendet werden.

Führen Sie die folgenden Befehle aus:

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

Hinweis

SQL MCP Server befindet sich derzeit in der Vorabversion. Durch die Verwendung des --prerelease Flags wird sichergestellt, dass Sie die neueste Version des Daten-API-Generators mit allen features erhalten, die in dieser Schnellstartanleitung verwendet werden.

Wenn Sie dazu aufgefordert werden, wählen Sie alle Standardwerte aus.

Mit diesem Befehl wird das Tool installiert und die folgenden Dateien erstellt.

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

4. Füllen Sie die AppHost.cs Datei aus.

In diesem Schritt aktualisieren Sie AppHost.cs mit dem richtigen Code, um diesen Quickstart durchzuführen.

Ersetzen Sie den Inhalt von AppHost.cs durch Folgendes:

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

Mit diesem Code werden die folgenden Ressourcen konfiguriert.

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

5. Erstellen Ihrer dab-config.json Datei

Führen Sie diese Befehle in Ihrem Projektordner aus (demselben Ordner, in dem AppHost.cs sich befindet).

Die @env('MSSQL_CONNECTION_STRING') Syntax weist den Daten-API-Generator an, die Verbindungszeichenfolge aus einer Umgebungsvariable zur Laufzeit zu lesen. Aspire legt diese Variable automatisch fest, wenn sie den Container startet, sodass Sie sie nicht lokal festlegen müssen.

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

Hinweis

Der @env(...) Ausdruck ist ein DAB-Konfigurationsfeature, das Umgebungsvariablen zur Laufzeit auflöst, nicht während dab init. Die generierte dab-config.json enthält die Literalzeichenfolge @env('MSSQL_CONNECTION_STRING'), die von DAB beim Start des Containers aufgelöst wird.

Die dab-config.json Datei konfiguriert SQL MCP Server für die Verbindung mit Ihrer Datenbank und identifiziert, welche Objekte verfügbar gemacht werden sollen. In diesem Fall wird Products verfügbar gemacht.

Mit diesem Befehl wird Ihrem Projekt eine neue Datei hinzugefügt.

dab-config.json

Von Bedeutung

Die dab-config.json Datei muss sich im selben Verzeichnis befinden, in dem Sie aspire run ausführen, da der Bind-Mount einen relativen Pfad (./dab-config.json) verwendet.

Optional können Sie Feldbeschreibungen hinzufügen.

Mit diesen Metadaten können Sprachmodelle Ihr Schema verstehen.

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"

Testen Ihrer Lösung

In diesem Schritt führen Sie Ihre Aspire-Umgebung aus und bestätigen, dass SQL Server, SQL MCP Server und MCP Inspector zusammenarbeiten.

1. Start Aspire

aspire run

Von Bedeutung

Stellen Sie sicher, dass Docker ausgeführt wird. Aspire erfordert, dass Ihr Containerhost ordnungsgemäß funktioniert.

Wenn das Dashboard geöffnet wird, werden Links für Swagger, MCP und Inspector angezeigt.

Erwartete URLs

Das Aspire-Dashboard zeigt diese Links an (Ports werden dynamisch zugewiesen):

Resource	Link	Description
sql-mcp-server	Swagger	REST-API-Dokumentation
sql-mcp-server	MCP	MCP-Endpunkt (/mcp)
Inspector	Inspector	MCP Inspector-Benutzeroberfläche

2. Testen der REST-API mit Swagger

Wählen Sie Swagger aus dem Dashboard aus.

Probieren Sie den GET Vorgang für Produkte aus. Dieser Test bestätigt, dass SQL MCP Server ausgeführt wird und eine Verbindung mit der Datenbank herstellen kann.

3. Entdecken Sie die MCP-Tools

Wählen Sie " Inspektor" aus dem Dashboard aus.

Try:

• list_tools um verfügbare MCP-Tools anzuzeigen
• read_records für die Products Entität

Versuchen Sie einen Filter (Beispielsyntax):

{ "filter": "Price gt 20" }

Dieser Test bestätigt, dass MCP funktioniert.

4. Aspire anhalten

Zum Beenden von Aspire drücken Sie Ctrl+C.

Aspire stoppt alle Dienste. SQL Server-Daten bleiben zwischen den Ausführungen bestehen, da der Code .WithDataVolume() und .WithLifetime(ContainerLifetime.Persistent) verwendet.

Problembehandlung

SQL MCP Server-Container kann nicht gestartet werden

• Überprüfen Sie die Containerprotokolle im Aspire-Dashboard auf Fehlerdetails.
• Überprüfen Sie, ob das --config-Argument mit der erwarteten Syntax des DAB-Containers übereinstimmt (bei einigen Versionen wird möglicherweise --ConfigFileName verwendet).
• Stellen Sie sicher, dass dab-config.json im selben Verzeichnis vorhanden ist, in dem Sie aspire run ausführen.

Datenbankinitialisierungsskript nicht gefunden

• Überprüfen Sie, ob sich init-db.sql im AppHost-Projektverzeichnis befindet
• Überprüfen Sie, ob die Datei im Projekt enthalten ist, und kopieren Sie sie in die Ausgabe, falls erforderlich.

MCP Inspector kann keine Verbindung herstellen

• Vergewissern Sie sich, dass der SQL MCP Server-Container ausgeführt und fehlerfrei ist.
• Überprüfen, ob der MCP-Endpunktpfad (/mcp) mit der DAB-Konfiguration übereinstimmt

Verwandte Inhalte

• Übersicht über SQL MCP Server
• Datenmanipulationstools in SQL MCP Server
• Hinzufügen von semantischen Beschreibungen zu SQL MCP Server