Démarrage rapide : Utiliser SQL MCP Server avec .NET Aspire

Important

SQL MCP Server est en préversion et cette documentation et l’implémentation du moteur est susceptible de changer pendant cette période d’évaluation.

Ce guide de démarrage rapide utilise Aspire pour créer une solution basée sur un conteneur. La solution inclut :

Une base de données SQL avec des exemples de données
Un serveur MCP (SQL Model Context Protocol) alimenté par le générateur d’API de données
Inspecteur MCP pour les tests

Aspire exécute tout pour vous, démarre les services, connecte des conteneurs, et arrête les services lorsque vous le fermez.

Prerequisites

Installez ces outils avant de commencer.

1. .NET 10

Dans cette étape, vous préparez votre ordinateur avec les prérequis requis pour ce didacticiel de démarrage rapide.

Important

Vous avez peut-être déjà installé cet outil. Testez-le en exécutant dotnet --version et confirmez qu’il signale la version 10 ou ultérieure. Si vous exécutez cette installation et que .NET est déjà présent, il actualise votre système sans provoquer de problèmes.

Fenêtres

winget install Microsoft.DotNet.SDK.10

Ou télécharger

https://get.dot.net

2. Runtime de conteneur

Dans cette étape, vous installez Docker Desktop pour prendre en charge le projet Aspire.

Important

Vous avez peut-être déjà installé cet outil. Testez-le en exécutant docker --version pour confirmer que Docker est disponible. Si vous exécutez cette installation et que Docker est déjà présent, il actualise votre système sans provoquer de problèmes.

Fenêtres

winget install Docker.DockerDesktop

macOS

brew install --cask docker

Note

Podman fonctionne également, mais la configuration varie. Les développeurs qui préfèrent Podman peuvent adapter ces étapes.

3. Outils Aspire et générateur d’API de données

Dans cette étape, vous créez les fichiers projet Aspire par défaut utilisés ultérieurement.

Exécutez les commandes suivantes

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

Note

SQL MCP Server est actuellement en préversion. L’utilisation de l’indicateur --prerelease vous permet d’obtenir la dernière version du générateur d’API de données avec toutes les fonctionnalités utilisées dans ce guide de démarrage rapide.

Lorsque vous y êtes invité, sélectionnez toutes les valeurs par défaut.

Cette commande installe les outils et crée les fichiers suivants

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

4. Terminez le fichier AppHost.cs

Dans cette étape, vous effectuez une mise à jour AppHost.cs avec le code approprié pour exécuter ce guide de démarrage rapide.

Remplacez le contenu de AppHost.cs par les éléments suivants :

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

Ce code configure les ressources suivantes

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

5. Créez votre fichier dab-config.json

Exécutez ces commandes dans votre dossier de projet (le même dossier où AppHost.cs se trouve).

La @env('MSSQL_CONNECTION_STRING') syntaxe indique au générateur d’API de données de lire la chaîne de connexion à partir d’une variable d’environnement au moment de l’exécution. Aspire définit automatiquement cette variable au démarrage du conteneur. Vous n’avez donc pas besoin de la définir localement.

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

Note

L’expression @env(...) est une fonctionnalité de configuration DAB qui résout les variables d’environnement au moment de l’exécution, et non pendant dab init. Le fichier généré contient la chaîne littérale dab-config.json, que DAB résout au moment où le conteneur démarre.

Le dab-config.json fichier configure SQL MCP Server pour se connecter à votre base de données et identifie les objets à exposer. Dans ce cas, Products est exposé.

Cette commande ajoute un nouveau fichier à votre projet

dab-config.json

Important

Le fichier dab-config.json doit se trouver dans le même répertoire où vous exécutez aspire run, car le montage par lien utilise un chemin relatif (./dab-config.json).

Si vous le souhaitez, ajoutez des descriptions de champ

Ces métadonnées peuvent aider les modèles de langage à comprendre votre schéma.

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"

Tester votre solution

Dans cette étape, vous exécutez votre environnement Aspire et vérifiez que SQL Server, SQL MCP Server et l’inspecteur MCP fonctionnent ensemble.

1. Démarrer Aspire

aspire run

Important

Vérifiez que Docker est en cours d’exécution. Aspire exige que votre hôte de conteneur fonctionne correctement.

Lorsque le tableau de bord s’ouvre, vous voyez des liens pour Swagger, MCP et Inspector.

URL attendues

Le tableau de bord Aspire affiche ces liens (les ports sont attribués dynamiquement) :

Resource	Lien	Descriptif
sql-mcp-server	Fichier Swagger	Documentation de l'API REST
sql-mcp-server	MCP	Point de terminaison MCP (`/mcp`)
Inspecteur	Inspector	Interface utilisateur de l’inspecteur MCP

2. Tester l’API REST avec Swagger

Sélectionnez Swagger dans le tableau de bord.

Essayez l’opération GET pour les produits. Ce test confirme que SQL MCP Server est en cours d’exécution et peut se connecter à la base de données.

3. Explorer les outils MCP

Sélectionnez Inspector dans le tableau de bord.

Try:

list_tools pour afficher les outils MCP disponibles
read_recordspour l’entité Products

Essayez un filtre (exemple de syntaxe) :

{ "filter": "Price gt 20" }

Ce test confirme que MCP fonctionne.

4. Arrêter Aspire

Pour arrêter Aspire, appuyez Ctrl+Csur .

Aspire arrête tous les services. Les données SQL Server persistent entre les exécutions, car le code utilise .WithDataVolume() et .WithLifetime(ContainerLifetime.Persistent).

Résolution des problèmes

Le conteneur SQL MCP Server ne parvient pas à démarrer

Pour plus d’informations sur les erreurs, consultez les journaux de conteneur dans le tableau de bord Aspire
Vérifiez que l’argument --config correspond à la syntaxe attendue du conteneur DAB (certaines versions peuvent être utilisées --ConfigFileName à la place)
Vérifiez dab-config.json qu’il existe dans le même répertoire que celui où vous exécutez aspire run

Script d’initialisation de base de données introuvable

Vérifiez que init-db.sql se trouve dans le répertoire du projet AppHost
Vérifiez que le fichier est inclus dans le projet et est copié dans la sortie si nécessaire.

L’inspecteur MCP ne peut pas se connecter

Vérifiez que le conteneur SQL MCP Server est en cours d’exécution et sain
Vérifiez que le chemin du point de terminaison MCP (/mcp) correspond à la configuration DAB

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-01-07

Partager via

Démarrage rapide : Utiliser SQL MCP Server avec .NET Aspire

Prerequisites

1. .NET 10

Fenêtres

Ou télécharger

2. Runtime de conteneur

Fenêtres

macOS

3. Outils Aspire et générateur d’API de données

Exécutez les commandes suivantes

Cette commande installe les outils et crée les fichiers suivants

4. Terminez le fichier AppHost.cs

Remplacez le contenu de AppHost.cs par les éléments suivants :

Ce code configure les ressources suivantes

5. Créez votre fichier dab-config.json

Cette commande ajoute un nouveau fichier à votre projet

Si vous le souhaitez, ajoutez des descriptions de champ

Tester votre solution

1. Démarrer Aspire

URL attendues

2. Tester l’API REST avec Swagger

3. Explorer les outils MCP

4. Arrêter Aspire

Résolution des problèmes

Le conteneur SQL MCP Server ne parvient pas à démarrer

Script d’initialisation de base de données introuvable

L’inspecteur MCP ne peut pas se connecter

Contenu connexe

Commentaires

Ressources supplémentaires