自定义指令模板

1MCP 允许您自定义发送给 LLM 客户端的指令模板。这使您能够为代理添加品牌标识、提供自定义文档，或针对特定用例定制教育内容。

概述

默认情况下，1MCP 会生成教育性指令模板，帮助 LLM 了解如何有效使用代理。您可以使用自己的 Handlebars 模板覆盖此模板，包括：

自定义品牌和消息
针对您用例的具体指令
使用实时服务器数据进行变量替换
基于连接服务器的条件内容

模板变量

您的自定义模板可以访问以下变量：

服务器状态变量

变量	类型	描述	示例
`{{serverCount}}`	number	连接且有指令的服务器数量	`3`
`{{hasServers}}`	boolean	是否有任何服务器连接	`true`
`{{serverList}}`	string	服务器名称的换行分隔列表	`"api-server\nweb-server"`
`{{serverNames}}`	array	用于迭代的服务器名称数组	`["api-server", "web-server"]`
`{{servers}}`	array	用于详细迭代的服务器对象数组（包含所有服务器）	`[{name: "api-server", instructions: "...", hasInstructions: true}, {name: "no-docs", instructions: "", hasInstructions: false}]`
`{{pluralServers}}`	string	基于数量的"server"或"servers"	`"servers"`
`{{isAre}}`	string	基于数量的"is"或"are"	`"are"`

服务器对象（`{{servers}}` 数组）

{{servers}} 数组中的每个服务器对象包含：

属性	类型	描述
`name`	string	服务器名称（例如 "api-server"）
`instructions`	string	服务器的指令内容（无指令时为空字符串）
`hasInstructions`	boolean	此服务器是否有指令

注意：数组包含所有连接的服务器，即使它们没有指令。没有指令的服务器将具有 hasInstructions: false 和空字符串的 instructions。

重要：serverCount 和相关变量（serverList、serverNames）只包含有指令的服务器，而 servers 数组包含所有连接的服务器，无论它们是否有指令。

内容变量

变量	类型	描述
`{{instructions}}`	string	包装在 XML 样式标签中的所有服务器指令（未转义输出）
`{{filterContext}}`	string	过滤器描述或空字符串

XML 样式服务器指令

服务器指令被包装在 XML 样式标签中，以清楚地标识其来源和范围：

xml

<server-name>
服务器指令内容在此
</server-name>

这种格式有助于 LLM 理解哪些指令来自哪个服务器，并维护不同服务器功能之间的清晰边界。

配置变量

变量	类型	描述	默认值
`{{title}}`	string	模板的标题	`"1MCP - Model Context Protocol Proxy"`
`{{toolPattern}}`	string	工具命名模式	`"{server}_1mcp_{tool}"`
`{{examples}}`	array	工具示例数组	参见示例参考

使用自定义模板

命令行选项

使用 serve 命令的 --instructions-template 选项：

bash

# 使用特定的模板文件
1mcp serve --instructions-template ./my-template.md

# 使用配置目录中的默认模板
1mcp serve  # 在配置目录中查找 instructions-template.md

模板文件位置

默认情况下，1MCP 会在您的配置目录中查找 instructions-template.md：

macOS/Linux: ~/.config/1mcp/instructions-template.md
Windows: %APPDATA%/1mcp/instructions-template.md

您也可以使用 CLI 选项指定自定义路径。

配置覆盖

您还可以通过扩展配置系统在每个客户端的 MCP 服务器配置中包含模板选项来覆盖模板设置。

模板语法

1MCP 使用 Handlebars 作为模板引擎，提供以下功能：

