HsSqlAgent.Server
2.0.2
See the version list below for details.
dotnet add package HsSqlAgent.Server --version 2.0.2
NuGet\Install-Package HsSqlAgent.Server -Version 2.0.2
<PackageReference Include="HsSqlAgent.Server" Version="2.0.2" />
<PackageVersion Include="HsSqlAgent.Server" Version="2.0.2" />
<PackageReference Include="HsSqlAgent.Server" />
paket add HsSqlAgent.Server --version 2.0.2
#r "nuget: HsSqlAgent.Server, 2.0.2"
#:package HsSqlAgent.Server@2.0.2
#addin nuget:?package=HsSqlAgent.Server&version=2.0.2
#tool nuget:?package=HsSqlAgent.Server&version=2.0.2
HsSqlAgent.Server
Embeddable MCP SQL Agent components for ASP.NET Core. New applications compose capabilities explicitly; each capability owns only the options it needs. The aggregate AddHsSqlAgent() / UseHsSqlAgent() pair remains as a compatibility path for existing consumers.
Install
dotnet add package HsSqlAgent.Server
Choose the composition you need
| Host scenario | Registration |
|---|---|
| Existing app with its own login/permissions | Runtime + AdminStore + HostAuthorization + AdminApi |
| Existing app that also exposes MCP | Add MCP to the host-auth composition |
| Standalone HsSqlAgent identity/Admin experience | Runtime + AdminStore + BuiltInAuth + AdminApi, optionally MCP/Telemetry/UI |
| Existing consumer using the old aggregate API | AddHsSqlAgent(...) / UseHsSqlAgent() compatibility preset |
AddHsSqlAgentCore() itself is optionless and does not install optional capabilities.
HTTP surfaces
The current public HTTP contracts are intentionally fixed:
- MCP:
/mcp - administration API:
/api - administration UI:
/
Canonical permission paths such as /auth/role and /runtime/db-management are authorization resource identifiers, not HTTP mount paths. Changing a page or API URL must not silently change its permission identity.
Existing ASP.NET Core host with its own login and permissions
A host can omit the HsSqlAgent frontend and built-in identity entirely. The host keeps ownership of authentication, authorization, exception handling, telemetry, and controller endpoint mapping.
using HsSqlAgent.Server.Extensions;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication(/* host schemes */);
builder.Services.AddAuthorization(options =>
{
options.AddPolicy("SqlAgentAdmin", policy =>
{
// Add the host application's own requirement/handler here.
// The handler can inspect HsSqlAgentPermissionResource.Permissions.
});
});
var hs = builder.Services.AddHsSqlAgentCore();
hs.AddHsSqlAgentRuntime();
hs.AddHsSqlAgentAdminStore(options =>
{
options.Provider = "Postgres";
options.ConnectionString = builder.Configuration.GetConnectionString("HsSqlAgent")!;
});
hs.AddHsSqlAgentHostAuthorization("SqlAgentAdmin");
hs.AddHsSqlAgentAdminApi();
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.UseHsSqlAgentAdminApi();
app.MapControllers();
app.Run();
In host-authorization mode HsSqlAgent:
- does not publish
AuthController,MemberController, orRoleController; - does not install the HsSqlAgent identity schema;
- does not require JWT, SMTP, password-reset, or OIDC settings;
- does not install an
/api-wide HsSqlAgent authentication/authorization middleware branch; - delegates canonical permission checks to the host policy as
HsSqlAgentPermissionResource; - leaves the host's authentication defaults, authorization policy provider, MVC JSON options, exception handling, telemetry, and controller mapping under host ownership.
Add MCP independently
MCP machine access is a separate security boundary from human/admin authorization. Add it only when the host needs an MCP endpoint:
hs.AddHsSqlAgentMcp(options =>
{
options.PublicEndpoint = "https://example.com/mcp";
options.HmacSecretKey = builder.Configuration["HMAC_KEY"]!; // at least 32 bytes
});
// after builder.Build()
app.UseHsSqlAgentMcp();
If AddHsSqlAgentMcp() is not selected, MCP options and MCP services are not installed.
Standalone server / packaged Admin experience
The first-party ToolBox uses the same modular registration surface as package consumers. It explicitly selects runtime, persistence, built-in identity, MCP, administration API, telemetry, controller mapping, UI, and host-wide exception handling.
using HsSqlAgent.Server.Extensions;
using HsSqlAgent.Server.Middleware;
var builder = WebApplication.CreateBuilder(args);
var hs = builder.Services.AddHsSqlAgentCore();
hs.AddHsSqlAgentRuntime();
hs.AddHsSqlAgentAdminStore(options =>
{
options.Provider = "Sqlite";
options.ConnectionString = "Data Source=hsagent.db";
});
hs.AddHsSqlAgentBuiltInAuth(options =>
{
options.Jwt.SecretKey = builder.Configuration["JWT_KEY"]!; // at least 32 bytes
});
hs.AddHsSqlAgentMcp(options =>
{
options.PublicEndpoint = "http://localhost:8080/mcp";
options.HmacSecretKey = builder.Configuration["HMAC_KEY"]!; // at least 32 bytes
});
hs.AddHsSqlAgentAdminApi();
hs.AddHsSqlAgentTelemetry();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddProblemDetails();
var app = builder.Build();
app.UseExceptionHandler();
app.UseHsSqlAgentMcp();
app.UseHsSqlAgentAdminApi();
app.MapControllers();
app.UseHsSqlAgentAdminUi();
app.Run();
Built-in schemes are namespaced (HsSqlAgent.Jwt, HsSqlAgent.ExternalCookie, HsSqlAgent.Oidc) and do not replace the host application's default authentication schemes or default authorization policy. Built-in identity and host-authorization mode are mutually exclusive.
Capability ownership
New code configures the capability that owns a setting:
| Capability | Options / responsibility |
|---|---|
AddHsSqlAgentRuntime() |
HsSqlAgentRuntimeOptions: bootstrap, operability, cache, rate limiting, security-policy sync, outbound-delivery sync, SQL concurrency, DML approval store |
AddHsSqlAgentAdminStore() |
HsSqlAgentAdminStoreOptions: administration DB provider and connection string |
AddHsSqlAgentBuiltInAuth() |
HsSqlAgentBuiltInAuthOptions: JWT, password reset/SMTP, enterprise identity/OIDC |
AddHsSqlAgentHostAuthorization() |
Delegate administration permission checks to an existing ASP.NET Core policy |
AddHsSqlAgentMcp() |
McpOptions: public MCP endpoint and MCP-key HMAC secret |
AddHsSqlAgentAdminApi() |
HsSqlAgent controllers plus controller-scoped validation and exception mapping |
AddHsSqlAgentTelemetry() |
TelemetryOptions: Prometheus and OTLP exporters |
Dependencies are composed automatically where required. For example, AdminStore ensures Runtime is present; BuiltInAuth ensures AdminStore is present. This does not mean unrelated capabilities are installed.
Defaults and compatibility
Capability defaults preserve the previous aggregate defaults. Omitting a capability does not allocate or validate that capability's options.
Notable preserved defaults:
| Setting | Default |
|---|---|
| Admin database provider | Sqlite |
| Admin database connection | Data Source=hsagent.db |
| MCP public endpoint | http://localhost:8080/mcp |
| Cache provider | Memory |
| Rate limiter provider / failure mode | Memory / FailClosed |
| Security-policy sync provider | Memory |
| Outbound-delivery sync provider | Memory |
| SQL concurrency provider / failure mode | Memory / FailClosed |
| SQL concurrency lease | 30 seconds |
| DML approval store provider | Memory |
| JWT issuer / audience | HS-Agent / HS-Agent-Users |
| Access / refresh token lifetime | 1 minute / 30 days |
| Sign-in lockout | 5 attempts / 15 minutes |
| Password reset expiration | 30 minutes |
| SMTP port / SSL | 587 / enabled |
| Prometheus | enabled on localhost:9000 |
| Telemetry service name | hs-sql-agent |
| Health probe | enabled, 60s interval, 10s timeout, max concurrency 4 |
| Security-policy refresh | 30 seconds |
Secret values intentionally default to empty strings. They are validated only when their owning capability is selected: BuiltInAuth requires a JWT secret of at least 32 bytes; MCP requires an HMAC secret of at least 32 bytes.
The existing key prefixes are also preserved, including:
hsqlagent:cache:
hsqlagent:ratelimit:
hsqlagent:security-policy:
hsqlagent:outbound-delivery:
hsqlagent:sql-concurrency
hsqlagent:dml-approval:
The first-party ToolBox also preserves the existing configuration fallback chains for distributed runtime connection strings; splitting the options model does not change those deployment semantics.
Regression tests compare the complete legacy-default capability option trees against modular defaults so future refactors cannot silently drift these defaults.
Legacy compatibility preset
Existing package consumers can continue to use the aggregate options shape:
builder.Services.AddHsSqlAgent(options =>
{
options.AdminDatabaseProvider = "Sqlite";
options.AdminConnectionString = "Data Source=hsagent.db";
options.JwtSecretKey = builder.Configuration["JWT_KEY"]!;
options.HmacSecretKey = builder.Configuration["HMAC_KEY"]!;
});
var app = builder.Build();
app.UseExceptionHandler();
app.UseHsSqlAgent().ServeAdminUi();
HsSqlAgentServiceOptions is retained as a compatibility DTO. The compatibility registration translates it into the same capability-specific option objects used by new integrations. New code should prefer AddHsSqlAgentCore() plus explicit capability registration.
Canonical permissions
The frontend and backend use stable canonical permission identities. Examples:
/auth/role.view
/auth/role.edit
/auth/user.create
/runtime/db-management.view
/runtime/db-management/semantic.edit
/runtime/mcp-keys.create
Frontend navigation paths are separate from these identifiers. Relative UI checks such as v-permission="'edit'" resolve from the page's declared canonical permission metadata, never from route.path.
Host authorization handlers receive the requested canonical permission keys through HsSqlAgentPermissionResource.Permissions and can map them into the host application's own authorization model.
MVC and pipeline ownership
UseHsSqlAgentAdminApi() initializes the HsSqlAgent administration surface but deliberately does not call MapControllers() in modular host mode. ASP.NET Core MapControllers() enables attribute-routed controllers for the MVC application as a whole, so the host must own that decision.
HsSqlAgent validation and exception mapping are attached only to HsSqlAgent controllers. The modular Admin API does not globally install FluentValidation auto-validation, HsSqlAgent ProblemDetails, global JSON converters, or a host-wide HsSqlAgent exception handler.
The packaged Admin UI is optional and currently mounts only at /:
app.UseHsSqlAgentAdminUi();
Arbitrary relocation of /mcp, /api, or the SPA is intentionally rejected until routing, frontend base paths, assets, and security boundaries can move together.
Package contents
The Server package currently brings in HsSqlAgent.SqlCore, provider abstractions, and all six supported providers: PostgreSQL, MySQL, SQLite, SQL Server, Oracle, and Firebird. Provider package decomposition is separate from the server embedding contract and may be refined independently.
Compiler observability
HsSqlAgent.SqlCore remains telemetry-provider agnostic and returns deterministic SqlCompileEvidence with each translated or rejected compile decision. When AddHsSqlAgentTelemetry() is selected, the Server package observes that evidence at the runtime boundary:
- structured
ILoggerevents contain verdict, decision boundary/code, source/target provider, capability-matrix version and evidence fingerprint; - when
OtlpEndpointis configured, those logs andsql.compile.decisiontrace spans are exported through OTLP; hsqlagent.sql.compilesis emitted through the existing OpenTelemetry meter and Prometheus exporter with low-cardinality verdict/boundary/decision/provider labels.
Raw SQL, runtime literal/parameter values, full evidence objects, allowed-table snapshots, evidence fingerprints and trace IDs are not used as Prometheus labels. The database-backed AuditLog remains the durable governance/audit store rather than a general compiler telemetry store.
Do not commit production keys. Supply HMAC/JWT keys and database credentials through your deployment secret store.
Full project documentation: https://github.com/tse-wei-chen/hs-sql-agent
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- BCrypt.Net-Next (>= 4.0.3)
- dapper (>= 2.1.79)
- FirebirdSql.Data.FirebirdClient (>= 10.3.4)
- FluentValidation.AspNetCore (>= 11.3.1)
- FSharp.Core (>= 10.1.201)
- HsSqlAgent.Provider.Abstractions (>= 2.0.2)
- HsSqlAgent.Provider.Firebird (>= 2.0.2)
- HsSqlAgent.Provider.MySql (>= 2.0.2)
- HsSqlAgent.Provider.Oracle (>= 2.0.2)
- HsSqlAgent.Provider.PostgreSql (>= 2.0.2)
- HsSqlAgent.Provider.Sqlite (>= 2.0.2)
- HsSqlAgent.Provider.SqlServer (>= 2.0.2)
- HsSqlAgent.SqlCore (>= 2.0.2)
- Humanizer.Core (>= 3.0.10)
- Microsoft.AspNetCore.Authentication.JwtBearer (>= 10.0.9)
- Microsoft.AspNetCore.Authentication.OpenIdConnect (>= 10.0.9)
- Microsoft.Data.SqlClient (>= 7.0.2)
- Microsoft.Data.Sqlite (>= 10.0.9)
- Microsoft.EntityFrameworkCore (>= 10.0.9)
- Microsoft.EntityFrameworkCore.Relational (>= 10.0.9)
- Microsoft.EntityFrameworkCore.Sqlite (>= 10.0.9)
- Microsoft.Extensions.Caching.StackExchangeRedis (>= 10.0.9)
- Microsoft.Extensions.FileProviders.Embedded (>= 10.0.9)
- ModelContextProtocol (>= 1.4.0)
- ModelContextProtocol.AspNetCore (>= 1.4.0)
- MySql.Data (>= 9.7.0)
- Npgsql (>= 10.0.3)
- Npgsql.EntityFrameworkCore.PostgreSQL (>= 10.0.0)
- OpenTelemetry.Exporter.OpenTelemetryProtocol (>= 1.17.0)
- OpenTelemetry.Exporter.Prometheus.HttpListener (>= 1.17.0-beta.1)
- OpenTelemetry.Extensions.Hosting (>= 1.17.0)
- Oracle.ManagedDataAccess.Core (>= 23.26.200)
- SQLitePCLRaw.lib.e_sqlite3 (>= 3.50.3)
- StackExchange.Redis (>= 2.7.27)
- System.IdentityModel.Tokens.Jwt (>= 8.19.1)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on HsSqlAgent.Server:
| Package | Downloads |
|---|---|
|
HsSqlAgent.Hosting
Official batteries-included ASP.NET Core composition for HsSqlAgent, matching the standalone Docker host. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 3.1.0 | 68 | 11/14/2026 |
| 3.0.0 | 337 | 10/25/2026 |
| 2.0.6 | 87 | 10/18/2026 |
| 2.0.5 | 129 | 9/8/2026 |
| 2.0.4 | 117 | 9/7/2026 |
| 2.0.3 | 116 | 9/5/2026 |
| 2.0.2 | 95 | 9/4/2026 |
| 2.0.1 | 103 | 9/3/2026 |
| 2.0.0 | 97 | 9/2/2026 |
| 1.10.10 | 102 | 8/25/2026 |
| 1.10.9 | 103 | 8/24/2026 |
| 1.10.8 | 109 | 8/23/2026 |
| 1.10.7 | 104 | 8/18/2026 |
| 1.10.6 | 103 | 8/14/2026 |
| 1.10.5 | 102 | 8/14/2026 |
| 1.10.4 | 98 | 8/11/2026 |
| 1.10.3 | 394 | 8/1/2026 |
| 1.10.2 | 149 | 7/7/2026 |
| 1.10.1 | 139 | 7/7/2026 |
| 1.10.0 | 145 | 7/4/2026 |