Skip to main content
Glama

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 声明的环境变量是否在代码中使用

Related MCP server: Swarm Orchestrator

快速开始

前置条件

  • 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。

Available Tools

4 tools
spec_check_envD

Inputs: specPath (required), codeDir (required).

spec_check_interfacesD

Inputs: specPath (required), codeDir (required).

spec_check_modelsD

Inputs: specPath (required), codeDir (required).

spec_check_securityD

Inputs: specPath (required), codeDir (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    D1.9/5.0

    Scored across 4 tools

    Disambiguation4/5

    Tool names specify distinct aspects (env, interfaces, models, security), so agents can differentiate them. Without descriptions, there is slight ambiguity about exact scope, but the naming is clear enough.

    Naming Consistency5/5

    All tools follow a consistent 'spec_check_<aspect>' pattern, making them predictable and easy to understand.

    Tool Count4/5

    Four tools is a reasonable scope for a specialized specification checker. It is neither too few nor too many for the domain.

    Completeness3/5

    The set covers key specification areas (env, interfaces, models, security), but lacks a composite check or a tool for performing all checks at once, which is a minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers