跳到主要内容
翻译页面

本页面由 AI 辅助从英文翻译而来。如两者存在差异，以英文版本为准。

StackQL MCP 架构

StackQL 的 MCP 服务器内置于引擎二进制文件中，并将 StackQL 的能力接口面（发现、描述、验证、执行）发布为 Model Context Protocol 工具。其设计围绕 3 点展开：用一组数量少而通用的工具取代按操作划分的工具，针对变更的分级安全契约，以及记录智能体所做一切的审计跟踪。

传输方式和部署模式​

模式命令用途
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_proxy通过 DSN 将 MCP 请求分发到作为后端的 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；跨源的浏览器请求会被拒绝。

工具接口面​

共 14 个工具，每个工具都返回供 LLM 使用的渲染文本视图，以及带类型的结构化负载：

  • 发现：list_providers、list_services、list_resources、list_methods、describe_method，即层次结构遍历，可在编写任何查询之前揭示必需的 WHERE 参数。
  • 注册表：list_registry（可用的 Provider 及其版本）、pull_provider（安装到本地缓存）。
  • 验证：validate_select_query，解析并规划 SELECT 而不执行。
  • 执行：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 之后的发布版本中可用）。

1 个静态提示词 write_safe_select 讲授方法发现工作流。

安全契约​

server.mode 从 4 种契约中选择一种；所有契约都允许 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 在未经审计的情况下完成。