企业官网建设流程全解析

MCP Toolbox Prompts 配置指南：可复用提示模板、参数插值与 Gemini CLI 斜杠命令实战

【免费下载链接】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 的使用者与配置开发者，围绕tools.yaml中kind: prompt声明式配置展开，系统讲解 prompt 的完整 Schema、消息与参数结构、占位符插值机制，并给出与 Gemini CLI 集成生成自定义斜杠命令的完整工作流。读完本文，你将能够编写单消息与多消息的自定义提示模板，理解其底层解析与插值实现，并让它在支持 MCP 的客户端中一键复用。

在 MCP Toolbox 中，prompt代表一个可复用的提示模板：它定义了一段（或一组）面向大语言模型（LLM）的结构化消息，以及可供客户端传入的命名参数。Toolbox 服务器实现了 Model Context Protocol（MCP）规范中的prompts/list与prompts/get两个方法，客户端因此可以发现并检索这些提示。本文以 Prompts 配置文档 为骨架，结合 internal/prompts 下的源码实现，从 YAML 声明、Schema 字段、参数插值到客户端集成逐层展开。

什么是 Toolbox 中的 Prompt

一个prompt本质上是一条或一系列消息的模板，它最终会被发送给 LLM。与把指令硬编码在客户端相比，prompt 的价值在于：

• 复用：同一条提示（如代码审查、角色扮演、SQL 生成）可以在不同会话中被反复调用；
• 参数化：通过{{.argument_name}}占位符，让每次调用的内容随入参变化；
• 标准化：通过 MCP 的prompts/list（列出）和prompts/get（获取并插值）协议暴露给任何兼容客户端。

一个最基本的 prompt 声明如下（来自 Prompts 配置文档）：

kind: prompt name: code_review description: "Asks the LLM to analyze code quality and suggest improvements." messages: - content: "Please review the following code for quality, correctness, and potential improvements: \n\n{{.code}}" arguments: - name: "code" description: "The code to review"

该配置定义了一个名为code_review的提示模板：消息内容中包含{{.code}}占位符，客户端在调用prompts/get时提供code实参，服务器将其替换为真实代码后返回最终提示。

用 Groups 组织 Prompt

提示可以借助 Groups 配置 进行归类。当客户端连接到某个 group 的端点时，prompts/list只返回该 group 内的 prompts；而默认端点（/mcp）返回全部 prompts。典型声明如下：

kind: group name: data_analyst description: Tools, prompts, and resources for exploratory data analysis. prompts: - summarize_results

这意味着你既可以在全局范围提供通用提示，也可以为特定角色（如数据分析师、管理员）定制精简的提示集合。

Prompt Schema 字段详解

关于type字段，在源码中可以看到其处理逻辑：internal/prompts/prompts.go 的DecodeConfig会先按type查找已注册的 prompt 工厂；当type为空字符串时自动回退为"custom"，若类型仍无法识别则返回unknown prompt type错误。这一设计表明：

• type 是可选的，缺省即custom；
• prompt 类型是可扩展的，任意类型可通过Register注册自己的配置工厂（prompts.go）；
• 当前仓库内置的默认类型为custom，详见 Custom Prompts 文档。

messages是唯一必填字段，必须包含一条或多条消息对象；arguments定义可插值的参数列表，二者均在下文详述。

Message Schema：角色与内容

role合法取值仅"user"与"assistant"。这一约束在 internal/prompts/messages.go 的Message.UnmarshalYAML中强制校验：若未指定role则默认补为"user"，若填写了其他值则直接报错invalid role。content支持 Go 模板风格的占位符语法{{.argument_name}}。

Argument Schema：参数即 Parameter

Argument 可以复用 Tools 参数规范 中的任意 Parameter 类型；如果未指定type，默认是string。

这一默认行为的底层实现在 internal/prompts/arguments.go：Arguments.UnmarshalYAML对每个参数项先检查是否存在type字段，缺失时写入parameters.TypeString，再调用与 tools 共用的parameters.ParseParameter完成解析。这意味着 prompt 参数与 tool 参数共享同一套类型系统，可用的类型包括：

参数还可以声明required（缺省视为必填，见 parameters.go 的GetRequired）、default、allowedValues、excludedValues等公共字段，从而在插值前完成类型转换与取值校验。

实战示例：从单消息到多消息提示

单消息提示

单消息模板适合"一条指令 + 若干输入"的场景，例如上文code_review。此处再给出带参数描述与多参数的完整版本：

kind: prompt name: code_review description: "Asks the LLM to analyze code quality and suggest improvements." messages: - content: "Please review the following code for quality, correctness, and potential improvements: \n\n{{.code}}" arguments: - name: "code" description: "The code to review"

多消息提示

