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.goFlag (Short)Flag (Long)说明默认值-a--address服务器监听地址127.0.0.1--disable-ext指定在本服务器上禁用的 MCP 扩展 URI--disable-reload禁用配置动态重载-h--help显示 toolbox 帮助--http-max-request-bytesMCP HTTP 请求体的最大字节数1048576010 MB--ignore-unknown-tools对未知/不支持的工具类型仅记录警告并跳过而不是启动失败--log-level最低日志级别可选DEBUG/INFO/WARN/ERRORinfo--logging-format日志格式可选standard或JSONstandard--mcp-prm-file手动 Protected Resource Metadata (PRM) JSON 文件路径提供后将覆盖 MCP Server-Wide Authentication 的自动生成-p--port服务器监听端口5000--tls-certPEM 编码的 TLS 证书文件路径--tls-keyPEM 编码的 TLS 私钥文件路径--toolbox-url绝对 Toolbox URL如https://my-toolbox.example.comMCP Auth 启用时用作 MCP PRM 文件中的 resource 字段未设置时回退到TOOLBOX_URL环境变量--prebuilt按 source 类型使用一个或多个预构建工具配置可附加 toolset 后缀如source/toolset只加载该 toolset。这些配置面向构建期build-time场景Agent 协助受信任的开发人员不足以应对运行期run-time场景Agent 与可能不受信任的开发人员对话。允许值见 Prebuilt Tools Reference--stdio通过 MCP STDIO 监听而非作为远程 HTTP 服务器运行--telemetry-gcp直接导出遥测数据到 Google Cloud Monitoring--telemetry-gcp-project--telemetry-gcp使用的 Google Cloud 项目 ID未设置时默认取GOOGLE_CLOUD_PROJECT--telemetry-otlp通过 OpenTelemetry Protocol (OTLP) 导出遥测数据到指定端点如http://127.0.0.1:4318--telemetry-service-name设置遥测数据的service.nameresource 属性toolbox--sql-commenter在执行 SQL 前以 SQLCommenter 格式注入注释traceparent、server、tool.name、db.system.name以及来自_meta[dev.mcp-toolbox/telemetry]的客户端元数据--config指定工具配置文件的路径。不能与--configs、--config-folder同时使用--configs指定多个工具配置文件路径多个文件会被合并。不能与--config、--config-folder同时使用--config-folder包含 YAML 工具配置文件的目录路径目录内所有.yaml、.yml文件会被加载并合并。不能与--config、--configs同时使用--ui启动 Toolbox UI Web 服务器--allowed-origins允许访问本服务器的来源origin列表用于 CORS 控制*--allowed-hosts允许访问本服务器的主机Host列表用于防御 DNS rebinding 攻击*--user-agent-metadata向 User-Agent 追加额外元数据--poll-interval配置文件更新的轮询频率秒0--enable-draft-specs选择加入并测试即将推出的 MCP 草案规范false-v--version显示 toolbox 版本值得注意的实现细节互斥校验--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被注册为持久化persistentflagcmd/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先加载配置并初始化全部 primitivesources、authServices、tools、prompts、resources、groups然后按名称查找工具、取回其 Source 并校验将 JSON 参数解析并嵌入EmbedParams后调用tool.Invoke最终以json.MarshalIndent格式化输出结果。需要注意invoke是瞬时调用不支持客户端授权流程——如果工具要求客户端授权RequiresClientAuthorization命令会直接报错client authorization is not supportedcmd/internal/invoke/command.go。更详细的用法说明参见 Invoke Tools via CLI。3.2migrate把旧式嵌套配置迁移为扁平格式migrate子命令负责将旧式嵌套格式的配置文件顶层包含sources:、tools:、toolsets:等映射重写为扁平格式——即每个资源独立成为一个带kind字段的 YAML 文档同时把toolsetprimitive 转换为groupprimitive。语法toolbox migrate --config pathFlags--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 outputFlags--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执行脚本。名称解析规则见resolveSkillNamecmd/internal/skills/command.go。更多说明参见 Generate Agent Skills。四、安全加固实战Hardening ToolboxToolbox 的设计以灵活为首要目标但安全不容忽视——即使在本地开发环境也是如此。当服务器暴露到网络或与浏览器同机运行时请务必使用以下配置保护数据与系统。4.1 主机校验与 DNS Rebinding 防护--allowed-hosts控制服务器接受哪些Host头。收紧它是防御 DNS Rebinding 攻击的第一道防线。Flag--allowed-hosts本地开发设置为localhost或127.0.0.1。生产环境设置为你的具体 FQDN如toolbox.example.com。示例./toolbox --allowed-hostslocalhost,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-originshttps://my-mcp-ui.internal.com4.3 传输层安全TLS/HTTPS默认情况下流量是未加密的HTTP。在生产环境或共享网络中必须启用 TLS 以防范中间人MitM攻击与数据包嗅探。Flag--tls-cert与--tls-key两者必须同时提供才会激活 TLS协议Toolbox 强制最低使用 TLS 1.2以确保采用现代加密标准。使用场景公网域名可使用 Certbot 签发证书本地可信开发证书可使用 mkcert。示例./toolbox --tls-certcert.pem --tls-keykey.pem源码视角在 cmd/root.go 中useTLS : opts.Cfg.CertFile ! || opts.Cfg.KeyFile ! 一旦启用 TLS日志中的协议会自动切换为httpsUI 地址也会显示为https://.../ui。服务器会收到 SIGINT/SIGTERM 信号后进入最长 10 秒的优雅关闭流程cmd/root.go。五、传输配置HTTP 与 STDIO服务器设置--address/-a服务器监听地址默认127.0.0.1--port/-p服务器监听端口默认5000STDIO--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 ReloadToolbox 支持两种检测配置变更的方式Push事件驱动与Poll定时轮询。要彻底禁用热重载使用--disable-reloadflag。Push默认Toolbox 使用高效的推送系统监听操作系统级文件事件保存配置的瞬间即触发重载。Poll回退方案也可以用--poll-intervalseconds按固定节奏主动检查更新。轮询是拉取式检查非常适合 OS 事件可能丢失的网络驱动器或容器挂载卷场景。间隔设为0表示禁用轮询系统。源码视角热重载实现位于 cmd/root.go 的watchChanges。Push 模式基于fsnotify监听文件事件关注Write、Create、Rename带 100ms 防抖debounce以避免编辑器多次写入触发多次重载Poll 模式通过time.Ticker周期性调用scanWatchedFiles比对文件ModTime并检测文件删除。重载前会先调用validateReloadEdits对配置进行解析与校验失败则保留当前运行状态并记录警告成功后才用新配置更新 server 的全部 primitivecmd/root.go。仅当存在自定义配置且未传--disable-reload时才启动 watchercmd/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考