本頁面由英文在 AI 協助下翻譯而成。若兩者有出入,請以英文版本為準。
如何搭配 AI 代理程式使用 StackQL
StackQL 內建 Model Context Protocol(MCP)伺服器。任何支援 MCP 的代理程式(Claude、Cursor、Continue 或自訂代理程式架構)都能連線到此伺服器,取得一個可自我描述且受管控的 SQL 介面,存取 StackQL 登錄庫中的每個雲端與 SaaS Provider。
步驟
- 設定 Provider 憑證,在啟動伺服器之前將其設為環境變數(伺服器會繼承這些變數):
export AWS_ACCESS_KEY_ID=YOURACCESSKEYID
export AWS_SECRET_ACCESS_KEY=YOURSECRETACCESSKEY
或者(在 v0.10.542 之後的 StackQL 發行版本中),使用 --env.file 指定 dotenv 格式的憑證檔案;reload_credentials MCP 工具會在工作階段中途重新讀取該檔案,讓輪替後的憑證無須重新啟動即可送達執行中的伺服器。
- 啟動 MCP 伺服器。若要執行獨立的 HTTP 伺服器:
stackql mcp \
--mcp.server.type=http \
--mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true}}'
從 v0.12.742 起,HTTP 傳輸方式需要 server.auth_token_env_var(存放預先共用 bearer 權杖的環境變數,每個要求都必須攜帶此權杖),或如此處所示明確選擇加入 allow_unauthenticated,否則伺服器會拒絕啟動;凡是其他處理程序或主機可以連線的接聽程式,都應使用權杖。stdio 不受影響。
對於內嵌於編輯器的用戶端,請使用 --mcp.server.type=stdio,並讓用戶端啟動處理程序(請參閱如何搭配 Claude 使用 StackQL)。若要從單一處理程序同時提供 MCP 與 PostgreSQL 線路協定,請使用 stackql srv 搭配相同的 MCP 旗標,再加上 --pgsrv.port。
- 選擇安全模式。模式在伺服器設定中指定,並管控代理程式可以執行的作業:
| 模式 | SELECT / 中繼資料 | INSERT / UPDATE | DELETE | EXEC |
|---|---|---|---|---|
read_only | 允許 | 拒絕 | 拒絕 | 拒絕 |
safe(預設) | 允許 | 需要核准 | 需要核准 | 需要核准 |
delete_safe | 允許 | 允許 | 需要核准 | 需要核准 |
full_access | 允許 | 允許 | 允許 | 允許 |
「需要核准」使用 MCP 徵詢(elicitation)流程:用戶端會向使用者顯示待執行的 SQL,由使用者接受或拒絕。資源清單代理程式請固定使用 read_only;full_access 僅保留給稽核記錄經過審查的受信任管線。包含多個陳述式的承載會依其中權限最高的陳述式管控(從 v0.12.742 起),因此變更無法夾帶在開頭的 SELECT 之後。
- 讓代理程式先探索,再查詢。典型的代理程式工作階段:先呼叫一次
server_info,接著list_providers->list_methods(會顯示必要的WHERE參數)->validate_select_query->run_select_query:
SELECT name, language, stargazers_count
FROM github.repos.repos
WHERE org = 'stackql';
代理程式完全不需要載入 SDK;schema 在執行階段探索,查詢則是一般的 SQL。
稽核
每次工具呼叫都會將一筆 JSONL 記錄(時間戳記、工具、模式、決策、查詢類別、SQL、持續時間)寫入具備輪替功能的檔案接收端。稽核預設為開啟,記錄的是代理程式做了什麼(而非結果資料列)。在預設的 strict 失敗模式下,稽核寫入失敗會以錯誤呈現,而不會讓未經稽核的變更趁隙通過。
相關概念
- 如何搭配 Claude 使用 StackQL:Claude Desktop 設定
- StackQL MCP 架構:傳輸方式、模式與稽核的內部機制
- StackQL vs 自訂 MCP 伺服器:何時應自行建置
- 什麼是代理式基礎架構?:這套做法所實現的模式
- 為什麼 SQL 是雲端 API 的強大介面:為什麼代理程式與 SQL 相契合