通过多条消息可以搭建更复杂的对话上下文，例如角色扮演场景（来自 Custom Prompts 文档）：

kind: prompt name: roleplay_scenario description: "Sets up a roleplaying scenario with initial messages." arguments: - name: "character" description: "The character the AI should embody." - name: "situation" description: "The initial situation for the roleplay." messages: - role: "user" content: "Let's roleplay. You are {{.character}}. The situation is: {{.situation}}" - role: "assistant" content: "Okay, I understand. I am ready. What happens next?"

这里第一条消息（user）携带两个参数占位符，第二条消息（assistant）给出开场白。客户端传入character与situation后，服务器返回两条完整消息，为 LLM 提供明确的角色设定与初始情境。

插值机制：Go 模板的底层实现

当客户端调用prompts/get传入参数值后，服务器需要把{{.xxx}}占位符替换为真实值。这条链路在源码中清晰可见：

1. custom.go 中Prompt.SubstituteParams委托给prompts.SubstituteMessages；
2. messages.go 的SubstituteMessages遍历每条消息，调用parameters.ResolveTemplateParams执行替换；
3. parameters.go 使用标准库text/template解析消息内容，并以参数名到值的映射作为模板上下文执行，最终返回替换后的字符串。

该实现还额外注册了array模板函数：当消息中需要以逗号分隔形式输出字符串数组参数时，可用{{array .tag}}形式将其渲染为a, b, c（对应 ConvertArrayParamToString）。这意味着除简单标量外，数组参数同样可以直接进入模板渲染。

从调用链可进一步看出，prompts/get处理流程包含参数解析（ParseArgs，完成类型转换、默认值与必填校验）与模板插值（SubstituteParams）两个阶段，二者共同保证了最终提示内容既符合参数约束、又完成占位符替换。

与 Gemini CLI 集成：把 Prompt 变成斜杠命令

在 tools.yaml 等配置文件中定义的 prompts 可以与 Gemini CLI 无缝集成，自动成为 CLI 中的自定义斜杠命令。完整工作流如下：

1. 发现（Discovery）：Gemini CLI 连接 Toolbox 服务器后，自动调用prompts/list发现所有可用提示；

2. 转换（Conversion）：每个被发现的 prompt 被转换为对应的斜杠命令。例如名为code_review的 prompt 变成 CLI 中的/code_review命令；

3. 执行（Execution）：用户直接执行该命令，并通过--参数名形式传入实参：

   /code_review --code="def hello():\n print('world')"

4. 插值（Interpolation）：参数收集完毕后，CLI 调用prompts/get并携带你提供的值，取回完成插值的最终提示，例如：

   Please review the following code for quality, correctness, and potential improvements: def hello(): print('world')

5. 响应（Response）：完整的提示被发送给 Gemini 模型，模型的回答直接显示在 CLI 中。

这套流程意味着：你只需在 YAML 中声明一次 prompt，即可在 Gemini CLI 中获得一个类型安全、参数自动校验的命令入口，无需在客户端侧重复编写提示逻辑。

Types of prompts：Custom 是默认类型

custom是用户自定义、通过 MCP 服务器对外暴露的提示类型，也是当前默认且内置的类型。其定义位于 Custom Prompts 文档，源码实现在 internal/prompts/custom/custom.go：

• 通过init()注册类型名"custom"与对应配置工厂（custom.go）；
• Config结构体直接对应 YAML 中的name、description、messages、arguments四个字段（custom.go）；
• Initialize生成带描述与参数清单的Manifest，用于prompts/list时向客户端暴露元信息（custom.go）；
• 其 Schema 与默认 prompt 一致：type必须为"custom"，messages必填，description、arguments可选；Message Schema 与 Argument Schema 均参照 Prompts 主文档。

从注册机制（prompts.go）可以推断，prompt 类型体系是开放可扩展的：后续若新增其他内置类型，只需以同样方式注册新的工厂函数即可，配置文件中的type字段随之生效，无需改动协议层代码。

小结与进一步阅读

围绕kind: prompt，本文覆盖了从 YAML 声明、Schema 字段、参数与消息结构、Go 模板插值原理，到 Gemini CLI 斜杠命令集成与custom类型的完整知识链。建议按以下路径继续深入：

• 查看 Prompts 配置主文档 与 Custom Prompts 文档 获取权威字段说明；
• 阅读 internal/prompts/prompts.go、custom/custom.go、messages.go、arguments.go 理解类型注册、校验与插值实现，配套的 prompts_test.go、custom_test.go、messages_test.go、arguments_test.go 提供了丰富的解析与插值用例；
• 如需了解参数类型系统全貌，参见 tools 参数规范 与 internal/util/parameters；
• 若要按角色组织提示集合，参见 Groups 配置文档。

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