MCP Toolbox CLI 完全指南：toolbox 命令、参数与实战配置详解

MCP Toolbox CLI 完全指南：toolbox 命令、参数与实战配置详解

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

导读

本文是 MCP Toolbox for Databases（一个开源的数据库 MCP Server）官方 CLI 参考文档的深度解析与实战扩充，完整覆盖toolbox根命令的全部 33 个命令行参数、invoke/migrate/skills-generate三个子命令的用法，并结合仓库源码（cmd/root.go、cmd/internal/flags.go、cmd/internal/config.go 等）讲解参数背后的实现原理。读完本文，你将能够熟练地通过命令行启动、加固、调试 Toolbox 服务器，理解配置热重载、MCP 认证、TLS 传输等关键机制，并能在不启动完整客户端的情况下直接用 CLI 测试工具、迁移旧配置和生成 Agent Skill。

一、toolbox 根命令与整体结构

toolbox命令行程序采用 Go 编写，基于 Cobra 框架构建。入口定义在 cmd/root.go，由 main.go 调用Execute()启动。根命令之下注册了四个子命令：invoke、skills-generate、serve、migrate，其中serve是部署服务器用的显式子命令，而默认的根命令运行（不带子命令）同样会启动服务器（见 cmd/root.go 中cmd.RunE = run）。

版本信息由cmd/version.txt（当前为1.11.0）通过//go:embed注入，并附加buildType.GOOS.GOARCH与可选 commit 信息（cmd/root.go），可通过-v/--version查看。

二、全局参数速查表

下表完整列出toolbox根命令支持的全部参数，取自官方参考文档并补充了源码实现细节（flag 定义见 cmd/internal/flags.go）：

值得注意的实现细节

• 互斥校验：--config、--configs、--config-folder通过MarkFlagsMutuallyExclusive强制互斥（cmd/internal/flags.go），同一时间只能使用三者之一；--prebuilt则可与三者任意组合叠加。
• 旧参数兼容：--tools-file、--tools-files、--tools-folder是已废弃的别名，分别对应--config、--configs、--config-folder，使用时会提示改用新参数（cmd/internal/flags.go）。
• --http-max-request-bytes的默认值来自server.DefaultHTTPMaxRequestBytes常量（cmd/internal/flags.go），即 10485760 字节（10 MB），用于限制 MCP HTTP 请求体大小。
• 持久化 flag：--log-level、--logging-format、--telemetry-*、--sql-commenter、--user-agent-metadata、--disable-version-check被注册为持久化（persistent）flag（cmd/internal/flags.go），对所有子命令同样生效。

三、子命令详解

3.1invoke：不启动服务器直接调用工具

invoke子命令用于携带参数直接执行某个工具，非常适合在不搭建完整 MCP 客户端的情况下测试工具配置与参数。

语法：

toolbox invoke <tool-name> [params]

参数：

• tool-name：要执行的工具名（与配置文件中定义的名字一致）。
• params：（可选）包含工具参数的 JSON 字符串。

示例：

toolbox invoke my-tool '{"param1": "value1"}'

源码视角：执行流程见 cmd/internal/invoke/command.go：先加载配置并初始化全部 primitive（sources、authServices、tools、prompts、resources、groups），然后按名称查找工具、取回其 Source 并校验，将 JSON 参数解析并嵌入（EmbedParams）后调用tool.Invoke，最终以json.MarshalIndent格式化输出结果。需要注意：invoke是瞬时调用，不支持客户端授权流程——如果工具要求客户端授权（RequiresClientAuthorization），命令会直接报错"client authorization is not supported"（cmd/internal/invoke/command.go）。

更详细的用法说明参见 Invoke Tools via CLI。

3.2migrate：把旧式嵌套配置迁移为扁平格式

migrate子命令负责将旧式嵌套格式的配置文件（顶层包含sources:、tools:、toolsets:等映射）重写为扁平格式——即每个资源独立成为一个带kind字段的 YAML 文档；同时把toolsetprimitive 转换为groupprimitive。

语法：

