跳至主要內容
翻譯頁面

本頁面由英文在 AI 協助下翻譯而成。若兩者有出入,請以英文版本為準。

StackQL MCP 架構

StackQL 的 MCP 伺服器內建於引擎二進位檔中,將 StackQL 的功能介面(探索、描述、驗證、執行)公開為 Model Context Protocol 工具。其設計以三件事為核心:以少量通用工具取代每個作業各一個工具、針對變更的分級安全契約,以及記錄代理程式一切行為的稽核軌跡。

傳輸方式與部署模式​

模式命令用途
stdiostackql mcp --mcp.server.type=stdio直接啟動處理程序、內嵌於編輯器的用戶端(Claude Desktop、Cursor、Continue)
HTTP(獨立)stackql mcp --mcp.server.type=http供獨立代理程式使用的長時間執行伺服器
雙伺服器、記憶體內stackql srv --mcp.server.type=http --pgsrv.port <port>由單一處理程序提供 MCP 與 PostgreSQL 線路協定
反向代理stackql srv --mcp.server.type=reverse_proxyMCP 要求透過 DSN 分派到後端的 StackQL Postgres 伺服器;支援工作負載分離與 TLS

設定是透過 --mcp.config 傳入的 JSON(或 YAML)物件,涵蓋傳輸方式、位址、TLS 憑證路徑、用戶端驗證、模式、稽核設定,以及選用的 enabled_tools / enabled_prompts 允許清單,用來公開範圍縮小的介面(例如只公開 server_info 與 list_providers 的唯讀資源清單伺服器)。從 v0.12.742 起,HTTP 傳輸方式需要預先共用的 bearer 權杖(server.auth_token_env_var),或明確選擇加入 server.allow_unauthenticated;跨來源的瀏覽器要求會遭到拒絕。

工具介面​

共有十五個工具,每個工具都會傳回供 LLM 使用的轉譯文字檢視,以及具型別的結構化承載:

  • 探索:list_providers、list_services、list_resources、list_methods、describe_method,逐層走訪階層,在撰寫任何查詢之前就揭示必要的 WHERE 參數。
  • 登錄庫:list_registry(可用的 Provider 與版本)、pull_provider(安裝到本機快取)。
  • 驗證:validate_select_query,剖析並規劃 SELECT 而不執行。
  • Query Library:query_library_search(依意圖、Provider、服務與標籤尋找精選的查詢範本)、query_library_get(驗證參數並傳回轉譯後的 SQL,但不執行)。
  • 執行:run_select_query(讀取)、run_mutation_query(INSERT/UPDATE/REPLACE/DELETE,會產生實際的副作用)、run_lifecycle_operation(EXEC)。
  • 身分:server_info,提供版本、後端、登錄庫、模式;在需要時呼叫(用於診斷遭拒絕或受管控的作業,或檢查特定版本的行為),而不是在工作階段開始時呼叫。
  • 憑證:reload_credentials,在工作階段進行中將 --env.file dotenv 檔案重新載入處理程序環境,並回報各 Provider 的憑證解析狀態;只包含名稱與狀態,絕不包含祕密值(於 v0.10.542 之後的發行版本提供)。

另有一個靜態提示詞 write_safe_select,用來教導方法探索的工作流程。

安全契約​

server.mode 會選取四種契約之一;所有契約都允許 SELECT 與中繼資料,差異在於寫入:

模式INSERT / UPDATE / REPLACEDELETEEXEC
read_only拒絕拒絕拒絕
safe(預設)需要核准需要核准需要核准
delete_safe允許需要核准需要核准
full_access允許允許允許

「需要核准」是以 MCP 徵詢(elicitation)實作:伺服器將待處理的動作(工具、查詢類別、SQL)傳送給用戶端,由人員接受或拒絕。未宣告徵詢功能的用戶端會收到拒絕,並指引維運人員改用 full_access,這讓無人值守的變更成為明確的選擇加入,而不是預設行為。模式是每部伺服器的全域設定;沒有個別工具的覆寫。包含多個陳述式的承載會由其中權限最高的陳述式管控(自 v0.12.742 起),而 validate_select_query 只接受一個陳述式。

稽核子系統​

每次工具呼叫都會將一筆 JSONL 記錄寫入檔案接收端,並依大小、存留時間與備份份數輪替。記錄內容包括時間戳記、工具、模式、決策(allow、refuse_immediate、needs_approval_accepted 等)、查詢類別、SQL、引數、持續時間與錯誤。記錄回答的是「代理程式做了什麼」,刻意不回答「代理程式看到了什麼」:SELECT 結果資料列可能龐大且敏感,因此不予記錄。寫入發生在執行之後、回應傳回之前;在預設的 strict 失敗模式下,成功的變更若稽核失敗,會向用戶端傳回錯誤,這是刻意的選擇,確保沒有任何 DELETE 會在未經稽核的情況下完成。