服务器指令覆盖

自定义模板最强大的功能之一是能够使用 Handlebars 逻辑覆盖、过滤或自定义服务器指令。这使您可以完全控制如何向 LLM 呈现服务器指令。

基本服务器指令覆盖模式

1. 完全替换服务器指令

您可以用自己的自定义内容替换原始服务器指令：

{{#each servers}}
{{#if hasInstructions}}
<{{name}}>
{{#if (eq name "problematic-server")}}

# {{name}} 的自定义指令

此服务器已使用简化指令进行自定义。
使用这些工具：tool1、tool2、tool3
{{else}}
{{instructions}}
{{/if}}
</{{name}}>
{{/if}}
{{/each}}

2. 过滤特定服务器

通过添加条件完全跳过某些服务器：

{{#each servers}}
{{#unless (eq name "unwanted-server")}}
{{#if hasInstructions}}
<{{name}}>
{{instructions}}
</{{name}}>
{{/if}}
{{/unless}}
{{/each}}

3. 为服务器指令添加前缀或后缀

使用附加上下文增强服务器指令：

{{#each servers}}
{{#if hasInstructions}}
<{{name}}>
⚠️ **服务器：{{name}}** - 在生产环境中谨慎使用

{{instructions}}

📝 **注意**：所有 {{name}} 操作都会记录用于审计。
</{{name}}>
{{/if}}
{{/each}}

4. 基于服务器名称的条件指令

根据服务器类型或命名模式进行不同处理：

{{#each servers}}
{{#if hasInstructions}}
<{{name}}>
{{#if (startsWith name "test-")}}

# 测试环境服务器：{{name}}

⚠️ 这是一个测试服务器。结果可能不可靠。

{{instructions}}
{{else if (startsWith name "prod-")}}

# 生产环境服务器：{{name}}

✅ 这是一个生产服务器。所有操作都受到监控。

{{instructions}}
{{else}}
{{instructions}}
{{/if}}
</{{name}}>
{{/if}}
{{/each}}

高级覆盖技术

1. 服务器指令转换

使用自定义逻辑转换指令：

{{#each servers}}
{{#if hasInstructions}}
<{{name}}>
{{#if (eq name "verbose-server")}}

# 简化的 {{name}} 指令

{{! 用简化版本替换冗长的指令 }}
此服务器提供文件操作。主要工具：

- read_file：读取文件内容
- write_file：写入文件内容
- list_files：列出目录内容
  {{else}}
  {{instructions}}
  {{/if}}
  </{{name}}>
  {{/if}}
  {{/each}}

2. 合并多个服务器

将多个服务器的指令合并到统一部分：

## 文件操作

{{#each servers}}
{{#if (or (eq name "filesystem") (eq name "storage"))}}
{{#if hasInstructions}}

### {{name}} 功能

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

## 数据库操作

{{#each servers}}
{{#if (or (eq name "database") (eq name "sql"))}}
{{#if hasInstructions}}

### {{name}} 功能

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

## 其他服务

{{#each servers}}
{{#unless (or (eq name "filesystem") (eq name "storage") (eq name "database") (eq name "sql"))}}
{{#if hasInstructions}}
<{{name}}>
{{instructions}}
</{{name}}>
{{/if}}
{{/unless}}
{{/each}}

3. 基于优先级的服务器排序

按重要性或偏好重新排序服务器：

## 高优先级服务器

{{#each servers}}
{{#if (or (eq name "critical-server") (eq name "primary-db"))}}
{{#if hasInstructions}}
<{{name}}>
🔥 **高优先级服务器**

{{instructions}}
</{{name}}>
{{/if}}
{{/if}}
{{/each}}

## 标准服务器

{{#each servers}}
{{#unless (or (eq name "critical-server") (eq name "primary-db"))}}
{{#if hasInstructions}}
<{{name}}>
{{instructions}}
</{{name}}>
{{/if}}
{{/unless}}
{{/each}}

用于服务器覆盖的 Handlebars 辅助函数

您可以使用这些内置的 Handlebars 辅助函数进行复杂逻辑：

辅助函数	描述	使用示例
eq	相等比较	{{#if (eq name "server1")}}
ne	不等比较	{{#if (ne name "server1")}}
or	逻辑或	{{#if (or (eq name "a") (eq name "b"))}}
and	逻辑与	{{#if (and hasInstructions (ne name "skip"))}}
startsWith	字符串开头匹配	{{#if (startsWith name "test-")}}
endsWith	字符串结尾匹配	{{#if (endsWith name "-dev")}}
contains	字符串包含	{{#if (contains instructions "deprecated")}}

实际覆盖示例

示例 1：特定环境指令

{{#each servers}}
{{#if hasInstructions}}
<{{name}}>
{{#if (endsWith name "-dev")}}

# 开发环境：{{name}}

⚠️ **开发模式**：此服务器仅用于开发。

{{instructions}}

**开发注意事项：**

- 调试已启用
- 所有操作都会详细记录
- 数据可能每天重置
  {{else if (endsWith name "-prod")}}

# 生产环境：{{name}}

✅ **生产环境**：此服务器处理实时数据。

{{instructions}}

**生产准则：**

- 所有操作都会被审计
- 强制执行速率限制
- 遵循安全协议
  {{else}}
  {{instructions}}
  {{/if}}
  </{{name}}>
  {{/if}}
  {{/each}}

示例 2：服务器功能分组

# 按类别分类的服务器功能

## 数据存储和检索

{{#each servers}}
{{#if (or (contains name "db") (contains name "storage") (contains name "file"))}}
{{#if hasInstructions}}

### {{name}}

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

## 通信和网络

{{#each servers}}
{{#if (or (contains name "web") (contains name "api") (contains name "http"))}}
{{#if hasInstructions}}

### {{name}}

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

## 处理和计算

{{#each servers}}
{{#unless (or (contains name "db") (contains name "storage") (contains name "file") (contains name "web") (contains name "api") (contains name "http"))}}
{{#if hasInstructions}}

### {{name}}

{{instructions}}
{{/if}}
{{/unless}}
{{/each}}

测试您的模板覆盖

要测试您的模板覆盖并确保它们正常工作：

1. 创建测试模板

创建一个简单的测试模板来验证您的覆盖逻辑：

# 模板测试

{{#if hasServers}}
发现 {{serverCount}} 个带有指令的服务器。

{{#each servers}}
服务器：{{name}}（有指令：{{hasInstructions}}）
{{#if hasInstructions}}
指令长度：{{instructions.length}} 字符
{{/if}}

{{/each}}
{{else}}
未找到服务器。
{{/if}}

2. 使用 CLI 测试

将您的模板保存到文件并测试：

# 创建测试模板
echo "{{#each servers}}{{name}}: {{hasInstructions}}{{/each}}" > test-template.md

# 使用您的模板测试
1mcp serve --instructions-template test-template.md

# 连接客户端查看渲染输出

3. 验证步骤

1. 语法检查：确保 Handlebars 语法有效
2. 逻辑验证：使用不同的服务器配置测试条件逻辑
3. 边缘情况：测试无服务器、单个服务器、没有指令的服务器
4. 性能：监控多个服务器时的渲染时间

4. 常见测试场景

针对这些常见场景测试您的模板：

• 无服务器连接：模板应优雅地处理空状态
• 混合服务器类型：一些有指令，一些没有
• 长指令：确保格式保持可读
• 特殊字符：测试包含特殊字符的服务器名称
• 多种环境：测试 dev/staging/prod 服务器命名模式

服务器指令覆盖技巧

1. 测试您的逻辑：先使用简单条件，然后构建复杂性
2. 保留原始内容：考虑保持原始指令可用并进行修改
3. 使用注释：Handlebars 注释 {{! comment }} 有助于记录您的逻辑
4. 验证服务器名称：检查服务器名称是否符合您期望的模式
5. 处理边缘情况：考虑没有指令或意外名称的服务器
6. 性能：模板中的复杂逻辑在服务器数量多时可能减慢渲染速度
7. 文档：为团队成员记录您的覆盖逻辑
8. 版本控制：将模板保存在版本控制中以跟踪更改

模板问题排查

常见问题和解决方案

1. 模板未加载：检查文件路径和权限
2. 语法错误：使用验证器验证 Handlebars 语法
3. 逻辑不工作：逐步测试各个条件
4. 性能问题：简化复杂的嵌套循环
5. 输出格式：检查额外的空白或缺少的换行符

调试模板变量

使用此调试模板检查可用变量：

# 调试模板

## 可用变量

- serverCount: {{serverCount}}
- hasServers: {{hasServers}}
- serverList: {{serverList}}
- toolPattern: {{toolPattern}}
- title: {{title}}

## 服务器详情

{{#each servers}}

### 服务器 {{@index}}：{{name}}

- 有指令：{{hasInstructions}}
- 指令长度：{{instructions.length}}
  {{#if hasInstructions}}
- 前 100 个字符：{{substring instructions 0 100}}...
  {{/if}}

{{/each}}

此模板将帮助您了解哪些数据可用以及它们的结构。