MCP Conventional Commit

mcp常规承诺

用于提交辅助流的MCP服务器：

1. 分析git差异(analyze_diff)
2. 验证消息音调(validate_tone)
3. 可选择执行提交(execute_commit)只有在用户确认后

特性

• analyze_diff:

• 分析 git diff (--cached 默认情况下）

• 返回用于类型/范围/主题推理的结构化信号

• 回报 relatedRecentCommits 只有当相关性足够高时

• 不生成最终提交消息

• validate_tone:

• 验证常规提交语气/风格

• 回报 toneScore, violations，以及 suggestedRewrite

• 如果未提供相关提交，则自动回退到最近的历史记录

• execute_commit:

• 跑 git commit -m "" （以及 -m "" 提供时）

• 自动暂存最新文件 analyze_diff 默认情况下

• 支持 --dry-run 模式

• 拒绝占位符值，如 `, , `

• 如果出现以下情况，则返回错误 autoStageAnalyzed=true 而且之前没有 analyze_diff 上下文存在

需求

• Node.js 18+

安装

npm install
npm run build

运行服务器（stdio）

npm start

运行本地CLI客户端

npm run client -- --help

分析阶段示例：

npm run client --
npm run client -- --unstaged
npm run client -- --base main
npm run client -- --json

执行阶段示例：

npm run client -- --commit-message "feat(api): add token refresh"                 # preview only
npm run client -- --commit-message "feat(api): add token refresh" --confirm-commit
npm run client -- --commit-message "feat(api): add token refresh" --commit-body "- add refresh token endpoint\n- update auth middleware" --confirm-commit
npm run client -- --commit-message "feat(api)!: add token refresh" --commit-body "- add refresh token endpoint" --commit-footer "BREAKING CHANGE: refresh token format changed" --confirm-commit
npm run client -- --commit-message "fix(ui): handle null avatar" --dry-run --confirm-commit

CLI选项

分析：

• `--repo

`：git存储库路径

• --unstaged：分析工作树差异，而不是分阶段差异
• --base ：比较 ...HEAD
• --max-chars ：分析的最大差异字符数
• 默认情况下，分析中包含未跟踪的文件（合成差异vs /dev/null)

执行：

• --commit-message ：运行预览流(analyze_diff + validate_tone)
• --commit-body ：可选提交体
• --commit-footer ：可选提交页脚
• --confirm-commit：预览确认后执行commit
• --dry-run：使用 git commit --dry-run （与 --confirm-commit)

概述：

• --json：打印完整的结构化结果

与Codex一起使用

通用的 mcpServers JSON样式

{
  "mcpServers": {
    "conventional-commit": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-conventional-commit/dist/index.js"]
    }
  }
}

法典 ~/.codex/config.toml 风格

[mcp_servers.conventional_commit]
command = "node"
args = ["/absolute/path/to/mcp-conventional-commit/dist/index.js"]

[mcp_servers.conventional_commit.env]
MCP_TRANSPORT_TYPE = "stdio"

然后重新启动Codex会话，以便加载工具。

推荐流量（代理）

MCP服务器公开了三个工具：

1. analyze_diff
2. validate_tone
3. execute_commit

推荐药剂流量：

1. 如果（且仅当）任务修改了目标项目中的文件，请调用 analyze_diff.
2. 使用MCP分析(recommendedTypes, scopeCandidates, subjectHints, stats, changedFiles)作为LLM提交消息推理的结构化上下文。
3. 在LLM/客户端中起草一条提交消息。
4. 呼叫 validate_tone 只有当分数低于阈值时，才对草稿进行重写。
5. 将最终建议的提交消息作为预览显示给用户。
6. 不自动运行 execute_commit 在默认流程中；建议将其作为可选的下一步行动。
7. 如果用户选择继续，请致电 execute_commit （更喜欢 dryRun=true 首先是严格/安全的工作流程）。

MCP常规提交流（示例）

# MCP Conventional Commit Flow

Run this flow only after tasks that change files in this project.
Do not run it for Q&A or non-editing tasks.

1. Call `analyze_diff` with:
   - `repoPath`: repository path
   - `staged`: true/false (default true)
   - `baseRef`: optional comparison base
2. Read structured output and use:
   - `recommendedTypes` for commit type candidates
   - `scopeCandidates` for optional scope
   - `subjectHints` for subject candidates
   - `relatedRecentCommits` for continuity hints (already filtered by correlation)
   - `stats` and `changedFiles` for justification
3. Produce draft Conventional Commit message in the LLM/client.
4. Call `validate_tone` with:
   - `message`: draft message
   - `relatedRecentCommits`: optional direct pass-through from `analyze_diff`
   - `minToneScore`: optional threshold (default `0.8`)
5. Show the final commit message preview to the user.
6. Add an optional suggested next action such as:
   - `Run execute_commit with this message`
7. Call `execute_commit` only if the user explicitly confirms:
   - `message`: final commit message
   - `body`: optional commit body
   - `footer`: optional commit footer
   - `autoStageAnalyzed`: optional, default `true` (stages analyzed files automatically)
   - `dryRun`: true first (recommended), then false if valid

Notes:
- Keep commit message generation in the LLM/client layer.
- Use MCP only for deterministic diff analysis and git commit execution.

工具

analyze_diff

输入：

{
  "repoPath": "/path/to/project",
  "staged": true,
  "baseRef": "main",
  "includeUntracked": true
}

输出（形状）：

{
  "hasChanges": true,
  "scopeCandidates": ["api", "auth"],
  "recommendedTypes": [
    { "type": "feat", "score": 6, "reason": "featureSignals=2, addedFiles=1" }
  ],
  "subjectHints": ["add api support"],
  "stats": {
    "files": 3,
    "additions": 42,
    "deletions": 5,
    "addedFiles": 1,
    "deletedFiles": 0,
    "renamedFiles": 0,
    "hasBreakingHint": false
  },
  "changedFiles": ["src/api/auth.ts", "src/api/token.ts", "README.md"],
  "relatedRecentCommits": [
    {
      "hash": "a1b2c3d",
      "subject": "feat(api): add auth token decoder",
      "score": 0.78,
      "reason": "fileOverlap=0.67, lexicalSimilarity=0.40, typeMatch=1"
    }
  ]
}

validate_tone

输入：

{
  "repoPath": "/path/to/project",
  "message": "feat(api): Add auth refresh flow.",
  "relatedRecentCommits": [
    {
      "hash": "a1b2c3d",
      "subject": "feat(api): add auth token decoder",
      "score": 0.78,
      "reason": "fileOverlap=0.67, lexicalSimilarity=0.40, typeMatch=1"
    }
  ],
  "minToneScore": 0.8
}

输出（形状）：

{
  "toneScore": 0.75,
  "violations": ["subject should start with lowercase verb", "subject should not end with punctuation"],
  "suggestedRewrite": "feat(api): add auth refresh flow",
  "applied": true
}

execute_commit

输入：

{
  "repoPath": "/path/to/project",
  "message": "feat(api): add token refresh",
  "body": "- add refresh token endpoint\n- update auth middleware",
  "footer": "Refs: #123",
  "autoStageAnalyzed": true,
  "dryRun": true
}

输出（形状）：

{
  "success": true,
  "dryRun": true,
  "autoStageAnalyzed": true,
  "autoStagedFiles": 3,
  "message": "feat(api): add token refresh",
  "body": "- add refresh token endpoint\n- update auth middleware",
  "footer": "Refs: #123",
  "stdout": "...",
  "stderr": "..."
}