模板语法参考

1MCP 服务器模板中 Handlebars 模板语法的完整参考。

语法概述

1MCP 服务器模板使用 Handlebars 语法，变量替换使用双花括号：

{{variable}}           <!-- 变量访问 -->
{{namespace.variable}}  <!-- 嵌套变量访问 -->
{{helper arg1 arg2}}   <!-- 辅助函数调用 -->

变量访问

标准语法

所有模板变量都使用双花括号：

{{project.path}}
{{user.username}}
{{transport.client.name}}
{{project.custom.teamId}}

嵌套属性

使用点号表示法访问嵌套属性：

{{project.git.branch}}
{{project.custom.apiEndpoint}}
{{transport.client.version}}

可选值

可能未定义的属性将渲染为空字符串：

{{project.git.branch}}    <!-- 如果不在 git 仓库中则渲染为空 -->
{{user.email}}            <!-- 如果未设置则渲染为空 -->

模板变量

项目变量

变量	类型	描述
project.path	string	当前项目的绝对路径
project.name	string	项目目录名称
project.environment	string	来自 .1mcprc 或默认的环境
project.git.branch	string?	当前 git 分支
project.git.commit	string?	当前 git 提交哈希
project.git.repository	string?	Git 远程 URL
project.custom.*	any	来自 .1mcprc 的自定义值

用户变量

变量	类型	描述
user.username	string?	系统用户名
user.name	string?	用户全名
user.email	string?	用户邮箱地址
user.home	string?	主目录路径
user.uid	string?	用户 ID
user.gid	string?	组 ID
user.shell	string?	默认 shell 路径

传输变量

变量	类型	描述
transport.type	string	传输类型 (http、sse、stdio)
transport.url	string?	服务器 URL（仅 HTTP/SSE）
transport.connectionId	string?	连接标识符
transport.connectionTimestamp	string?	连接时间（ISO 8601）
transport.client.name	string	客户端应用名称
transport.client.version	string	客户端应用版本
transport.client.title	string?	客户端显示名称

条件表达式

If/Else

