mcp-toolbox 的 Cloud Storage Source 详解项目级配置、14 个 GCS 工具与 allowedLocalRoots 路径安全机制【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本文为 mcp-toolbox 中cloud-storage数据源source的完整技术指南。读完你将掌握如何在配置文件中声明一个项目级的 Cloud Storage 数据源、该数据源暴露的全部 14 个工具及其分组的 toolsets、各工具所需的 IAM 权限、allowedBuckets与allowedLocalRoots两个安全约束字段的精确语义与源码级实现原理以及预置配置prebuilt的启用方式。一、Cloud Storage Source 是什么Cloud Storage 是 Google Cloud 的托管对象存储服务用于以bucket桶为容器存放非结构化数据blob。bucket 隶属于一个 GCP 项目对象通过gs://bucket/object寻址。在 mcp-toolbox 中Cloud Storage source 是一个**项目级project level**的数据源source 只配置一个 GCP 项目 ID不绑定具体 bucket每个工具都接受bucket参数因此一个配置好的 source 可以操作该凭据有权限访问的任意 bucket通过 [IAM][gcs-iam-roles]Identity and Access Management控制对 bucket 和 object 的访问toolbox 使用Application Default CredentialsADC在与 Cloud Storage 交互时完成授权和认证。因此部署前必须先为服务器进程配置好 ADC并确保对应 IAM 身份拥有将要暴露的工具所需的角色。说明外部文档链接Cloud Storage 官方文档、quickstart、IAM 角色清单以本文中的术语名称代替读者可按名称在 Google 官方文档中检索。二、Source 配置字段参考与完整示例2.1 配置示例以下是一个可直接放入 toolbox 配置文件的完整 source 声明继承自官方文档的示例kind: source name: my-gcs-source type: cloud-storage project: my-project-id allowedBuckets: - my-app-bucket - my-backup-bucket allowedLocalRoots: - /workspace2.2 字段参考字段类型必填说明typestring是必须为cloud-storage。projectstring是source 所属 GCP 项目的 ID例如my-project-id。allowedBuckets[]string否允许操作的对象存储桶名称列表省略时表示允许所有桶。allowedLocalRoots[]string否允许用于文件上传/下载的绝对本地目录列表路径在解析符号链接后仍须留在根目录之内省略时表示允许所有路径。从源码看该字段表与 Cloud Storage source 配置结构体 一一对应Name、Type、Project标注了validate:required而AllowedBuckets与AllowedLocalRoots均为可省略omitempty的字符串切片。source 在初始化时会以该 project 创建 GCS 客户端Initialize调用initGCSClient并在init()中向 source 注册表登记cloud-storage类型。2.3 预置配置prebuilt仓库自带cloud-storage预置配置预置配置文件 展示了开箱即用的完整声明kind: source name: cloud-storage-source type: cloud-storage project: ${CLOUD_STORAGE_PROJECT}--prebuilt取值cloud-storage需要的环境变量CLOUD_STORAGE_PROJECT拥有目标 bucket 的 GCP 项目 ID预置配置一次性声明了全部 14 个工具见下节和 2 个 toolset未设置allowedBuckets/allowedLocalRoots即不做额外收敛安全边界完全依赖 IAM 角色。三、可用工具一览与 Toolsets该 source 提供 14 个工具按操作对象分为两组工具文档索引桶Bucket管理工具toolsetcloud-storage-buckets工具类型作用cloud-storage-list-buckets列出配置项目下的所有 Cloud Storage 桶cloud-storage-create-bucket在配置项目中创建桶cloud-storage-get-bucket-metadata获取桶的元数据cloud-storage-get-bucket-iam-policy获取桶的 IAM 策略绑定cloud-storage-delete-bucket删除空桶对象Object管理工具toolsetcloud-storage-objects工具类型作用cloud-storage-list-objects列出桶中的对象支持前缀prefix与分隔符delimiter过滤cloud-storage-get-object-metadata获取对象元数据cloud-storage-read-object读取 UTF-8 文本对象或字节范围上限 8 MiB拒绝读取二进制对象二进制请用download-objectcloud-storage-download-object将对象下载到本地文件路径cloud-storage-write-object将文本内容直接写入对象cloud-storage-upload-object将本地文件上传为对象cloud-storage-copy-object将对象复制到目标对象同桶或跨桶cloud-storage-move-object在同一桶内原子重命名对象cloud-storage-delete-object删除对象两个 toolset 在 预置配置 中通过kind: group定义并带有面向 LLM 的用途描述例如cloud-storage-buckets组注明当你需要管理桶、创建桶、检查桶元数据与访问控制策略、删除桶时使用帮助 Agent 在工具众多时快速选中正确的组。关于read-object的 8 MiB 上限从源码看Cloud Storage source 代码 中定义了defaultMaxReadBytes 8 208 MiB常量注释明确说明其目的有两个——防止服务端 OOM、以及把 LLM 上下文保持在可管理规模超出的对象或范围会以ErrReadSizeLimitExceeded拒绝。四、IAM 权限要求Cloud Storage 通过 IAM 控制对桶和对象的访问。除配置 ADC 外还必须确保 IAM 身份拥有与所暴露工具匹配的角色。常用角色roles/storage.bucketViewer— 桶元数据的只读访问足以支撑cloud-storage-list-buckets与cloud-storage-get-bucket-metadataroles/storage.objectViewer— 对象及对象元数据的只读访问足以支撑cloud-storage-list-objects、cloud-storage-get-object-metadata、cloud-storage-read-object、cloud-storage-download-objectroles/storage.objectUser— 对象的读写访问足以支撑cloud-storage-upload-object、cloud-storage-write-object、cloud-storage-copy-objectroles/storage.admin— 完全控制包括桶管理。各变更类工具对应的细粒度对象/桶权限工具所需权限upload-object/write-object/copy-object对目标对象的对象创建或更新权限move-object同桶内的storage.objects.move与storage.objects.create若目标对象已存在还需storage.objects.deletedelete-object对象删除权限create-bucket在配置项目中的桶创建权限get-bucket-iam-policy读取桶 IAM 策略的权限delete-bucket桶删除权限且目标桶必须为空完整的角色-权限映射参见 Cloud Storage 预置配置文档其中还给出只读部署的建议组合Storage Object Viewerroles/storage.objectViewerStorage Legacy Bucket Readerroles/storage.legacyBucketReader即可覆盖只读工具子集。五、allowedLocalRoots本地文件访问的安全边界cloud-storage-upload-object与cloud-storage-download-object读写的是Toolbox 服务器进程所在文件系统的本地文件而不是客户端机器。服务器进程必须具备相应的本地文件权限。allowedLocalRoots将这两个工具约束在你列出的目录之内。官方文档对语义的表述与源码实现高度一致这里结合源码逐条展开。5.1 路径校验拒绝..与相对路径ValidateLocalPath 执行三道检查路径非空对原始输入逐段检查——出现独立的..段即拒绝检查原始输入而非 Clean 后的结果是为了防止/legit/../../etc/passwd这类经filepath.Clean折叠后看似无害的路径混过检查而foo..bar这类仅包含两个点的合法文件名不受影响Clean 后必须是绝对路径。5.2 双重边界检查字面路径 符号链接解析Source.validateLocalPath 实现了文档中的核心语义——路径在书写形式和解析符号链接后都必须留在允许的根内名称层检查路径 Clean 后必须位于某个allowedLocalRoots根目录下isUnderRoot(clean, root)否则报错local path %q is not under any allowed local roots解析层检查调用 ResolveSymlinks 将路径沿每个符号链接解析到最终目标再将解析后的路径与解析后的根目录比较escapes判断相对路径是否以..开头或跨盘符。这样做的意义在于种在根目录内的一个符号链接可能指向文件系统任意位置仅凭名称级检查形同虚设——解析后比较才是让根目录成为真正边界的关键两个方向的解析都做了容错允许根本身经由符号链接到达例如 macOS 的/tmp、符号链接化的工作区仍然匹配而无法解析的根不会授权任何东西跳过该根而不是回退到已通过的名称级匹配悬空链接dangling link会被显式拒绝而非当作不存在的名字处理因为在这样的路径上创建文件会跟随链接接受它会重新打开这个函数旨在封死的逃逸口。这些行为均有对应测试覆盖cloudstorage_test.go 中包含空allowedLocalRoots放行、符号链接指向根外被拒绝注释直言这正是allowedLocalRoots要阻止的场景、未设置allowedLocalRoots时链接不受限制等用例paths_test.go 则覆盖..段拒绝、符号链接解析等边界。5.3 文档明示的两项局限部署时必须了解硬链接不可区分硬链接与普通文件在文件系统层面无法区分因此在允许根内创建的、指向根外文件的硬链接仍然可读TOCTOU 竞争检查发生在文件打开前的一瞬间。能写入允许根目录的进程原则上可以在检查与打开之间替换该路径上的文件。因此官方建议把allowedLocalRoots当作叠加在操作系统权限之上的护栏guardrail而非替代品应让 Toolbox 以一个只拥有必要文件访问权限的用户运行。若省略allowedLocalRoots服务器进程可达的所有绝对路径都会被放行。六、allowedBuckets桶级白名单Source.validateBucket 的逻辑很直接AllowedBuckets为空即未配置该字段时任何桶名都通过配置后则做精确字符串匹配不在列表内的桶名返回bucket %q is not allowed by source %q configuration错误。相关测试cloudstorage_test.go验证了空列表放行与列表内/列表外的行为。值得注意的设计取向allowedBuckets与allowedLocalRoots都是应用层软约束真正的访问控制边界仍然是 IAM 角色——source 配置决定工具能看见/尝试什么IAM 决定凭据真正能做什么。二者叠加使用IAM 最小权限 白名单收敛是文档与预置配置隐含的最佳实践预置配置刻意不设置白名单把收敛权留给使用者按部署环境自行收紧。七、配置落地清单为服务器进程配置 ADCservice account key、gcloud auth或 metadata server 均可并使身份具备上节所需的 IAM 角色在 toolbox 配置中声明type: cloud-storage的 source必填name与project按最小权限原则决定是否添加allowedBuckets收敛可操作桶与allowedLocalRoots收敛本地上传/下载目录须为绝对路径目录列表声明工具与 toolset可手写kind: tool条目工具type为第三节的cloud-storage-*名称或直接使用--prebuilt cloud-storage获得全部 14 个工具 2 个 toolset需设置CLOUD_STORAGE_PROJECT环境变量让 Toolbox 以受限用户运行使 OS 权限与allowedLocalRoots形成双层防护。相关仓库路径source 实现 internal/sources/cloudstorage/cloudstorage.go、路径安全公共库 internal/tools/cloudstorage/cloudstoragecommon/paths.go、各工具实现位于 internal/tools/cloudstorage/ 下的独立子包每个工具一个包并配套测试、集成测试见 tests/cloudstorage/cloud_storage_integration_test.go。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考