MCP Toolbox Sources 配置完全指南：在 tools.yaml 中定义数据源并解锁数据库工具-开发者社区

MCP Toolbox Sources 配置完全指南：在 tools.yaml 中定义数据源并解锁数据库工具

【免费下载链接】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中的Source是"工具可以交互的数据源"的抽象：一个 Source 代表一个数据库或 HTTP 服务连接，在tools.yaml中以kind: source声明。本文以官方配置文档 docs/en/documentation/configuration/sources/_index.md 为主体，结合仓库源码讲解 Source 的配置字段、环境变量注入、解析流程与底层连接管理机制，读完你就能为 Cloud SQL、PostgreSQL、MySQL 等任意受支持数据库编写可运行的 Source 配置，并理解它如何解锁一批专用工具。

Source 是什么：工具与数据库之间的连接抽象

在 MCP Toolbox 中，Source 表示一个工具可以交互的数据源。你可以在tools.yaml文件的source区域中以映射（map）的形式定义任意多个 Source。通常，一个 Source 配置包含连接并交互数据库所需的全部信息——地址、端口、认证凭据、目标数据库等。

从实现角度看，每个 Source 在运行时都是一个独立的连接池（connection pool）或客户端（client），工具通过它连接数据库并执行操作。这也是为什么配置文档特别强调：连接信息属于敏感数据，不要把密钥硬编码进配置文件。

建议使用${ENV_NAME}格式的环境变量替换来替代在配置文件中硬编码你的密钥。

一个最小的 Cloud SQL PostgreSQL Source 配置如下（出自官方文档）：

kind: source name: my-cloud-sql-source type: cloud-sql-postgres project: my-project-id region: us-central1 instance: my-instance-name database: my_db user: ${USER_NAME} password: ${PASSWORD}

这段配置声明了一个名为my-cloud-sql-source的 Source，其类型为cloud-sql-postgres，指定了 GCP 项目、区域、实例、数据库名，用户名和密码则通过${USER_NAME}、${PASSWORD}两个环境变量注入，避免明文写入文件。

Source 配置结构逐字段拆解

一个kind: source文档由通用字段和类型相关字段组成。通用字段在 internal/server/config.go 的UnmarshalYAMLSourceConfig中解析：

字段	必填	说明
`kind`	是	固定为`source`，用于区分同一文件中的其他配置类型（`tool`、`toolset`、`group`、`prompt`、`resource`等）
`name`	是	Source 的唯一名称，工具通过`source: <name>`引用它；同一文件中名称不可重复，重复声明会报错
`type`	是	Source 类型，决定后续字段如何解析，如`cloud-sql-postgres`、`postgres`、`mysql`等
其余字段	视类型而定	与具体数据库/服务的连接参数，见下方分类

在 internal/server/config.go 中，kind: source的文档会被分发到UnmarshalYAMLSourceConfig：先读取type字段，再以严格解码器（strict decoder）把剩余字段交给sources.DecodeConfig按类型解析。也就是说，配置校验是类型驱动的——字段是否合法取决于你声明的type。

通用数据库 Source 的参数

以仓库内置的 internal/prebuiltconfigs/tools/postgres.yaml 为例，postgres类型的 Source 配置为：

kind: source name: postgresql-source type: postgres host: ${POSTGRES_HOST:localhost} port: ${POSTGRES_PORT:5432} database: ${POSTGRES_DATABASE} user: ${POSTGRES_USER} password: ${POSTGRES_PASSWORD} queryParams: ${POSTGRES_QUERY_PARAMS:}

字段含义：

host：数据库主机地址。这里使用了${POSTGRES_HOST:localhost}语法，冒号后是默认值——环境变量未设置时回退到localhost，方便本地开发。
port：端口号，默认5432。
database：目标数据库名。
user/password：认证凭据，强烈建议用环境变量注入。
queryParams：附加的连接查询参数（如 SSL 配置），可为空字符串。

Cloud SQL 类型 Source 的参数

官方文档示例中的cloud-sql-postgres使用 GCP 资源定位方式：

project：GCP 项目 ID。
region：实例所在区域。
instance：实例名称。
database：数据库名。
user/password：数据库用户与密码。

从源码看，Cloud SQL 类连接还支持更细粒度的网络与认证控制：internal/sources/util.go 中的GetCloudSQLOpts支持通过ipType指定连接方式，必须是public、private或psc三者之一，并可配合useIAM启用 Cloud SQL IAM 数据库认证（WithIAMAuthN）。这类参数在不同 Cloud SQL 集成文档（如cloud-sql-mysql、cloud-sql-mssql）中各有对应配置项，具体字段以对应集成文档为准。

环境变量替换：${ENV_NAME} 与默认值语法

Source 配置支持环境变量替换，格式为${ENV_NAME}。仓库的配置解析基于 goccy/go-yaml 与 internal/sources/sources.go），环境变量展开发生在 YAML 解码之前。

更实用的是带默认值的写法${ENV_NAME:default}：

host: ${POSTGRES_HOST:localhost} # 未设置 POSTGRES_HOST 时使用 localhost port: ${POSTGRES_PORT:5432} # 未设置 POSTGRES_PORT 时使用 5432 queryParams: ${POSTGRES_QUERY_PARAMS:} # 默认值为空字符串

这种写法让同一份tools.yaml可以在本地与生产环境复用：开发环境不导出任何变量即用默认值，生产环境通过环境变量注入真实连接信息，密钥永不落盘。

从源码看 Source 的解析与注册机制

Source 的类型系统定义在 internal/sources/sources.go：

SourceConfigFactory：创建SourceConfig的工厂函数签名func(ctx, name, *yaml.Decoder) (SourceConfig, error)。
注册表sourceRegistry：包级 map，各数据库实现通过Register(sourceType, factory)把自己注册进来；若类型已存在则返回false且不覆盖（internal/sources/sources.go）。
DecodeConfig：按type从注册表取出工厂解析配置；类型不存在时返回unknown source type: %q错误（internal/sources/sources.go）。
SourceConfig接口：要求实现SourceConfigType()与Initialize(ctx, tracer) (Source, error)——配置负责初始化出可用的连接对象。
Source接口：要求实现SourceType()、ToConfig()与IsReadOnly()。其中IsReadOnly()标记该数据源是否为只读，是只读安全特性（read-only 模式）的判定依据之一。

配置与实现分离是这套设计的关键：tools.yaml里你写的kind: source+type只是声明；真正"连接"发生在服务启动时对每个SourceConfig调用Initialize，此时才会建立连接池或客户端。

底层连接管理：连接池、延迟初始化与 60 秒超时

文档指出"每个 source 是一个连接池或客户端"。仓库在 internal/sources/connect.go 中提供了统一连接管理组件ConnectOnce[T]，其设计要点可以从源码注释与实现中确认：

延迟连接（lazy connect）：连接在首次使用时通过Do建立而非启动时强制建立（internal/sources/connect.go）。并发调用方共享同一次连接尝试（基于singleflight.Group），失败的尝试不会被缓存，下一个调用者会重试。
连接超时上限：ConnectTimeout = 60 * time.Second，注释明确它按"冷启动的云连接器路径"而非健康连接来设定上限（internal/sources/connect.go）；WithMinConnectTimeout可以抬高上限，但不会把上限压低。
安全关闭：Close释放已建立的连接并阻止新连接，重复调用安全（internal/sources/connect.go）。由于不同驱动关闭方式各异（pgx 的Close、neo4j 驱动接收 context、mongo 的Disconnect），关闭函数通过OnClose显式注册而非接口断言。
可观测性：每次连接建立都会产生toolbox/server/source/connect追踪 span，携带source_type与source_name属性（internal/sources/sources.go），连接失败时 span 会被标记为 error。

此外，internal/sources/util.go 的NormalizeValue展示了连接之上的数据加工：PostgreSQL 的 UUID（OID 2950）与 UUID 数组（OID 2951）会被自动转换为字符串表示，保证工具返回值对 LLM 友好。

Source 如何解锁工具：source 字段与预置配置

Source 本身不产生能力，能力来自绑定到该 Source 上的工具。在tools.yaml中，工具通过source: <source-name>引用数据源。例如 internal/prebuiltconfigs/tools/postgres.yaml：

kind: tool name: execute_sql type: postgres-execute-sql source: postgresql-source description: Use this tool to execute a single SQL statement.

同一个 Source 可以被几十个工具共享：上述 Postgres 预置配置中，execute_sql、list_tables、list_active_queries、database_overview、list_indexes等数十个工具全部指向postgresql-source，并通过kind: toolset（data、monitor、health、replication等）分组暴露给客户端。

这与 docs/en/integrations/_index.md 的说明一致：一个 Source 连接定义一次，即可解锁一整套专用工具（查询数据、列出表、分析 schema 等）。

使用预置配置快速上手

如果你不想从零编写 Source 配置，可以使用仓库自带的预置配置。根据 docs/en/documentation/configuration/prebuilt-configs/_index.md 的说明：

用--prebuilt配合--config、--configs或--config-folder将预置配置与自定义工具组合；
可以组合多个预置配置；
用/追加工具集名称来只加载其中一部分，例如--prebuilt=postgres/data只加载 SQL 工具。

需要提醒的是，预置配置中的动态 SQL 工具（如execute_sql）允许 Agent 直接提交原始 SQL。官方文档明确警告：这类工具应使用只具备 Agent 所需最小权限的专用数据库身份运行（如仅SELECT权限），避免使用 owner、admin 或迁移账号，也不要用正则关键词黑名单来试图让任意 SQL 端点变得安全。

查看所有受支持的 Source 类型

本文只深入剖析了cloud-sql-postgres与postgres两种类型，但 MCP Toolbox 支持的 Source 远不止于此。完整的受支持 Source 列表及其解锁的专用工具，请查看仓库的 Integrations 索引，其中按集成分类（BigQuery、MySQL、MongoDB、Spanner、Snowflake、Cloud Storage 等）提供了各自的tools.yaml连接片段与可用工具清单。

小结

Source 是 tools.yaml 中的kind: source声明，承载连接数据库所需的全部信息，运行时表现为独立的连接池或客户端。
字段分两层：kind/name/type是通用结构，连接参数由type决定（host/port/database/user/password适用于通用数据库，project/region/instance适用于 Cloud SQL）。
密钥必须走环境变量：${ENV_NAME}注入、${ENV_NAME:default}提供回退值。
底层由类型注册表驱动：Register+DecodeConfig完成配置解析，Initialize建立连接，ConnectOnce负责延迟连接、60 秒超时上限与并发去重。
工具通过source字段绑定数据源，一个 Source 可解锁整套工具，可用--prebuilt快速加载预置配置。