toolbox migrate --config <path>

Flags：

• --config：（可选）要迁移的配置文件路径；未设置其他 config flag 时默认tools.yaml。
• --configs：（可选）逗号分隔的待迁移配置文件列表。
• --config-folder：（可选）目录路径，其中的.yaml和.yml文件都会被迁移。
• --dry-run：（可选）只把迁移结果打印到 stdout，不写回文件。

行为要点：

• --config、--configs、--config-folder三者互斥。
• 每个文件就地重写，原文件以.bak后缀保留在旁（如tools.yaml.bak）；无需变更的文件保持原样。
• 除顶层注释外，其余注释不会保留，因此删除备份前务必先审查迁移结果。

源码视角：迁移的核心是 cmd/internal/config.go 中的ConvertConfig，它通过yaml.MapSlice保持字段顺序，识别hasKindField判断文档是否已是扁平格式；migrateToolsetKind将kind: toolset改写为kind: group，并对 toolset 上不支持的description字段给出警告后丢弃（cmd/internal/config.go）。写回逻辑见 cmd/internal/migrate/command.go：--dry-run只打印，否则先将原文件重命名为.bak，再以原文件权限写回新内容；若写入失败会自动回滚恢复原文件。

3.3skills-generate：从 toolset/group 生成 Agent Skill 包

skills-generate从指定的 toolset 或 group 生成一个 skill 包，集合中的每个工具都会对应生成一个 Node.js 执行脚本。

语法：

toolbox skills-generate --name <name> --description <description> --toolset <toolset> --output-dir <output>

Flags：

• --name：（可选）生成的 skill 名称。省略--toolset生成多个 toolset 时，该名称作为每个 skill 目录的前缀（如<name>-<toolset>）；单 skill 模式下省略时，默认按顺序取：--group名 →--toolset名 → 单个--prebuilt配置名；其余情况必须提供--name。
• --description：（可选）生成 skill 的描述。group 自带description时优先用 group 的，--description仅作回退。
• --group：（可选）要转换为单个 skill 的 group 名。优先使用该 group 的description，回退到--description。与--toolset互斥。
• --toolset：（可选）要转换为 skill 的 toolset 名。未提供时，为每个自定义 toolset 生成一个 skill；若没有自定义 toolset，则默认生成一个包含全部工具的单 skill。
• --output-dir：（可选）skill 输出目录（默认skills）。
• --license-header：（可选）要前置到生成的 Node 脚本中的许可头。
• --additional-notes：（可选）追加到生成的SKILL.md的 Usage 部分之下的附加说明。
• --invocation-mode：（可选）生成脚本的调用模式：binary或npx（默认npx）。
• --toolbox-version：（可选）npx 方式使用的@toolbox-sdk/server版本（默认取当前 toolbox 版本）。

源码视角：实现见 cmd/internal/skills/command.go。它通过InitializeOfflineConfigs离线初始化 tools 与 groups（不需要真实连接数据库），因此skills-generate使用AllowMissingEnvVars: true的解析器，缺失的${VAR}环境变量会被替换为占位符而非报错（cmd/internal/skills/command.go，对应 cmd/internal/config.go 的解析逻辑）。每个 skill 目录包含SKILL.md、assets/（打包配置所需的 YAML 文件）和scripts/（每个工具一个.js执行脚本）。名称解析规则见resolveSkillName（cmd/internal/skills/command.go）。

更多说明参见 Generate Agent Skills。

四、安全加固实战（Hardening Toolbox）

Toolbox 的设计以灵活为首要目标，但安全不容忽视——即使在本地开发环境也是如此。当服务器暴露到网络或与浏览器同机运行时，请务必使用以下配置保护数据与系统。

4.1 主机校验与 DNS Rebinding 防护

--allowed-hosts控制服务器接受哪些Host头。收紧它是防御 DNS Rebinding 攻击的第一道防线。

• Flag：--allowed-hosts
• 本地开发：设置为localhost或127.0.0.1。
• 生产环境：设置为你的具体 FQDN（如toolbox.example.com）。
• 示例：

  ./toolbox --allowed-hosts="localhost,127.0.0.1"