变量替换: {{variable}}
条件内容: {{#if condition}}...{{/if}}
循环: {{#each array}}...{{/each}}
辅助函数: 内置逻辑和比较运算符

HTML 转义行为

重要: 1MCP 默认配置 Handlebars 时使用 noEscape: true，这意味着：

所有变量都未转义: {{instructions}} 输出原始内容而不进行 HTML 实体转义
XML 标签清晰渲染: <server-name> 保持为 <server-name>（不是 <server-name>）
无需三重括号: 所有内容使用常规 {{variable}} 语法
适合 LLM 消费: 输出清晰且易于 AI 处理

这种配置专门为 LLM 指令模板设计，HTML 转义会使内容可读性降低且更难被 AI 模型解析。

基本模板示例

markdown

# {{title}}

{{#if hasServers}}
You have {{serverCount}} {{pluralServers}} connected:

{{#each serverNames}}

- ✅ {{this}}
  {{/each}}

## Server Instructions

The following sections contain instructions from each connected MCP server. Each server's instructions are wrapped in XML-like tags to clearly identify their source and scope.

{{#each servers}}
{{#if hasInstructions}}
<{{name}}>
{{instructions}}
</{{name}}>

{{/if}}
{{/each}}

## Tool Usage

Tools follow the pattern: `{{toolPattern}}`
{{else}}
⏳ No servers are currently connected.
{{/if}}

高级模板示例

markdown

# {{title}}

{{#if hasServers}}
You are interacting with 1MCP, a proxy server that aggregates capabilities from multiple MCP (Model Context Protocol) servers. 1MCP acts as a unified gateway, allowing you to access tools and resources from various specialized MCP servers through a single connection.

## How 1MCP Works

- **Unified Access**: Connect to multiple MCP servers through one proxy
- **Tool Aggregation**: All tools are available with the naming pattern \`{{toolPattern}}\`
- **Resource Sharing**: Access files, data, and capabilities across different servers
- **Intelligent Routing**: Your requests are automatically routed to the appropriate servers

## Currently Connected Servers

{{serverCount}} MCP {{pluralServers}} {{isAre}} currently available{{filterContext}}:

{{serverList}}

## Available Capabilities

All tools from connected servers are accessible using the format: \`{{toolPattern}}\`

Examples:
{{#each examples}}

- \`{{name}}\` - {{description}}
  {{/each}}

## Server-Specific Instructions

The following sections contain instructions from each connected MCP server. Each server's instructions are wrapped in XML-like tags (e.g., \`<server-name>instructions</server-name>\`) to clearly identify their source and scope.

{{#each servers}}
{{#if hasInstructions}}
<{{name}}>
{{instructions}}
</{{name}}>

{{/if}}
{{/each}}

## Tips for Using 1MCP

- Tools are namespaced by server to avoid conflicts

{{else}}
You are interacting with 1MCP, a proxy server that aggregates capabilities from multiple MCP (Model Context Protocol) servers.

## Current Status

No MCP servers are currently connected. 1MCP is ready to connect to servers and provide unified access to their capabilities once they become available.

## What 1MCP Provides

- **Unified Access**: Connect to multiple MCP servers through one proxy
- **Tool Aggregation**: Access tools using the pattern \`{{toolPattern}}\`
- **Resource Sharing**: Share files, data, and capabilities across servers
- **Intelligent Routing**: Automatic request routing to appropriate servers

1MCP will automatically detect and connect to available MCP servers. Once connected, their tools and capabilities will become available through the unified interface.
{{/if}}`

模板最佳实践

1. 使用条件内容

在显示服务器特定内容之前始终检查服务器是否可用：

text

{{#if hasServers}}
  <!-- 服务器特定内容 -->
{{else}}
  <!-- 无服务器消息 -->
{{/if}}

2. 处理复数形式

使用提供的辅助变量进行正确的语法：

text

{{serverCount}} 个 {{pluralServers}} {{isAre}} 可用

3. 所有变量都未转义

由于 1MCP 使用 noEscape: true，所有变量都输出原始内容而不进行 HTML 转义：

text

{{instructions}}    <!-- 输出原始内容（未转义） -->
{{name}}           <!-- 按原样输出服务器名称 -->
{{title}}          <!-- 所有变量渲染时都不转义 -->

这意味着像 <server-name> 这样的 XML 标签将在输出中清晰渲染，非常适合 LLM 消费。

4. 提供上下文

包含有关过滤的信息（当激活时）：

text

{{serverCount}} 个服务器可用{{filterContext}}

5. 使用单个服务器迭代

为获得最大灵活性，迭代单个服务器而不是使用连接的指令：

text

{{#each servers}}
{{#if hasInstructions}}
### {{name}} 功能
<{{name}}>
{{instructions}}
</{{name}}>
{{else}}
### {{name}}
此服务器已连接但没有可用的指令。
{{/if}}
{{/each}}

这使您可以控制每个服务器的格式、条件包含和自定义逻辑。您可以对有指令和没有指令的服务器进行不同的处理。

6. 解释 XML 标签格式

通过提供上下文帮助 LLM 理解 XML 标签结构：

text

## 服务器指令

每个服务器的指令都包装在 XML 样式标签中（例如 `<server-name>content</server-name>`），以清楚地标识其来源和范围。

7. 使其有帮助

包含示例和使用技巧，帮助 LLM 理解您的特定设置：

text

{{#each examples}}
- `{{name}}` - {{description}}
{{/each}}

错误处理

如果您的自定义模板有语法错误或渲染失败：

回退: 1MCP 自动回退到默认模板
日志记录: 错误被记录用于调试
验证: 模板编译错误被捕获并报告

测试模板

您可以通过以下方式测试模板：

启动服务器: 使用您的模板并检查日志
连接客户端: 验证指令是否正确渲染
使用不同的过滤器: 使用各种服务器组合进行测试
检查边缘情况: 测试无服务器、单个服务器等情况

服务器指令覆盖

自定义模板允许您使用 Handlebars 逻辑覆盖、过滤或自定义服务器指令。这使您可以完全控制如何向 LLM 呈现服务器指令。

有关服务器指令覆盖的详细指导，包括模式、技术和示例，请参见专门的服务器指令覆盖指南。

模板示例

有关不同用例的完整模板示例，请参见模板示例页面。

自定义指令模板 ​

概述 ​

模板变量 ​

服务器状态变量 ​

服务器对象（{{servers}} 数组） ​

内容变量 ​

XML 样式服务器指令 ​

配置变量 ​

使用自定义模板 ​

命令行选项 ​

模板文件位置 ​

配置覆盖 ​

模板语法 ​

HTML 转义行为 ​

基本模板示例 ​

高级模板示例 ​

模板最佳实践 ​

1. 使用条件内容 ​

2. 处理复数形式 ​

3. 所有变量都未转义 ​

4. 提供上下文 ​

5. 使用单个服务器迭代 ​

6. 解释 XML 标签格式 ​

7. 使其有帮助 ​

错误处理 ​

测试模板 ​

服务器指令覆盖 ​

模板示例 ​

自定义指令模板

概述

模板变量

服务器状态变量

服务器对象（`{{servers}}` 数组）

内容变量

XML 样式服务器指令

配置变量

使用自定义模板

命令行选项

模板文件位置

配置覆盖

模板语法

HTML 转义行为

基本模板示例

高级模板示例

模板最佳实践

1. 使用条件内容

2. 处理复数形式

3. 所有变量都未转义

4. 提供上下文

5. 使用单个服务器迭代

6. 解释 XML 标签格式

7. 使其有帮助

错误处理

测试模板

服务器指令覆盖

模板示例