跳至主要內容
翻譯頁面

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

如何搭配 AI 代理程式使用 StackQL

StackQL 內建 Model Context Protocol(MCP)伺服器。任何支援 MCP 的代理程式(Claude、Cursor、Continue 或自訂代理程式架構)都能連線到此伺服器,取得一個可自我描述且受管控的 SQL 介面,存取 StackQL 登錄庫中的每個雲端與 SaaS Provider。

步驟​

  1. 設定 Provider 憑證,在啟動伺服器之前將其設為環境變數(伺服器會繼承這些變數):
export AWS_ACCESS_KEY_ID=YOURACCESSKEYID
export AWS_SECRET_ACCESS_KEY=YOURSECRETACCESSKEY

或者(在 v0.10.542 之後的 StackQL 發行版本中),使用 --env.file 指定 dotenv 格式的憑證檔案;reload_credentials MCP 工具會在工作階段中途重新讀取該檔案,讓輪替後的憑證無須重新啟動即可送達執行中的伺服器。

  1. 啟動 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。

  1. 選擇安全模式。模式在伺服器設定中指定,並管控代理程式可以執行的作業:
模式SELECT / 中繼資料INSERT / UPDATEDELETEEXEC
read_only允許拒絕拒絕拒絕
safe(預設)允許需要核准需要核准需要核准
delete_safe允許允許需要核准需要核准
full_access允許允許允許允許

「需要核准」使用 MCP 徵詢(elicitation)流程:用戶端會向使用者顯示待執行的 SQL,由使用者接受或拒絕。資源清單代理程式請固定使用 read_only;full_access 僅保留給稽核記錄經過審查的受信任管線。包含多個陳述式的承載會依其中權限最高的陳述式管控(從 v0.12.742 起),因此變更無法夾帶在開頭的 SELECT 之後。

  1. 讓代理程式先探索,再查詢。典型的代理程式工作階段:先呼叫一次 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 失敗模式下,稽核寫入失敗會以錯誤呈現,而不會讓未經稽核的變更趁隙通過。