关于"本地"的误区：即使在本机，使用--allowed-hosts="*"也不安全。恶意网站可以诱使你的浏览器向127.0.0.1发起请求，从而绕过浏览器安全机制控制你的本地 Toolbox。

4.2 跨域资源共享（CORS）

--allowed-origins决定哪些 Web 应用（前端）被允许与你的 Toolbox API 通信。

• Flag：--allowed-origins
• 建议：任何包含敏感数据的环境都应避免使用*，应显式列出受信任的前端 URL。
• 示例：

  ./toolbox --allowed-origins="https://my-mcp-ui.internal.com"

4.3 传输层安全（TLS/HTTPS）

默认情况下流量是未加密的（HTTP）。在生产环境或共享网络中，必须启用 TLS 以防范中间人（MitM）攻击与数据包嗅探。

• Flag：--tls-cert与--tls-key（两者必须同时提供才会激活 TLS）
• 协议：Toolbox 强制最低使用 TLS 1.2，以确保采用现代加密标准。
• 使用场景：公网域名可使用 Certbot 签发证书，本地可信开发证书可使用 mkcert。
• 示例：

  ./toolbox --tls-cert=cert.pem --tls-key=key.pem

源码视角：在 cmd/root.go 中，useTLS := opts.Cfg.CertFile != "" || opts.Cfg.KeyFile != ""，一旦启用 TLS，日志中的协议会自动切换为https，UI 地址也会显示为https://.../ui。服务器会收到 SIGINT/SIGTERM 信号后进入最长 10 秒的优雅关闭流程（cmd/root.go）。

五、传输配置：HTTP 与 STDIO

服务器设置：

• --address/-a：服务器监听地址（默认127.0.0.1）
• --port/-p：服务器监听端口（默认5000）

STDIO：

• --stdio：以 MCP STDIO 模式运行，替代 HTTP 服务器

使用示例：

# 自定义端口启动基础服务器 ./toolbox --config "tools.yaml" --port 8080 # 同时加载自定义配置与 prebuilt 配置 ./toolbox --config tools.yaml --prebuilt alloydb-postgres # 加载多个 prebuilt 配置（两种写法等价） ./toolbox --prebuilt alloydb-postgres,alloydb-postgres-admin # 或 ./toolbox --prebuilt alloydb-postgres --prebuilt alloydb-postgres-admin # 只加载某个 prebuilt 配置中的指定 toolset ./toolbox --prebuilt alloydb-postgres/monitor

源码视角：--stdio模式下走s.ServeStdio(ctx, in, out)（cmd/root.go），适合作为本地 MCP 客户端/IDE 的子进程直接接入；HTTP 模式下先s.Listen再s.Serve，并在--ui开启时打印 UI 访问地址。serve子命令（cmd/internal/serve/command.go）提供了同样的服务器启动能力。

六、工具配置来源

CLI 提供多种互斥的方式来指定工具配置：

单文件（默认）：

• --config：单个 YAML 配置文件路径（默认tools.yaml）

多文件：

• --configs：逗号分隔的待合并 YAML 文件列表

目录：

• --config-folder：包含待加载合并的 YAML 文件的目录

Prebuilt 配置：

• --prebuilt：使用一个或多个针对特定数据库类型的预定义配置（如bigquery、postgres、spanner），可附加 toolset 名过滤所加载的工具（如alloydb-postgres/monitor）。这些 prebuilt 配置面向"构建期"（build-time）场景（Agent 协助受信任的开发人员构建东西），不足以应对"运行期"（run-time）场景（Agent 与可能不受信任的开发人员对话）。允许值见 Prebuilt Tools Reference。

CLI 强制配置文件来源 flag 互斥，防止同时使用--config、--configs或--config-folder。

