spec-guard

SPEC 与代码对齐检查 MCP · 自建确定性检查，无 AI 参与

---

spec-guard 是一个确定性 MCP（Model Context Protocol）服务器，用于检查项目代码是否与 SPEC 文档保持一致。它不依赖 AI 判断，纯静态分析，结果可复现。

核心能力

工具	检查项	准确度	说明
spec_check_interfaces	API 端点	~99%	SPEC 中定义的端点是否都在代码中实现
spec_check_models	数据模型字段	~98%	实体字段名与代码中的字段是否匹配
spec_check_security	安全措施	~80-90%	安全需求（限流/JWT/加密等）是否在代码中落地
spec_check_env	环境变量	~98%	SPEC 声明的环境变量是否在代码中使用

快速开始

前置条件

• Node.js 18+
• npm

安装与运行

# 克隆
git clone https://github.com/loongarch-pirun/spec-guard.git
cd spec-guard

# 安装依赖
npm install

# 构建
npm run build

# 运行（标准输入输出模式，供 MCP 客户端使用）
node dist/server.js

# 开发模式（热重载）
npm run dev

MCP 客户端配置

在 MCP 客户端中添加：

{
  "mcpServers": {
    "spec-guard": {
      "command": "node",
      "args": ["path/to/spec-guard/dist/server.js"]
    }
  }
}

参数说明

所有工具使用相同的参数：

参数	类型	必填	说明
specPath	string	✅	SPEC.md 文件的路径
codeDir	string	✅	项目代码目录路径

返回格式

{
  "tool": "spec_check_interfaces",
  "grade": "PASS | WARN | FAIL",
  "accuracy": "~99%",
  "checks": [
    { "path": "GET /api/users", "ok": true, "location": "routes/users.ts:42" },
    { "path": "POST /api/login", "ok": false, "detail": "not found" }
  ]
}

项目结构

spec-guard/
├── src/
│   ├── server.ts                # MCP 服务器入口 & 检查逻辑
│   └── utils/
│       ├── parse-spec.ts        # SPEC 文档解析器
│       └── scan-code.ts         # 代码扫描器
├── package.json
├── tsconfig.json
├── README.md
├── LICENSE
└── .github/
    ├── ISSUE_TEMPLATE.md
    └── PULL_REQUEST_TEMPLATE.md

与 hua-think-lite 配合使用

spec-guard 与 hua-think-lite 形成三阶段代码门禁：

写代码前                   写代码时                    代码完成后
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ hua-think    │ →  │ hua-think    │ →  │ spec-guard   │
│ guard_validate│    │ guard_check  │    │ spec_check_* │
│ 符号验证     │    │ 路径安全审查  │    │ SPEC一致性   │
└──────────────┘    └──────────────┘    └──────────────┘

贡献

欢迎贡献！请阅读 CONTRIBUTING.md。

许可证

MIT — 详见 LICENSE。