跳到主要内容
翻译页面

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

如何在 macOS Swift 应用中嵌入 StackQL MCP 服务器

StackQL 的 MCP 服务器可以在原生 macOS 应用内运行，无需单独安装，也没有运行时依赖。stackql-mcp-swift 包在官方 Swift MCP SDK 客户端的背后通过 stdio 启动已签名的 StackQL 二进制文件。由于 darwin-universal 二进制文件使用 Developer ID 签名并经 Apple 公证，你可以将它打包到已签名的 .app 中，并保持应用的公证有效。这就是 CloudLens 所采用的模式，它是一个菜单栏云哨兵。

步骤​

  1. 添加包到 Package.swift：
.package(url: "https://github.com/stackql/stackql-mcp-swift.git", from: "0.1.0")

需要 macOS 13+ 和 Swift 6.1（Xcode 16.3+）。唯一的依赖是官方的 Swift MCP SDK。

  1. 启动服务器并调用工具。 Options.mode 默认为 .readOnly：
import StackQLMCP

var options = Options()
options.mode = .readOnly
options.auth = ["github": ["type": "null_auth"]]

let server = try await StackQLServer.start(options)
let tools = try await server.listToolNames()
print("\(tools.count) tools available")

let services = try await server.call(
    "list_services", ["provider": "github", "row_limit": 5])
print(services.text)

await server.stop()

对于外部 harness，StackQLServer.resolveCommand(_:) 返回解析后的启动命令。

  1. 选择模式。 Options.mode 默认为 .readOnly。仅当应用需要预配资源时，才设置 .safe、.deleteSafe 或 .fullAccess。权限提升必须显式进行。

将经过公证的二进制文件打包到已签名的应用中​

darwin-universal 二进制文件使用 Developer ID 签名并经 Apple 公证，因此可以打包到已签名的 macOS .app 中，同时保持应用自身的公证有效。二进制文件解析顺序：

  1. 显式指定的 binaryOverride。
  2. 打包在 .app 中的资源。
  3. 位于 ~/.stackql/mcp-server-bin/ 的共享缓存。
  4. 下载并进行 sha256 校验（设置了 allowDownload 时）。

将经过公证的二进制文件放入应用资源，打包的路径即优先：应用完全自包含，无需在首次运行时下载。

演示应用​

CloudLens 是一个菜单栏云哨兵，它嵌入经过公证的二进制文件，并运行一组 read_only 检查。