# 模板变量参考

本页面提供了自定义指令模板中所有可用变量的完整参考。

## HTML 转义行为

**重要**: 1MCP 默认配置 Handlebars 时使用 `noEscape: true`，这意味着所有模板变量都输出未转义的内容。这专门为 LLM 指令模板设计，HTML 转义会干扰可读性和 AI 解析。

- **所有变量都未转义**: 所有内容使用常规 <span v-pre>`{{variable}}`</span> 语法
- **XML 标签清晰渲染**: `<server-name>` 输出为 `<server-name>`（不是 HTML 实体）
- **无需三重括号**: <span v-pre>`{{instructions}}`</span> 直接输出原始内容

## 服务器状态变量

### <span v-pre>`{{serverCount}}`</span>

- **类型**: `number`
- **描述**: 连接且有指令的服务器数量（旧版 - 保留用于向后兼容）
- **示例**: `3`
- **注意**: 仅计算具有非空指令的服务器。新模板请使用 `instructionalServerCount`。

### <span v-pre>`{{instructionalServerCount}}`</span>

- **类型**: `number`
- **描述**: 连接且有指令的服务器数量（`serverCount` 的更清晰名称）
- **示例**: `3`
- **注意**: 仅计算具有非空指令的服务器

### <span v-pre>`{{connectedServerCount}}`</span>

- **类型**: `number`
- **描述**: 连接的服务器总数（包括没有指令的服务器）
- **示例**: `5`
- **注意**: 计算所有连接的服务器，无论是否有指令

### <span v-pre>`{{hasServers}}`</span>

- **类型**: `boolean`
- **描述**: 是否有任何有指令的服务器连接
- **示例**: `true`
- **用法**: 模板逻辑的主要条件（与 `hasInstructionalServers` 相同）

### <span v-pre>`{{hasInstructionalServers}}`</span>

- **类型**: `boolean`
- **描述**: 是否有任何有指令的服务器连接
- **示例**: `true`
- **用法**: 显示基于指令内容的主要条件

### <span v-pre>`{{serverList}}`</span>

- **类型**: `string`
- **描述**: 服务器名称的换行分隔列表（字母顺序）
- **示例**: `"api-server\ndatabase-server\nweb-server"`
- **用法**: 用于简单文本列表

### <span v-pre>`{{serverNames}}`</span>

- **类型**: `array<string>`
- **描述**: 用于迭代的服务器名称数组
- **示例**: `["api-server", "database-server", "web-server"]`
- **用法**: 与 <span v-pre>`{{#each}}`</span> 辅助函数一起用于自定义格式化

### <span v-pre>`{{servers}}`</span>

- **类型**: `array<ServerData>`
- **描述**: 用于详细迭代和条件逻辑的服务器对象数组
- **结构**:
  ```typescript
  interface ServerData {
    name: string; // 服务器名称（例如 "api-server"）
    instructions: string; // 服务器指令内容
    hasInstructions: boolean; // 此服务器是否有指令
  }
  ```
- **用法**: 与 <span v-pre>`{{#each}}`</span> 一起使用以获得最大的模板灵活性
- **示例**:

::: v-pre

```text
{{#each servers}}
{{#if hasInstructions}}
### {{name}} 服务器
<{{name}}>
{{instructions}}
</{{name}}>
{{/if}}
{{/each}}
```

:::

### <span v-pre>`{{pluralServers}}`</span>

- **类型**: `string`
- **描述**: 基于有指令服务器数量的语法正确的单数/复数形式
- **值**: `"server"`（instructionalServerCount = 1）或 `"servers"`（instructionalServerCount ≠ 1）
- **示例**: `"servers"`

### <span v-pre>`{{isAre}}`</span>

- **类型**: `string`
- **描述**: 基于有指令服务器数量的语法正确的动词形式
- **值**: `"is"`（instructionalServerCount = 1）或 `"are"`（instructionalServerCount ≠ 1）
- **示例**: `"are"`

### <span v-pre>`{{connectedPluralServers}}`</span>

- **类型**: `string`
- **描述**: 基于连接服务器总数的语法正确的单数/复数形式
- **值**: `"server"`（connectedServerCount = 1）或 `"servers"`（connectedServerCount ≠ 1）
- **示例**: `"servers"`

### <span v-pre>`{{connectedIsAre}}`</span>

- **类型**: `string`
- **描述**: 基于连接服务器总数的语法正确的动词形式
- **值**: `"is"`（connectedServerCount = 1）或 `"are"`（connectedServerCount ≠ 1）
- **示例**: `"are"`

## 内容变量

### <span v-pre>`{{instructions}}`</span>

- **类型**: `string`（未转义）
- **描述**: 包装在 XML 样式标签中的所有服务器指令
- **格式**: `<server-name>\n指令...\n</server-name>`
- **用法**: 使用常规 <span v-pre>`{{instructions}}`</span> 语法（默认未转义）
- **示例**:

  ```xml
  <api-server>
  用于后端服务的 API 服务器指令
  </api-server>

  <web-server>
  用于前端开发的网页服务器指令
  </web-server>
  ```

### <span v-pre>`{{filterContext}}`</span>

- **类型**: `string`
- **描述**: 活动过滤的描述，如果没有则为空字符串
- **示例**:
  - `""`（无过滤）
  - `" (按标签过滤: backend, api)"`
  - `" (按高级表达式过滤)"`
  - `" (按预设过滤)"`

