@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 会自动获取并使用最新版本。

环境变量

| 环境变量 | 必填 | 默认值 | 说明 | | --------------------- | ---- | -------------------- | ----------------------------------- | | TEMPLATE_SERVER_URL | 是 | — | 模板服务端地址（HTTP 服务器根地址） | | TEMPLATE_TIMEOUT | 否 | 30000 | HTTP 请求超时（ms） | | TEMPLATE_RETRIES | 否 | 3 | 下载失败重试次数 | | TEMPLATE_CACHE_DIR | 否 | .yq-template/cache | zip 缓存目录（相对于项目目录） |

如何升级到最新版本？

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

工具

get-template-info

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

参数：

| 参数 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ----------------- | | type | string | 否 | 模板类型，默认 BM |

create-project

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

参数：

| 参数 | 类型 | 必填 | 说明 | | ----------------------- | -------- | ---- | ---------------------------------------------------------------------------- | | projectName | string | 是 | 项目名（package.json 的 name，kebab-case） | | projectDir | string | 是 | 目标目录绝对路径 | | type | string | 否 | 模板类型，默认 BM | | version | string | 否 | 要创建的模板版本号，不传则用最新版（latest）。端到端测试或需指定旧版本时使用 | | includeOptionalGroups | string[] | 否 | 要包含的可选组名称列表 | | port | number | 是 | 开发服务器端口号 |

check-update

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

参数：

| 参数 | 类型 | 必填 | 说明 | | --------------- | ------ | ---- | ------------------------------------------------------------ | | projectDir | string | 是 | 项目目录绝对路径 | | targetVersion | string | 否 | 目标版本号，不传则查最新版（latest）。需更新到指定版本时传入 |

update-template

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

参数：

| 参数 | 类型 | 必填 | 说明 | | --------------------- | -------- | ---- | --------------------------------------------- | | projectDir | string | 是 | 项目目录绝对路径 | | targetVersion | string | 否 | 目标版本号，默认 latest | | selectedFiles | string[] | 是 | 用户选择更新的文件路径列表 | | conflictResolutions | object | 否 | 冲突处理决定（use-template / keep-local） |

repair-state

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

参数：

| 参数 | 类型 | 必填 | 说明 | | ------------ | ------ | ---- | ------------------------------------------ | | projectDir | string | 是 | 项目目录绝对路径 | | version | string | 否 | 当前模板版本号，不提供时从 state.json 读取 |

get-file-at-version

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

参数：

| 参数 | 类型 | 必填 | 说明 | | ------------ | ------ | ---- | ---------------- | | projectDir | string | 是 | 项目目录绝对路径 | | path | string | 是 | 文件相对路径 | | version | string | 是 | 版本号 |

三值比对

更新检测基于三值比对：

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

| A | B | C | 状态 | 说明 | | --- | --- | --- | ---------------- | ------------------------------- | | X | X | X | — | 无变化，跳过 | | X | Y | X | auto | 维护者改了，同事没改 → 自动覆盖 | | X | X | Y | — | 同事改了，维护者没变 → 跳过 | | X | Y | Y | auto | 同事已手动更新到新版本 | | X | Y | Z | conflict | 双方都改了 → 需处理 | | — | Y | — | new | 新文件 | | — | Y | Z | confirm | 不在快照，本地和 zip 都有 | | X | Y | — | missing | 文件缺失 | | X | — | X | deleted | 维护者删了，同事没改 | | X | — | Y | deleted-modified | 维护者删了，同事改过 |

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 参数。