Commit Specs MCP

一个基于 Model Context Protocol (MCP) 的智能代码提交前审查系统，支持多语言项目自动检测和适配。

✨ 核心特性

• 🔍 智能项目检测 - 自动识别项目语言和技术栈 (Rust/Go/Python/Node.js/Java/C#)
• 🎯 自适应审查 - 根据项目类型自动生成对应的审查配置和检查命令
• 📊 多维度检查 - 阻塞性检查(格式化、Lint、编译、测试、架构、安全) + 警告性检查(性能、文档、覆盖率)
• 📝 结构化报告 - 自动生成详细的 Markdown 审查报告并归档
• 🔄 MCP 集成 - 通过 MCP 协议与 AI 助手无缝集成
• ⚙️ 灵活配置 - 支持自定义检查项、阈值和跳过规则

🌍 支持的语言

| 语言 | 构建工具 | Linter | 格式化 | 测试框架 | |------|---------|--------|--------|---------| | 🦀 Rust | Cargo | Clippy | rustfmt | cargo test | | 🐹 Go | Go Modules | golangci-lint | gofmt | go test | | 🐍 Python | pip/poetry | pylint/ruff | black | pytest | | 🟢 Node.js | npm/yarn/pnpm | eslint | prettier | jest | | ☕ Java | Maven/Gradle | checkstyle | google-java-format | junit | | 💜 C# | dotnet | roslyn | dotnet-format | xunit |

🚀 快速开始

安装

npm install -g commit-specs-mcp

或使用 npx (无需安装):

npx commit-specs-mcp /path/to/your/project

配置 MCP 客户端

Claude Desktop

编辑 claude_desktop_config.json:

{
  "mcpServers": {
    "commit-specs": {
      "command": "npx",
      "args": ["-y", "commit-specs-mcp@latest", "/path/to/your/project"],
      "timeoutSeconds": 180
    }
  }
}

timeoutSeconds 可以根据项目规模适当调大 (例如 120/180 秒), 防止 Claude Desktop 在长时间运行的审查过程中提前终止 MCP 工具。

Augment Code

{
  "mcpServers": {
    "commit-specs": {
      "command": "npx",
      "args": ["-y", "commit-specs-mcp@latest", "/path/to/your/project"]
    }
  }
}

Cursor IDE

在 settings.json 中添加:

{
  "mcpServers": {
    "commit-specs": {
      "command": "npx",
      "args": ["-y", "commit-specs-mcp@latest", "/path/to/your/project"]
    }
  }
}

调整 Codex CLI 的 MCP 超时

对于大型项目(尤其是 Rust/Java)即使启用并行也可能超过 Codex CLI 默认的 60 秒工具超时。可以在 ~/.codex/config.toml 中对应的 [mcp_servers.<name>] 区块设置更高的 tool_timeout_sec/startup_timeout_sec:

[mcp_servers.commit-specs]
command = "npx"
args = ["-y", "commit-specs-mcp@latest", "/path/to/your/project"]
startup_timeout_sec = 30   # 默认 10 秒, 可按需增大
tool_timeout_sec = 180     # 默认 60 秒, 可设置成 90/120/180 等

更多 Codex CLI 配置项请参考 Codex 官方配置文档 (https://github.com/openai/codex)。

首次使用

1. 启动 MCP Server

npx commit-specs-mcp /path/to/your/project

首次启动会自动:

• 🔍 检测项目类型和技术栈
• ⚙️ 生成适配的审查配置
• 📁 初始化工作空间目录
• 📋 创建审查 Prompts 和模板

2. 在 AI 助手中使用

用户: 请帮我执行提交前代码审查

AI: 好的,我来执行完整的代码审查...
[自动调用 MCP 工具执行审查]

✅ 审查通过!
- 阻塞性检查: 6/6 通过
- 警告: 1个

详细报告: .commit-review/reports/passed/202511080554-passed.md

🔁 execute-commit-review 默认以后台模式运行 (full/quick 均如此)。CLI 会先返回“审查已在后台运行”与 jobId，请稍候再使用 get-review-job-status 或 get-review-report (reportType="latest") 查看进度与生成的报告。如需同步等待，可传 runInBackground: false。

📁 项目结构

初始化后会在项目根目录创建 .commit-review/ 目录:

your-project/
  .commit-review/
    ├── config/
    │   └── review-config.toml      # 审查配置文件
    ├── prompts/
    │   └── pre-commit-review.md    # 审查指南 Prompt
    ├── templates/
    │   └── review-report-template.md # 报告模板
    └── reports/
        ├── passed/                  # 通过的审查报告
        │   └── 202511080554-passed.md
        └── failed/                  # 失败的审查报告
            └── 202511080612-failed.md

🔧 MCP 工具

1. get-project-info

获取项目检测信息和审查配置。

// 无需参数

返回:

• 项目语言和技术栈
• 检测到的构建工具
• 启用的检查项列表
• 项目架构信息 (单包/Monorepo)

2. execute-commit-review

执行完整的提交前代码审查。

{
  mode?: "full" | "quick",        // 审查模式 (默认: full)
  skipChecks?: string[],           // 跳过的检查项 ID
  runInBackground?: boolean        // 是否后台执行 (默认: true)
}

返回:

• 审查结果 (进行中/通过/失败)
• 各检查项详细结果
• 生成的报告路径
• 提交建议或后台任务提示 (含 jobId)

3. get-review-status

获取最近的审查历史和统计。

{
  limit?: number                   // 返回最近 N 次记录 (默认: 10)
}

返回:

• 最近审查记录列表
• 通过率统计
• 常见失败原因

4. get-review-report

获取指定审查报告的内容。

{
  timestamp: string,               // 报告时间戳 (如: "202511080554")
  status: "passed" | "failed"      // 报告状态
}

返回:

• 完整的报告内容 (Markdown)

5. describe-commit-specs

获取 commit-specs MCP Server 的自描述信息。

// 无需参数

返回:

• 服务器名称、版本、仓库/主页
• 常用启动命令与最佳实践
• 所有工具的描述及输入参数
• 官方文档与问题反馈入口

6. get-review-job-status

查询后台执行的审查任务列表/状态。

{
  jobId?: string,                // 任务 ID (可选)
  projectPath?: string,          // 项目路径 (可选)
  limit?: number                 // 返回任务数量 (默认: 10)
}

返回:

• 任务 ID、模式、状态(运行中/已完成)
• 报告路径或错误信息
• 开始/完成时间

⚡ 并行执行与超时优化

• Full 模式默认会同时运行多个检查项：阻塞性检查并发度为 2，警告性检查并发度为 3；需要独占资源的格式化类检查会自动串行执行。
• .commit-review/config/review-config.toml 可覆盖默认并行度：

[review]
parallelism = 3                 # 统一设置阻塞/警告并发度
blocking_parallelism = 2        # 仅覆盖阻塞性检查
warning_parallelism = 4         # 仅覆盖警告性检查

• 若某些检查仍需串行，可在配置生成器中为对应检查加上 execution.isolation = true（默认已对格式化检查启用）。

📊 审查维度

阻塞性检查 (必须全部通过)

| # | 检查项 | 说明 | |---|--------|------| | 1 | 代码格式化 | 检查代码格式是否符合标准 | | 2 | 静态分析 | Linter 检查,零警告零错误 | | 3 | 编译检查 | 确保代码能成功编译 | | 4 | 单元测试 | 所有测试必须通过 | | 5 | 架构一致性 | 验证依赖层次和命名约定 | | 6 | 安全审计 | 检查依赖漏洞和敏感信息 |

警告性检查 (不阻止提交)

| # | 检查项 | 说明 | |---|--------|------| | 7 | 性能基准 | 检测性能退化 (阈值: 10%) | | 8 | 文档完整性 | API 文档覆盖率检查 | | 9 | 测试覆盖率 | 代码覆盖率检查 (目标: 85%+) |

⚙️ 配置

配置文件

编辑 .commit-review/config/review-config.toml:

[review]
default_mode = "full"              # 默认审查模式

[blocking_checks]
enabled = ["1", "2", "3", "4", "5", "6"]  # 启用的阻塞性检查

[warning_checks]
enabled = ["7", "8", "9"]          # 启用的警告性检查

[thresholds.performance]
yellow_warning = 10                # 性能退化黄色警告阈值 (%)
red_warning = 20                   # 性能退化红色警告阈值 (%)

[thresholds.coverage]
core = 90                          # 核心库覆盖率要求 (%)
modules = 85                       # 业务模块覆盖率要求 (%)

自定义检查命令

修改配置文件中的 [commands] 部分:

[commands]
format_check = "cargo fmt --all --check"
lint = "cargo clippy --workspace -- -D warnings"
# ... 自定义其他命令

💡 使用场景

场景 1: 常规提交审查

用户: 我完成了功能开发,准备提交代码

AI: 好的,我来执行提交前审查
[调用 execute-commit-review]

✅ 审查通过!

建议提交命令:
git commit -m "feat: 新增用户认证功能

审查报告: .commit-review/reports/passed/202511080554-passed.md"

场景 2: 快速审查 (跳过性能测试)

用户: 请执行快速审查,跳过性能测试

AI: [调用 execute-commit-review { mode: "quick" }]

✅ 快速审查完成 (已跳过性能基准测试)

场景 3: 审查失败

AI: ❌ 审查失败!

发现以下问题:
1. Clippy 检查: 3 个警告
2. 单元测试: 2 个测试失败

详细报告: .commit-review/reports/failed/202511080612-failed.md

请修复这些问题后重新审查。

🧪 使用示例集合

• 更多使用示例可参考项目 Wiki (https://github.com/fengjinyi98/commit-specs-mcp/wiki)，覆盖 Rust/Node.js/CI 等典型场景
• 每个示例都包含命令行参数及在 MCP 客户端的调用配置, 便于直接复用
• 欢迎通过 PR 补充更多团队实践, 我们会在该文档中持续收录

🚢 打包与发布流程

1. npm run typecheck && npm test - 确认类型安全与测试通过
2. npm run build - 基于 tsconfig.build.json 生成 dist/ 产物
3. npm run package - 自动清理+构建+生成 .tgz 以便在本地验证 npm 包
4. npm publish --access public - 发布到 npm (依赖 publishConfig.access=public)
5. 更新 CHANGELOG 以及 GitHub Release 说明

所有可发布文件通过 package.json 的 files 白名单控制, CLI 入口 dist/index.js 会在构建时保留 shebang 以确保可执行。

📈 审查报告示例

# Git 提交审查报告

**审查时间**: 2025-11-08 05:54
**审查状态**: ✅ 通过
**项目语言**: Rust

## 📊 变更概览

- 变更文件数: 12
- 新增代码行: 245
- 删除代码行: 67
- 变更模块: maohuoban-auth, maohuoban-database

## ✅ 阻塞性检查结果

### 1️⃣ Rust 代码格式化
- **状态**: ✅ 通过
- **耗时**: 1.2s

### 2️⃣ Clippy 静态分析
- **状态**: ✅ 通过
- **警告数**: 0
- **耗时**: 8.5s

...

## 🎯 审查结论

✅ **审查通过,可以提交!**

阻塞性检查: 6/6 ✅
警告性检查: 2/3 ⚠️ (文档覆盖率 95%)

🔧 故障排查

更详细的排障步骤请参考项目 Wiki 的 Troubleshooting 章节或 GitHub Issues。

问题 1: 项目检测失败

现象: 提示"无法检测项目类型"

解决:

# 检查项目根目录是否包含语言特征文件
ls -la  # 查找 Cargo.toml, go.mod, package.json 等

# 手动指定项目类型 (未来版本支持)
npx commit-specs-mcp /path/to/project --language rust

问题 2: 某个检查命令失败

现象: 审查时某个命令报错

解决:

# 确保工具链已安装
# Rust 项目
rustup component add clippy rustfmt

# Go 项目
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Python 项目
pip install black pylint pytest

🤝 贡献指南

欢迎贡献代码和建议!

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

📄 许可证

MIT License - 详见 LICENSE 文件

🔗 相关链接

• Model Context Protocol
• 参考项目: spec-workflow-mcp

维护者: Commit Specs MCP Team
最后更新: 2025-11-08
版本: v0.1.0