tagguard

Name: tagguard
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords开发工具01 周前更新

代码仓库

关于 tagguard

tagguard 是面向项目发布流程的本地预检工具，用于核对 Git 标签、软件包版本和更新日志。它以 JSON 报告全部五项检查，不会在首次失败时停止。

主要功能

01五项明确的发布检查
02Semver 与标签校验
03更新日志标题和内容检查
04JSON 报告及退出码
05支持 CLI 和 Docker

适用场景

01打标签前验证发布元数据
02一次找出所有发布信息问题

MCP 相关

MCP 服务提供 `check_release_tag`，根据拟定标签、软件包版本、更新日志文本和预发布设置执行检查并返回五项结果。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-tagguard": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/tagguard"
      ]
    }
  }
}

启动命令npx -y @reneturcios/tagguard

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/tagguard0.1.0stdio

ocighcr.io/cloudcorprecords/tagguard:0.1.0stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
tag	string	是	拟议的 git 标签，例如 "v0.2.0"
changelog	string	是	CHANGELOG.md 文本
package_version	string	是	package.json 中的版本
allow_prerelease	boolean	否	允许使用预发布版本组件（默认 false）

详细介绍

tagguard

你即将发布一个版本。必须保持一致的三项内容——git 标签、软件包版本和更新日志条目——是否真的一致？tagguard 是一个发布前门禁，通过五项明确的检查来回答这个问题，并在任一检查失败时阻止发布：

SEMVER_VALID — 软件包版本符合 semver 语法（拒绝数字部分中的前导零；预发布和构建元数据后缀遵循 semver 规则）
TAG_MATCHES_VERSION — 去掉一个开头的 v 或 V（前提是其后紧跟数字）后，标签必须与软件包版本完全一致
PRERELEASE_ALLOWED — 带有预发布部分的版本（在任何 + 之前出现 -）在未允许预发布版本时会失败
CHANGELOG_ENTRY — 更新日志中有该版本对应的 ## 标题：## 0.2.0、## [0.2.0]、## v0.2.0 (2026-01-01) 和 ## [0.2.0] - 2026-01-01 均有效
CHANGELOG_ENTRY_NONEMPTY — 该标题下的章节包含内容：在下一个 ## 标题之前，至少有一行非空且本身不是标题的内容

每项检查都会按顺序报告结果，无论通过还是失败——门禁不会提前终止，因此被阻止的发布会一次性显示所有问题。纯本地计算：不执行 git 命令、不访问网络，也无需配置。

命令行

npx @reneturcios/tagguard check --tag v0.2.0 --version 0.2.0 --changelog CHANGELOG.md
npx @reneturcios/tagguard --version

添加 --allow-prerelease，即可允许 1.0.0-beta.1 这样的预发布版本。

该命令会将门禁报告以 JSON 格式输出：

{
  "ok": true,
  "normalized_tag": "0.2.0",
  "checks": [
    { "code": "SEMVER_VALID", "ok": true, "message": "..." }
  ]
}

退出码：门禁通过时为 0；门禁阻止发布时为 1（仍会输出 JSON 报告）；发生运行时错误时也为 1（无法读取更新日志文件时会输出错误行，不输出 JSON）；用法错误时为 2。

MCP 服务

npx -y @reneturcios/tagguard mcp

MCP 客户端配置：

{
  "mcpServers": {
    "tagguard": {
      "command": "npx",
      "args": ["-y", "@reneturcios/tagguard", "mcp"]
    }
  }
}

工具

check_release_tag — 对一个拟议版本运行发布前门禁，并报告全部五项检查。
- tag（字符串，必填）— 拟议的 git 标签，例如 "v0.2.0"
- package_version（字符串，必填）— package.json 中的版本
- changelog（字符串，必填）— CHANGELOG.md 的文本
- allow_prerelease（布尔值，可选，默认 false）— 允许预发布版本部分

tag、package_version 或 changelog 缺失或为空时，会报错并指出对应参数。package_version 不符合 semver 不会导致错误——这会使第 1 项检查失败，而这正是门禁发挥作用的方式。

Docker

docker run -i ghcr.io/cloudcorprecords/tagguard
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/tagguard check --tag v0.2.0 --version 0.2.0 --changelog /w/CHANGELOG.md

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source