源码视角：多文件合并由 cmd/internal/config.go 的LoadAndMergeConfigs完成，内部调用mergeConfigs检测 source、authService、tool、prompt、resource、resourceTemplate、group 的重名冲突以及 resource URI 冲突（cmd/internal/config.go）；冲突时报错并列出具体项。目录加载由GetPathsFromConfigFolder用 glob 匹配目录内所有*.yaml与*.yml文件（cmd/internal/config.go）。此外配置解析还支持${ENV_VAR}与${ENV_VAR:default}形式的环境变量替换（cmd/internal/config.go）。

关于 prebuilt 配置的动态 SQL 安全，仓库文档特别提醒：execute_sql这类工具让 Agent 提供原始 SQL，工具注解和 MCP 客户端确认只是 UX 层护栏，并非数据库安全边界；应使用仅具备所需最小权限的专用数据库身份运行这些工具，不要依赖关键词黑名单来保证任意 SQL 端点的安全（见 Prebuilt Configs）。

七、配置热重载（Hot Reload）

Toolbox 支持两种检测配置变更的方式：Push（事件驱动）与Poll（定时轮询）。要彻底禁用热重载，使用--disable-reloadflag。

• Push（默认）：Toolbox 使用高效的推送系统监听操作系统级文件事件，保存配置的瞬间即触发重载。
• Poll（回退方案）：也可以用--poll-interval=<seconds>按固定节奏主动检查更新。轮询是"拉取"式检查，非常适合 OS 事件可能丢失的网络驱动器或容器挂载卷场景。间隔设为0表示禁用轮询系统。

源码视角：热重载实现位于 cmd/root.go 的watchChanges。Push 模式基于fsnotify监听文件事件（关注Write、Create、Rename），带 100ms 防抖（debounce）以避免编辑器多次写入触发多次重载；Poll 模式通过time.Ticker周期性调用scanWatchedFiles比对文件ModTime，并检测文件删除。重载前会先调用validateReloadEdits对配置进行解析与校验，失败则保留当前运行状态并记录警告；成功后才用新配置更新 server 的全部 primitive（cmd/root.go）。仅当存在自定义配置且未传--disable-reload时才启动 watcher（cmd/root.go）。

八、Toolbox UI

使用--uiflag 启动 Toolbox 的交互式 UI，可以在界面上测试工具与 toolset，支持 authorized parameters 等特性。详见 Toolbox UI。

启动后服务端会在日志中打印 UI 地址（形如http://127.0.0.1:5000/ui，启用 TLS 时协议变为https）。

九、禁用 MCP 扩展

默认情况下，Toolbox 在客户端发现阶段会通告对自有自定义 MCP 扩展（如com.google.cloud/toolbox.v1）的支持。该扩展向客户端表明可以使用官方 MCP 规范之外的 Toolbox 专属能力（仓库中关于这些扩展能力与版本策略的说明见 extensions/README.md，其标识符规范为com.google.cloud/toolbox.<version>）。

禁用某个扩展会将其从服务器通告的能力中移除。通过--disable-ext传入要禁用的扩展 URI：

# 禁用 Toolbox v1 扩展 ./toolbox --disable-ext com.google.cloud/toolbox.v1

--disable-ext是 StringSlice 类型（cmd/internal/flags.go），可以多次传入以禁用多个扩展 URI。

十、从源码构建与运行

仓库根目录的 main.go 是程序入口，go.mod定义了 Go 模块github.com/googleapis/mcp-toolbox。可通过go build直接构建出toolbox二进制（./toolbox），随后按本文各节示例运行。命令行实现的单元测试分布在 cmd/root_test.go 与cmd/internal/各子目录的command_test.go中，可作为理解参数行为与编写自动化验证的参考。

结语

toolboxCLI 将服务器启动、工具调试、配置迁移与 Skill 生成浓缩在少量参数与四个子命令中。本文既是对官方 CLI 参考文档 的完整继承，也通过源码佐证了互斥校验、环境变量替换、热重载、TLS 切换等底层机制。建议在生产部署前重点实践第四章的安全加固组合（--allowed-hosts+--allowed-origins+--tls-cert/--tls-key），并结合--dry-run先预览migrate的迁移结果，确保配置变更安全可控。

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox