MCP Toolbox 集成 Valkey 实战指南数据源配置、IAM 认证与动态命令工具【免费下载链接】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 中接入 Valkey以官方文档 Valkey Source 与 valkey 工具文档 为主体骨架结合 internal/sources/valkey/valkey.go 与 internal/tools/valkey/valkey.go 源码实现完整覆盖 Valkey 数据源source的配置字段、GCP Memorystore for Valkey 的 IAM 认证接入方式以及通过 valkey 工具按序执行预定义命令并支持$变量动态参数注入的完整方案。读完本文你可以直接编写一套可运行、可复制的 Valkey 数据源与命令工具 YAML 配置并理解其底层调用链。Valkey 集成概览Valkey 是一个开源的、基于内存的数据结构存储服务源自 Redis 的一个分支被设计用于数据库、缓存和消息代理等场景支持字符串strings、哈希hashes、列表lists、集合sets、支持范围查询的有序集合sorted sets with range queries、位图bitmaps、HyperLogLog 以及支持半径查询的地理空间索引geospatial indexes with radius queries等多种数据结构。在 MCP Toolbox 中Valkey 集成由两部分组成valkey 数据源source声明type: valkey负责建立到 Valkey 实例的连接含密码认证与 GCP IAM 认证两种模式并在初始化时通过PING命令验证连通性valkey 工具tool声明type: valkey基于某个 valkey 数据源把一组预定义的 Valkey 命令按顺序执行并把每个命令的返回值聚合后返回给 MCP 客户端。从源码结构看数据源实现位于 internal/sources/valkey/valkey.goSourceType valkey工具实现位于 internal/tools/valkey/valkey.goresourceType valkey二者通过init()中的Register机制注册到全局的 source / tool 注册表与仓库中其他几十个数据库集成保持同一套插件式架构。配置 Valkey 数据源在 MCP Toolbox 的配置文件如tools.yaml中Valkey 数据源使用kind: source声明。官方文档给出的最小可用示例来自 docs/en/integrations/valkey/source.md如下kind: source name: my-valkey-instance type: valkey address: - 127.0.0.1:6379 username: ${YOUR_USERNAME} password: ${YOUR_PASSWORD} # database: 0 # useGCPIAM: false # disableCache: false官方文档特别提示应使用${ENV_NAME}格式的环境变量替换来引用密钥而不是把密码等敏感信息硬编码进配置文件。这一机制与仓库统一的配置解析流程一致——数据源通过yaml.Decoder解码${...}占位符在配置加载阶段被替换为环境变量的实际值。数据源字段参考官方文档完整给出了 valkey 数据源的字段表整理如下fieldtyperequireddescriptiontypestringtrue必须为 valkey。address[]stringtrue要连接的 Valkey 实例端点列表。usernamestringfalse如果使用非默认用户在此指定用户名如果使用 Memorystore for Valkey请留空。passwordstringfalseValkey 实例的密码。databaseintfalse要连接的 Valkey 数据库不适用于集群cluster enabled实例默认数据库为0。useGCPIAMboolfalse如果使用 GCP 的 IAM 认证设为true默认为false。disableCacheboolfalse是否关闭客户端侧缓存client-side caching默认为false。源码印证字段结构与必填校验数据源字段与 internal/sources/valkey/valkey.go 中的Config结构体一一对应type Config struct { Name string yaml:name validate:required Type string yaml:type validate:required Address []string yaml:address validate:required Username string yaml:username Password string yaml:password Database int yaml:database UseGCPIAM bool yaml:useGCPIAM DisableCache bool yaml:disableCache }其中name、type、address三个字段带有validate:required标签与文档中 required 标记完全一致useGCPIAM、disableCache均为可选布尔字段缺省即false。从实现看disableCache会被直接透传给 valkey-go 客户端的ClientOption.DisableCache用于控制客户端侧缓存行为internal/sources/valkey/valkey.go默认不缓存。连接建立与连通性自检数据源初始化时initValkeyClient会完成三件事internal/sources/valkey/valkey.go根据useGCPIAM决定是否注入AuthCredentialsFn详见下一节调用 valkey-go 的valkey.NewClient创建客户端传入InitAddress即address列表、SelectDB即database、Username、Password等选项构建并执行一次PING命令client.B().Ping().Build()若PING失败则直接终止从而在启动阶段就完成连通性自检避免把连接不上的数据源暴露给后续工具调用。address是[]string类型支持配置多个端点这在连接集群或故障转移场景下尤其有用。使用 GCP Memorystore for Valkey 的 IAM 认证如果使用 GCP 的 Memorystore for Valkey 托管服务可以改用 IAM 认证而无需静态密码。操作分两步先在 GCP 侧为你的账号授予所需的 IAM 角色详见 Google Cloud Memorystore for Valkey 官方 IAM 认证文档然后把数据源配置中的useGCPIAM设为truekind: source name: my-valkey-instance type: valkey address: - 127.0.0.1:6379 useGCPIAM: true注意官方文档的约束使用 Memorystore for Valkey 时username字段应留空开启 IAM 认证时同样无需填写password认证凭据由运行时动态获取。源码印证IAM 令牌如何注入从源码看IAM 认证的实现非常直接internal/sources/valkey/valkey.go当r.UseGCPIAM为true时会构造一个AuthCredentialsFn每次认证时调用sources.GetIAMAccessToken(ctx)获取访问令牌并以Username: default、Password: token的形式作为认证凭据authFn func(valkey.AuthCredentialsContext) (valkey.AuthCredentials, error) { token, err : sources.GetIAMAccessToken(ctx) creds : valkey.AuthCredentials{Username: default, Password: token} if err ! nil { return creds, err } return creds, nil }这意味着使用 IAM 认证时实际连接的用户名固定为default密码为动态刷新的 GCP 访问令牌从而避免在配置文件中保存长期有效的静态密码。GetIAMAccessToken由 internal/sources 包统一提供与仓库中其他支持 GCP IAM 的数据库集成共用同一套令牌获取逻辑。定义 valkey 工具按序执行预定义命令数据源负责连得上工具则负责做什么。valkey 工具的核心能力是针对一个 valkey 数据源顺序执行一系列预定义的 Valkey 命令并把每个命令的执行结果聚合返回docs/en/integrations/valkey/tools/valkey-tool.md。每条命令用一个字符串数组表示数组第一个元素是命令名如SET、GET、HGETALL后续元素是该命令的参数。多个命令按配置顺序依次执行因此可以组合出先写后读先删再查等业务序列。动态命令参数$变量模板注入命令参数支持$variableName模板注解配置中以$开头的占位符会在运行时被工具的实际入参替换从而实现一个工具、多种调用。特别地数组类型的参数会被展开flatten成多个参数例如commands: - [SADD, userNames, $userNames] # Array will be flattened into multiple arguments. parameters: - name: userNames type: array description: The user names to be set.如果运行时输入的是字符串数组[Alice, Sid, Bob]则参数展开后最终执行的命令为[SADD, userNames, Alice, Sid, Bob]这正是SADD这类集合命令最常见的用法——一次把多个成员加入集合而不必为每个成员单独发一条命令。完整工具配置示例官方文档给出的 valkey 工具完整示例docs/en/integrations/valkey/tools/valkey-tool.md如下kind: tool name: user_data_tool type: valkey source: my-valkey-instance description: | Use this tool to interact with user data stored in Valkey. It can set, retrieve, and delete user-specific information. commands: - [SADD, userNames, $userNames] # Array will be flattened into multiple arguments. - [GET, $userId] parameters: - name: userId type: string description: The unique identifier for the user. - name: userNames type: array description: The user names to be set.配置要点source必须指向一个已定义的 valkey 数据源即前面kind: source配置中的name工具通过它获取客户端连接commands为命令列表按顺序执行description为必填项会被用作 MCP 工具清单manifest中的描述供 LLM 理解工具用途parameters声明工具的输入参数其中type支持string、array等类型array类型在展开时会把每个元素依次追加到命令参数位。源码印证参数替换与批量执行工具的参数替换逻辑位于 internal/tools/valkey/valkey.go 的replaceCommandsParams函数其核心行为与文档描述完全对应先把所有入参包装为带$前缀的映射paramMap : paramValues.AsMapWithDollarPrefix()再根据parameters声明建立占位符 - 参数类型的映射逐条命令、逐段参数扫描非占位符部分原样保留占位符若对应array类型则把数组逐项展开追加每个元素通过fmt.Sprintf(%s, item)字符串化其他类型直接替换为对应值嵌套数组只会展开一层源码注释明确说明例如[A, [B, C]]展开后变为[A, [B C]]避免无限递归。替换完成后工具调用数据源的RunCommand(ctx, commands)internal/sources/valkey/valkey.go执行所有命令通过 valkey-go 的DoMulti批量发送逐条解析响应——单条命令出错不会中断整批执行而是把error from executing command at index N: ...写入该位置的输出最终返回与命令数量等长的结果数组。这种设计保证了多命令序列的稳健性一条失败其余照常执行调用方可通过索引定位失败命令。测试与验证仓库为该集成提供了单元测试可作为配置写法的权威校验样例internal/tools/valkey/valkey_test.go 中的TestParseFromYamlvalkey用例验证了kind: tool的 YAML 能正确解析为valkey.Config其中命令支持[SET, greeting, hello, {{.name}}]与[GET, id]的组合参数声明会被解析为parameters.NewStringParameter(name, user name)集成测试位于 tests/valkey/valkey_test.go覆盖真实 Valkey 实例场景测试目录与其余数据库集成保持一致的组织方式。如果你想在本地快速验证配置解析可以参照测试用例的组织方式用go test ./internal/tools/valkey/运行对应单元测试。配置最佳实践与注意事项综合官方文档与源码落地时建议遵循以下几点敏感信息一律使用环境变量替换username、password等字段用${ENV_NAME}引用避免密钥进入版本库GCP IAM 场景下无需配置密码凭据由运行时动态获取安全性更高。集群实例注意字段适用性database字段不适用于集群cluster enabled实例配置前先确认目标实例类型集群场景直接省略该字段或保持默认。用PING自检前置数据源初始化阶段会执行PING地址不可达或认证失败会在启动阶段暴露便于快速定位问题而不是等到首次工具调用才报错。命令序列保持顺序敏感工具按配置顺序批量执行命令适合先写后读这类有先后依赖的业务但要注意DoMulti的批量语义若某条命令依赖上一条的返回值应在单个工具内配置完整的命令序列而不是依赖多次工具调用。数组参数只展开一层array类型参数会一次展开为多个命令参数适合SADD、DEL等多参数命令嵌套数组不会递归展开规划参数结构时需注意。总结MCP Toolbox 对 Valkey 的支持是一条数据源 命令工具的完整链路数据源层通过 internal/sources/valkey/valkey.go 管理连接、静态密码认证与 GCP IAM 认证并在初始化时用PING自检工具层通过 internal/tools/valkey/valkey.go 将预定义命令与$变量动态参数结合经DoMulti批量执行并聚合返回。参考官方文档 source.md 与 valkey-tool.md 中的 YAML 示例结合上述字段说明与源码行为即可快速为 MCP 客户端接入一套安全、可复用的 Valkey 操作能力。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考