중요합니다
MCP(SQL 모델 컨텍스트 프로토콜) 서버는 미리 보기 상태이며 이 설명서와 엔진 구현이 변경 될 수 있습니다. Data API Builder 버전 1.7은 미리 보기 상태이지만 MCP 기능이 태그에 아직 포함되지 1.7.83-rc 않았기 때문에 시험판 버전을 명시적으로 사용해야 합니다(예:latest: ).
이 빠른 시작에서는 Aspire를 사용하여 컨테이너 기반 솔루션을 빌드합니다. 솔루션에는 다음이 포함됩니다.
- 샘플 데이터가 있는 SQL 데이터베이스
- 데이터 API 작성기에서 제공하는 SQL MCP(모델 컨텍스트 프로토콜) 서버
- 테스트를 위한 MCP 검사기
Aspire는 모든 것을 실행하고, 서비스를 시작하고, 컨테이너를 연결하고, 닫을 때 서비스를 중지합니다.
필수 조건
시작하기 전에 이러한 도구를 설치합니다.
1. .NET 10
이 단계에서는 이 빠른 시작에 필요한 필수 구성 요소를 사용하여 컴퓨터를 준비합니다.
중요합니다
이 도구가 이미 설치되어 있을 수 있습니다.
dotnet --version를 실행하여 테스트하고 버전 10 이상임을 보고하는지 확인합니다. 이 설치를 실행하고 .NET이 이미 있는 경우 문제를 일으키지 않고 시스템을 새로 고칩니다.
2. 컨테이너 런타임
이 단계에서는 Aspire 프로젝트를 지원하기 위해 Docker Desktop을 설치합니다.
중요합니다
이 도구가 이미 설치되어 있을 수 있습니다. 실행 docker --version 하여 테스트하여 Docker를 사용할 수 있는지 확인합니다. 이 설치를 실행하고 Docker가 이미 있는 경우 문제를 일으키지 않고 시스템을 새로 고칩니다.
비고
Podman도 작동하지만 설정은 다릅니다. Podman을 선호하는 개발자는 이러한 단계를 조정할 수 있습니다.
3. Aspire 및 데이터 API 작성기 도구
이 단계에서는 나중에 사용되는 기본 Aspire 프로젝트 파일을 만듭니다. 다음 명령어를 실행하세요:
dotnet new tool-manifest
dotnet tool install aspire.cli
dotnet tool install microsoft.dataapibuilder --prerelease
aspire init
비고
SQL MCP Server는 현재 시험판에 있습니다. 플래그를 --prerelease 사용하면 이 빠른 시작에 사용된 모든 기능을 사용하여 최신 버전의 Data API 작성기를 얻을 수 있습니다.
메시지가 표시되면 모든 기본값을 선택합니다.
이 명령은 도구를 설치하고 다음 파일을 만듭니다.
.
├── .config
│ └── dotnet-tools.json
├── AppHost.cs
└── apphost.run.json
4. AppHost.cs 파일 완료
이 단계에서는 AppHost.cs를 올바른 코드로 업데이트하여 이 Quickstart를 실행합니다.
AppHost.cs의 내용을 다음으로 바꿉니다.
#: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);
""";
이 코드는 다음 리소스를 구성합니다.
.
├── SQL Server (sql)
│ └── SQL Database (productsdb)
└── SQL MCP Server (sql-mcp-server)
└── MCP Inspector (inspector)
5. dab-config.json 파일 만들기
프로젝트 폴더(있는 AppHost.cs 동일한 폴더)에서 다음 명령을 실행합니다.
이 구문은 @env('MSSQL_CONNECTION_STRING') 데이터 API 작성기에게 런타임 시 환경 변수에서 연결 문자열을 읽도록 지시합니다. Aspire는 컨테이너를 시작할 때 이 변수를 자동으로 설정하므로 로컬로 설정할 필요가 없습니다.
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."
비고
식은 환경 변수를 @env(...)에서 런타임 시 해결하는 DAB 구성 기능으로, dab init 동안에는 그렇게 하지 않습니다. 생성된 dab-config.json 문자열에는 컨테이너가 시작될 때 DAB가 확인하는 리터럴 문자열 @env('MSSQL_CONNECTION_STRING')이 포함됩니다.
이 파일은 dab-config.json 데이터베이스에 연결하도록 SQL MCP Server를 구성하고 노출할 개체를 식별합니다. 이 경우 Products 노출됩니다.
이 명령은 프로젝트에 새 파일을 추가합니다.
dab-config.json
중요합니다
바인딩 탑재는 상대 경로(dab-config.json)를 사용하므로 aspire run 파일은 ./dab-config.json을 실행하는 동일한 디렉터리에 있어야 합니다.
필요에 따라 필드 설명을 추가합니다. 이 메타데이터는 언어 모델이 스키마를 이해하는 데 도움이 될 수 있습니다.
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"
솔루션 테스트
이 단계에서는 Aspire 환경을 실행하고 SQL Server, SQL MCP Server 및 MCP 검사기에서 함께 작동하는지 확인합니다.
1. Aspire 시작
aspire run
중요합니다
Docker가 실행 중인지 확인합니다. Aspire에는 컨테이너 호스트가 올바르게 작동해야 합니다.
대시보드가 열리면 Swagger, MCP 및 Inspector에 대한 링크가 표시됩니다.
예상 URL
Aspire 대시보드에는 이러한 링크가 표시됩니다(포트는 동적으로 할당됨).
| Resource | Link | Description |
|---|---|---|
| sql-mcp-server | Swagger | REST API 설명서 |
| sql-mcp-server | MCP | MCP 엔드포인트(/mcp) |
| 경위 | 검사자 | MCP 검사기 UI |
2. Swagger를 사용하여 REST API 테스트
대시보드에서 Swagger 를 선택합니다.
제품에 GET 작업을 시도해 보세요. 이 테스트는 SQL MCP Server가 실행 중이며 데이터베이스에 연결할 수 있는지 확인합니다.
3. MCP 도구 살펴보기
대시보드에서 검사 기를 선택합니다.
Try:
-
list_tools사용 가능한 MCP 도구를 보려면 -
read_records엔터티의Products경우
필터(예제 구문)를 사용해 보세요.
{ "filter": "Price gt 20" }
이 테스트는 MCP가 작동하는지 확인합니다.
4. 열망 중지
Aspire를 중지하려면 Ctrl+C 키를 누릅니다.
Aspire는 모든 서비스를 중단합니다. SQL Server 데이터는 .WithDataVolume()와 .WithLifetime(ContainerLifetime.Persistent)를 코드에서 사용하기 때문에 실행 사이에 유지됩니다.
Troubleshooting
SQL MCP Server 컨테이너를 시작하지 못함
- Aspire 대시보드에서 컨테이너 로그에서 오류 세부 정보를 확인합니다.
- 인수가
--configDAB 컨테이너의 예상 구문과 일치하는지 확인합니다(일부 버전에서 대신 사용할--ConfigFileName수 있음). - 동일한 디렉터리에서
dab-config.json을 실행할 때aspire run이(가) 존재하는지 확인합니다.
데이터베이스 초기화 스크립트를 찾을 수 없음
- AppHost 프로젝트 디렉터리에 있는지 확인
init-db.sql - 파일이 프로젝트에 포함되어 있는지 확인하고 필요한 경우 출력에 복사합니다.
MCP 검사기에서 연결할 수 없음
- SQL MCP Server 컨테이너가 실행 중이고 정상인지 확인
- MCP 엔드포인트 경로(
/mcp)가 DAB 구성과 일치하는지 확인합니다.