@linjian612/yq-template-mcp

@linjian612/yq-template-mcp

模板分发系统的 MCP Server，供同事在 Claude Code 中创建项目和更新模板。

快速开始

Claude Code 配置

在项目的 .claude/settings.local.json 中添加：

{
  "mcpServers": {
    "yq-template": {
      "command": "npx",
      "args": ["@linjian612/yq-template-mcp@latest"],
      "env": {
        "TEMPLATE_SERVER_URL": "https://your-server.com"
      }
    }
  }
}

使用 @latest 标签 + npx，无需手动安装或升级——重启 MCP 服务后 npx 会自动获取并使用最新版本。

环境变量

如何升级到最新版本？

重启 MCP 服务后 npx 会自动获取并使用最新版本。确保配置时使用 @latest 标签即可。

工具

get-template-info

查询模板元信息。获取模板类型、最新版本和可选组。

参数：

create-project

创建新项目。下载模板 zip、解压、变量替换、生成 state.json。

参数：

check-update

检查可用更新。三值比对分析，返回按组分类的变更文件清单。含 status=conflict 时用批量列表让用户决策（用模板版 / 留本地版 / 自动合并）。

参数：

update-template

执行更新。支持冲突解决（用模板版 / 留本地版）+ 智能合并 + renamed 改名更新 + 自动备份。

参数：

repair-state

重建 state.json。state.json 损坏或缺失时使用。比对磁盘 hash 与 targetVersion zip hash，判定每文件版本确定 / 不确定，输出 uncertainCount。

参数：

get-file-at-version

读取项目模板某版本某文件的内容，供 conflict 自动合并读取旧版 / 新版。cache 命中直读，无则 download 该版本 zip。

参数：

三值比对

更新检测基于三值比对：

• A = state.json 中的 hash（旧快照）
• B = zip 中的 hash（新版模板）
• C = 磁盘上的 hash（当前文件）

renamed（大小写维度，在三值比对前短路）：state 与 zip 的 origKey 同 toLowerCase 但大小写不同 → 模板做了大小写重命名（fromPath → path）。localModified（C ≠ A）决定是否需 update 决策。

state.json

记录项目中所有模板文件的 hash 和域归属：

{
  "type": "BM",
  "version": "1.0.4",
  "createdAt": "2026-06-04T10:00:00.000Z",
  "updatedAt": "2026-07-07T12:00:00.000Z",
  "files": {
    "src/api/index.js": {
      "hash": "a1b2c3...",
      "domain": "template",
      "version": "1.0.4"
    }
  }
}

字段说明：

• hash — 文件内容 hash（定制文件存模板原版 hash，普通文件存磁盘 hash）
• domain — 域归属（template / mixed / business）
• version — 该文件当前内容对应的模板版本。repair 重建后，磁盘内容非模板原版的文件此字段缺失（版本不确定）

已知限制

• 并发 update（丢失更新）：state.json 读写无锁。多 agent / 多窗口同时 update 同一项目时，后写的会覆盖前一个的改动。原子写保证 state.json 不损坏，但可能与磁盘不一致。避免同项目并发 update。
• repair 的 targetVersion 可信度：repair 用 state.version（或传入 version）下载 zip 作为 hash 比对基准；若该版本号本身不准（部分更新残留），比对结论不可靠。不可信时由用户显式传正确 version 参数。