hs-sql-agent
2.0.2
文件 2.0.2
文件版本
2.0.2 最新
2.0.2 最新
文件 管理

Admin Panel 概覽

管理 database access、MCP credentials、identity、authorization、audit、security policy 與 runtime operations 的 operator control plane。

Admin Panel 是 hs-sql-agent 的 operator control plane。Operator 在這裡定義 MCP client 能碰到什麼，以及 SQL 要經過哪些治理；MCP client 則透過另一套 authentication 使用 /mcp endpoint。

Database Management 註冊 provider connection、測試 connectivity，並決定 MCP key 可以綁定哪個 database。
MCP Keys Issue、rotate、revoke、scope MCP credentials，並產生 client configuration。
Semantic Metadata 替 schema discovery 加上 human-readable names、descriptions、synonyms、relationships 與 metrics。
Custom Tools 把受治理的 SQL operations publish 成具名 MCP tools，而不繞過 runtime policy。
Security 理解 authentication、authorization、table/tool scope、fail-closed SQL policy 與 audit boundaries。
Operations 設定 deployment、shared state、observability、retention、limits 與 production runtime behavior。

Identity、治理與維運

Members 與 Roles 建立 Admin members、指派 roles、撤銷 sessions，並安全管理 role lifecycle。
Permissions 理解 Admin controllers 真正執行的 permission-path + action model。
Audit 搜尋、彙總、匯出並執行 runtime/security audit retention。
Security Policies 管理 query、DML、per-key rate limit 與 SQL concurrency enforcement。
Operability 檢視 execution metrics、DB health、key usage 與 outbound delivery state。
Admin HTTP API Bundled UI 使用的 2.0.2 source-backed controller routes 與 authorization surface。

建議的 operator flow

01 註冊 database
02 Issue MCP key
03 設定 tool/table scope
04 補 semantic metadata
05 連接 client
06 Observe & audit
  1. 註冊並驗證 agent 要 expose 的 database connection。
  2. Issue 一把綁定該 database 的 MCP key，只允許 client 真正需要的 tools/tables。
  3. 當 raw schema names 不足以讓 agent 穩定理解資料時，再補 semantic metadata。
  4. 產生 client configuration，透過 public Streamable HTTP /mcp endpoint 連線。
  5. 使用 audit 與 operability surface 檢視 runtime behavior，必要時再收緊 policy。

MCP key lifecycle

Key 在 issue、rotate 或 duplicate 時，UI 可以產生 supported client formats 的 direct Streamable HTTP configuration。Plaintext secret 只會在該 lifecycle dialog 顯示，不會保留成之後可再次查看的值。

關閉 dialog 前請先複製需要的 configuration。

Embedded UI 與 built-in identity 都是 optional

ASP.NET Core host 可以只 expose HsSqlAgent Admin API，不提供 packaged Admin UI。Modular integration 使用 UseHsSqlAgentAdminApi()，並由 host 自己呼叫 MapControllers()；只有需要 packaged UI 時才加 UseHsSqlAgentAdminUi()。

Host 也可以用 AddHsSqlAgentHostAuthorization(...) 沿用自己既有的 login / permission system，而不安裝 HsSqlAgent members、roles、JWT、SMTP 或 OIDC。MCP 則用 AddHsSqlAgentMcp(...) / UseHsSqlAgentMcp() 獨立選擇與掛載。

完整 2.0.2 composition model 請參考 ASP.NET Core 整合。