{{#if (eq project.environment 'production')}}
  production-value
{{else if (eq project.environment 'staging')}}
  staging-value
{{else}}
  development-value
{{/if}}

Unless

{{#unless (eq transport.client.name 'claude-code')}}
  此内容对 claude-code 隐藏
{{/unless}}

比较辅助函数

等于 (eq)

{{#if (eq project.environment 'production')}}
{{/if}}

不等于 (ne)

{{#if (ne user.username 'root')}}
{{/if}}

大于 (gt)

{{#if (gt project.custom.count 5)}}
{{/if}}

小于 (lt)

{{#if (lt project.custom.maxConnections 10)}}
{{/if}}

逻辑辅助函数

And

{{#if (and (eq project.environment 'production') (eq project.custom.region 'us'))}}
{{/if}}

Or

{{#if (or (eq project.custom.team 'backend') (eq project.custom.team 'devops'))}}
{{/if}}

数学辅助函数

基本数学运算

{{math value1 '+' value2}}     <!-- 加法 -->
{{math value1 '-' value2}}     <!-- 减法 -->
{{math value1 '*' value2}}     <!-- 乘法 -->
{{math value1 '/' value2}}     <!-- 除法 -->
{{math value1 '%' value2}}     <!-- 取模 -->
{{math value1 '**' value2}}    <!-- 幂运算 -->

链式运算

{{math value '*' 100 '/' total}}    <!-- (value * 100) / total，已四舍五入 -->

专门的数学运算

{{subtract a b}}    <!-- 带空值安全性的 a - b，未定义时返回 0 -->
{{div a b}}         <!-- 带零安全性的 a / b，除以零时返回 0 -->

字符串辅助函数

包含

{{#if (contains project.name 'admin')}}
  包含 'admin'
{{/if}}

以...开头

{{#if (startsWith project.git.branch 'feature/')}}
  功能分支
{{/if}}

以...结尾

{{#if (endsWith project.name '-test')}}
  测试项目
{{/if}}

长度

{{len project.name}}    <!-- 字符串长度 -->

子字符串

{{substring project.name 0 5}}    <!-- 字符 0-4 -->
{{substring project.name 3}}      <!-- 从字符 3 到结尾 -->

上下文数据结构

TypeScript 接口

interface ContextData {
  project: {
    path: string;
    name: string;
    environment?: string;
    git?: {
      branch?: string;
      commit?: string;
      repository?: string;
    };
    custom?: Record<string, unknown>;
  };
  user: {
    username?: string;
    name?: string;
    email?: string;
    home?: string;
    uid?: string;
    gid?: string;
    shell?: string;
  };
  transport?: {
    type: string;
    url?: string;
    connectionId?: string;
    connectionTimestamp?: string;
    client?: {
      name: string;
      version: string;
      title?: string;
    };
  };
}

模板渲染过程

1MCP 通过五个步骤的工作流程处理模板：

步骤 1：上下文收集

当客户端连接时，1MCP 从以下位置收集上下文：

• 当前工作目录（项目路径、名称）
• Git 仓库（分支、提交、远程）
• .1mcprc 文件（自定义上下文、环境）
• 系统信息（用户详细信息）
• 连接详细信息（传输、客户端信息）

步骤 2：模板查找

1MCP 从 mcp.json 的 mcpTemplates 中查找与客户端的过滤条件（标签、预设）匹配的模板。

步骤 3：变量替换

通过替换以下内容来渲染每个模板配置：

• {{variable}} 占位符替换为实际值
• {{#if}} 条件被评估
• {{helper}} 函数被执行

步骤 4：验证

validateOnReload 保留供将来使用，当前无效果。

步骤 5：服务器创建

使用渲染后的配置创建服务器实例并将其连接到客户端。

缓存

当启用 cacheContext 时（默认），渲染后的模板按上下文哈希缓存，以避免重新处理相同的上下文。

错误处理

模板语法错误

如果模板具有无效的 Handlebars 语法：

• 严格模式：受影响的模板服务器被跳过；错误会被记录。其他服务器正常继续。
• 优雅模式：使用原始模板而不进行渲染，记录错误

缺失变量

上下文中不存在的变量将渲染为空字符串。这是可选值（如 {{project.git.branch}}）的预期行为。

验证错误

如果渲染后的配置验证失败：

• 严格模式：不创建模板服务器
• 优雅模式：使用原始模板配置

示例

环境特定配置

{
  "mcpTemplates": {
    "adaptive-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "NODE_ENV": "{{project.environment}}",
        "LOG_LEVEL": "{{#if (eq project.environment 'production')}}warn{{else}}debug{{/if}}",
        "FEATURE_FLAG_X": "{{#if (gt project.custom.version 2)}}true{{else}}false{{/if}}"
      }
    }
  }
}

客户端感知配置

{
  "mcpTemplates": {
    "client-specific": {
      "command": "npx",
      "args": ["-y", "my-server", "--client", "{{transport.client.name}}", "--version", "{{transport.client.version}}"],
      "disabled": "{{#if (or (eq transport.client.name 'cursor') (eq transport.client.name 'claude-code'))}}false{{else}}true{{/if}}"
    }
  }
}

Git 感知配置

{
  "mcpTemplates": {
    "branch-aware": {
      "command": "npx",
      "args": ["-y", "context-server", "{{project.path}}", "--branch", "{{project.git.branch}}"],
      "disabled": "{{#if (startsWith project.git.branch 'hotfix/')}}true{{else}}false{{/if}}"
    }
  }
}

另请参阅

• MCP 服务器模板指南 - 使用模板的完整指南
• Handlebars 文档 - 官方 Handlebars 参考
• 上下文增强 - 使用 .1mcprc 文件