Skip to main content
Glama
loongarch-pirun

spec-guard

by loongarch-pirun
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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
ParametersJSON Schema
NameRequiredDescriptionDefault
specPathYes
codeDirYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_check_interfacesD
ParametersJSON Schema
NameRequiredDescriptionDefault
specPathYes
codeDirYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_check_modelsD
ParametersJSON Schema
NameRequiredDescriptionDefault
specPathYes
codeDirYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

spec_check_securityD
ParametersJSON Schema
NameRequiredDescriptionDefault
specPathYes
codeDirYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 4 tool updatesv1.0.0
    • First observedspec_check_env
    • First observedspec_check_interfaces
    • First observedspec_check_models
    • First observedspec_check_security
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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 issues

Resources

Related MCP Connectors

Related MCP Servers