## 配置变量

### <span v-pre>`{{title}}`</span>

- **类型**: `string`
- **描述**: 指令模板的标题
- **默认值**: `"1MCP - Model Context Protocol Proxy"`
- **可自定义**: 可以在配置中覆盖
- **示例**: `"我的自定义 MCP 网关"`

### <span v-pre>`{{toolPattern}}`</span>

- **类型**: `string`
- **描述**: 代理使用的工具命名模式
- **默认值**: `"{server}_1mcp_{tool}"`
- **可自定义**: 可以在配置中覆盖
- **示例**: `"{server}::{tool}"`

### <span v-pre>`{{examples}}`</span>

- **类型**: `array<ToolExample>`
- **描述**: 用于文档的工具示例数组
- **结构**:
  ```typescript
  interface ToolExample {
    name: string; // 应用了模式的工具名称
    description: string; // 工具的功能
  }
  ```

#### 默认示例 {#default-examples}

| 工具名称                    | 描述                       |
| --------------------------- | -------------------------- |
| `filesystem_1mcp_read_file` | 通过文件系统服务器读取文件 |
| `web_1mcp_search`           | 通过网页服务器搜索网页     |
| `database_1mcp_query`       | 通过数据库服务器查询数据库 |

#### 自定义示例

您可以在配置中提供自定义示例：

```json
{
  "examples": [
    {
      "name": "custom_1mcp_analyze",
      "description": "通过自定义服务器分析数据"
    },
    {
      "name": "monitor_1mcp_check",
      "description": "通过监控服务器检查系统健康"
    }
  ]
}
```

## 变量使用示例

### 基本替换

::: v-pre

```text
连接到 {{connectedServerCount}} 个 {{connectedPluralServers}}
有指令的: {{instructionalServerCount}} 个 {{pluralServers}}
```

:::

输出: `连接到 5 个服务器`
输出: `有指令的: 3 个服务器`

### 条件内容

::: v-pre

```text
{{#if hasServers}}
  {{connectedServerCount}} 个 {{connectedPluralServers}} 已连接
  {{#if hasInstructionalServers}}
    {{instructionalServerCount}} 个 {{pluralServers}} 正在提供指令
  {{else}}
    暂无服务器提供指令
  {{/if}}
{{else}}
  没有连接服务器
{{/if}}
```

:::

### 服务器迭代（简单）

::: v-pre

```text
{{#each serverNames}}
- 服务器: {{this}}
{{/each}}
```

:::

### 服务器迭代（详细）

::: v-pre

```text
{{#each servers}}
{{#if hasInstructions}}
#### {{name}} 功能
<{{name}}>
{{instructions}}
</{{name}}>
{{/if}}
{{/each}}
```

:::

### 工具示例

::: v-pre

```text
可用工具:
{{#each examples}}
- `{{name}}`: {{description}}
{{/each}}
```

:::

### 复杂模板

::: v-pre

```text
# {{title}}

## 状态: {{#if hasServers}}✅ 已连接{{else}}⏳ 等待中{{/if}}

{{#if hasServers}}
**{{connectedServerCount}} 个 {{connectedPluralServers}} 已连接**{{filterContext}}

### 服务器
{{#each serverNames}}
- 🔧 {{this}}
{{/each}}

{{#if hasInstructionalServers}}
### 指令
{{instructions}}

### 示例工具
{{#each examples}}
- `{{name}}` - {{description}}
{{/each}}

*工具使用模式: `{{toolPattern}}`*
{{else}}
*服务器已连接但尚未提供指令*
{{/if}}
{{else}}
等待服务器连接...
{{/if}}
```

:::

## 变量范围和上下文

### 过滤影响

当过滤激活时，变量反映过滤的子集：

- <span v-pre>`{{connectedServerCount}}`</span> = 所有过滤后的服务器数量
- <span v-pre>`{{instructionalServerCount}}`</span> = 有指令的过滤后服务器数量
- <span v-pre>`{{serverNames}}`</span> = 仅过滤后的服务器名称
- <span v-pre>`{{instructions}}`</span> = 仅来自过滤后服务器的指令
- <span v-pre>`{{filterContext}}`</span> = 活动过滤器的描述

### 字母顺序

服务器相关变量保持一致的字母顺序：

- <span v-pre>`{{serverList}}`</span> 按字母顺序排序
- <span v-pre>`{{serverNames}}`</span> 数组按字母顺序排序
- <span v-pre>`{{instructions}}`</span> 部分按字母顺序出现

### 实时更新

所有变量都反映当前状态：

- 服务器连接/断开更新计数
- 指令更改更新内容
- 过滤更改更新所有相关变量

## 错误处理

### 缺失变量

- 未定义的变量渲染为空字符串
- 模板引擎继续处理
- 缺失变量不会抛出错误

### 无效模板

- 语法错误导致回退到默认模板
- 错误被记录但不会导致服务器崩溃
- 模板编译被缓存以提高性能

### 模板渲染

**注意**: 1MCP 使用 `noEscape: true` 配置，因此所有变量默认未转义：

- <span v-pre>`{{variable}}`</span> 输出原始内容（未转义）
- 无需三重括号 - 所有内容按原样渲染
- 非常适合 LLM 消费，XML 标签和标记应被保留
- 不需要 XSS 保护，因为模板用于 LLM 指令目的，而不是网页显示
