クイックスタート

必須のシークレット保護設定

Docker の起動またはランタイム登録の前に、互いに独立したランダムな 32 バイトの Base64 シークレットを 3 個設定してください。すべてのノードで同じキーを使い、再起動後も保持します。HMAC_KEY と JWT_KEY は別の署名シークレットです。openssl rand -base64 32 を個別に 3 回実行してください。

Docker 環境変数	ASP.NET Core 設定
`DB_ENCRYPTION_KEY`	`SecretProtection:DatabasePasswords:Keys:db-1`
`DML_ENCRYPTION_KEY`	`SecretProtection:DmlPayloads:Keys:dml-1`
`DML_FINGERPRINT_KEY`	`SecretProtection:DmlFingerprintKey`

SecretProtection:DatabasePasswords:ActiveKeyId を db-1、SecretProtection:DmlPayloads:ActiveKeyId を dml-1 に設定します。キーの欠落、不正な値、使い回しは起動エラーになります。サンプルのプレースホルダーは意図的に無効です。

HsSqlAgent.Hosting は SecretProtection を自動的にバインドします。モジュール構成のホストでは明示的にバインドします。

hs.AddHsSqlAgentRuntime(options =>
{
    builder.Configuration.GetSection("SecretProtection").Bind(options.SecretProtection);
});

新規 bootstrap MCP キーには Bootstrap:Databases:*:McpKeys:*:Key を明示してください。起動時にキーを生成したりログに記録したりしません。既存の暗号化された DB パスワードは再入力が必要です。既存環境を変更する前にアップグレードガイドを確認してください。

Host を誰が所有するかに合わせて利用形態を選びます。

方式	適している場合
Docker	hs-sql-agent を独立サービスとして動かす
`HsSqlAgent.Hosting`	.NET Host に完全な第一方製品を組み込む
`HsSqlAgent.Server`	既存 ASP.NET Core アプリで構成をカスタマイズする

単独デプロイ: Docker Compose

cp .env.example .env
docker compose up -d

HMAC_KEY と JWT_KEY は、それぞれ異なる 32 bytes 以上の secrets に置き換えてください。既定のアプリケーション Port は 8080、MCP endpoint は /mcp です。

外部 MCP Client から使う場合、MCP_PUBLIC_ENDPOINT は Client から到達できる絶対 URL にし、/mcp まで含めます。

完全な製品を組み込む: HsSqlAgent.Hosting

dotnet add package HsSqlAgent.Hosting

using HsSqlAgent.Hosting;

var builder = WebApplication.CreateBuilder(args);
builder.AddHsSqlAgentStandardHost();

var app = builder.Build();
app.UseHsSqlAgentStandardHost();
await app.RunAsync();

Docker と同じ標準の第一方 Capability 構成と DML 承認 Provider の設定契約を利用します。

カスタム ASP.NET Core 統合: HsSqlAgent.Server

HsSqlAgent.Server を導入し、AddHsSqlAgentCore() の後に Runtime、Admin Store/API、MCP、Identity、Telemetry、承認 Capability を必要な分だけ追加します。ASP.NET Core 統合を参照してください。

MCP Key を発行する

Admin UI で MCP Key を作成し、1 つの管理対象 Database に紐付け、Client に必要な Tools と Tables だけ公開します。生成された Client 設定を使うか、Streamable HTTP endpoint に X-MCP-Server-Key を送ります。

DML 承認

第一方の既定は MCP Elicitation です。標準 Hosting は設定で公式 Webhook adapter を選択でき、カスタム Server Host は HsSqlAgent.Approvals.Webhook または独自の IDmlApprovalProvider を登録できます。

batch 専用 DML Tool は追加しません。既存の execute_dml_sql が、セミコロンで区切った複数の対応 DML を受け取り、承認後に単一 Transaction で原子的に commit します。