自定义指令模板

Name: 1MCP Agent
Author: 1MCP

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

概述

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

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

在 Admin Console 中管理模板

打开 Admin Console > Instructions，无需直接编辑配置文件即可管理具名指令模板。每个模板包含两个相互独立的变体：

Initialization：在新的 MCP 客户端初始化时返回。
CLI：由 1mcp instructions 及其对应的 HTTP 端点渲染。

内置的 default 模板始终提供这两个变体。它受系统保护，不能编辑或删除，但可以克隆为新的托管模板。

编辑器支持以下工作流：

创建或克隆模板，并编辑任一变体。
保存草稿。即使某个变体包含无效的 Handlebars，草稿也可以保存，未完成的内容不会丢失。
校验两个变体，并使用显式的服务器上下文进行预览。
激活模板。只有两个变体都通过校验时才能激活。

同一时间只能有一个活动模板。活动模板不能删除；请先激活另一个模板。Admin Console 在真正删除前还会显示删除预览。

预览上下文与过滤

预览使用显式、临时的上下文。请选择目标客户端会使用的服务器，以及相同的 preset、tags 或高级 tag filter。预览会先应用过滤，再构建 {{servers}}、{{serverNames}} 和 {{filterContext}} 等变量。预览不会创建持久客户端会话，也不会更改活动模板。

当改动涉及共享变量时，请同时预览两个变体。Initialization 和 CLI 变体可以基于同一组过滤后的服务器数据有意生成不同结构。

运行时行为与回退

激活模板会更新后续渲染所用的配置。已经完成初始化的 MCP 会话继续保留其已收到的指令；新的 MCP 连接和之后执行的 1mcp instructions 会使用当前活动模板。

如果活动变体在渲染时失败，1MCP 会针对该输出面使用内置变体，并在 Admin 中记录结构化错误。活动选择会保留，便于运维人员检查和修复。cli 变体失败不会替换有效的 initialization 变体，反之亦然。

托管配置

Admin Console 将托管模板存储在 mcp.json 中：

json

{
  "instructionTemplates": {
    "team": {
      "initialization": "# {{title}}\n\n{{instructions}}",
      "cli": "先执行 `1mcp inspect <server>`，再执行 `1mcp run`。\n\n{{instructions}}"
    }
  },
  "activeInstructionTemplate": "team"
}

由 Admin 管理的发布状态

publishedInstructionTemplates 是 Admin 工作流维护的可选内部快照。当活动模板被保存为无效草稿时，它会保留上次激活的输出，并在重启后继续生效。请勿手动编辑该字段；应编辑 instructionTemplates 草稿，并使用 Activate 发布通过校验的变体。

不要在 instructionTemplates 中添加 default 条目；该标识保留给内置模板。activeInstructionTemplate 必须是 default，或某个已配置托管模板的标识。

当 activeInstructionTemplate 存在时，托管选择对两个输出面都具有更高优先级。当该字段不存在时，Initialization 保留下面介绍的旧版文件或 --instructions-template 行为，而 CLI 输出使用内置 CLI 模板。

迁移旧版模板

在 Admin Console 中使用 Import legacy template，将当前配置的旧版 Initialization 模板复制到一个具名草稿中。导入不会覆盖旧版文件，也不会激活该草稿。新模板会获得：

旧版内容作为 initialization 变体；
内置内容作为 cli 变体。

请检查并校验两个变体，使用预期的过滤上下文进行预览，然后激活托管模板。托管选择激活后，其优先级高于旧版 Initialization 模板。建议先保留旧版文件，验证新连接和 CLI 输出后，再按需移除旧的 serve 选项或文件。

模板变量

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

服务器状态变量

变量	类型	描述	示例
`{{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 选项指定自定义路径。

迁移到托管配置

如需使用受支持的配置工作流，请按照上面的说明将旧版文件导入托管模板。若要替换或抑制某个已配置服务器的指令，请使用服务器指令覆盖，而不是添加每客户端模板设置。

模板语法

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 呈现服务器指令。

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

模板示例

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

自定义指令模板 ​

概述 ​

在 Admin Console 中管理模板 ​

预览上下文与过滤 ​

运行时行为与回退 ​

托管配置 ​

迁移旧版模板 ​

模板变量 ​

服务器状态变量 ​

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

内容变量 ​

XML 样式服务器指令 ​

配置变量 ​

使用自定义模板 ​

命令行选项 ​

模板文件位置 ​

迁移到托管配置 ​

模板语法 ​

HTML 转义行为 ​

基本模板示例 ​

高级模板示例 ​

模板最佳实践 ​

1. 使用条件内容 ​

2. 处理复数形式 ​

3. 所有变量都未转义 ​

4. 提供上下文 ​

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

6. 解释 XML 标签格式 ​

7. 使其有帮助 ​

错误处理 ​

测试模板 ​

服务器指令覆盖 ​

模板示例 ​

自定义指令模板

概述

在 Admin Console 中管理模板

预览上下文与过滤

运行时行为与回退

托管配置

迁移旧版模板

模板变量

服务器状态变量

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

内容变量

XML 样式服务器指令

配置变量

使用自定义模板

命令行选项

模板文件位置

迁移到托管配置

模板语法

HTML 转义行为

基本模板示例

高级模板示例

模板最佳实践

1. 使用条件内容

2. 处理复数形式

3. 所有变量都未转义

4. 提供上下文

5. 使用单个服务器迭代

6. 解释 XML 标签格式

7. 使其有帮助

错误处理

测试模板

服务器指令覆盖

模板示例