# mcp_ai_commit

**Repository Path**: WangJinLiang3/mcp_ai_commit

## Basic Information

- **Project Name**: mcp_ai_commit
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-15
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP AI Commit — 智能 Git 提交助手

符合 Model Context Protocol (MCP) 规范的智能 Git 提交助手。将 AI 提交助手
（变更检测 → 四要素结构化提交信息生成 → 提交前验证 → 代码审查 → Git 提交）
封装为标准 MCP 工具，供 Trae、Claude Desktop 等大语言模型客户端发现与调用。

**特点**：零第三方依赖（仅 Python 标准库）、四要素结构化提交信息、五维代码审查、
插件扩展机制、commit-msg 钩子同步规则、文件监控自动提交（带高风险护栏与
`Auto-Committed-By` 审计页脚）、门禁失效显性化+留痕+自证。

---

## 快速开始

### 前置条件

- Python ≥ 3.10
- Git 已安装且对目标仓库有写权限

### 一键环境自检（推荐）

```bash
# 环境校验 + 单元测试 + MCP 握手冒烟
./install.sh

# 一键全局安装：全局 commit-msg + pre-push 钩子 + 2 个 skill 软链到 ~/.trae/skills
# （默认只预演会做什么，加 --yes 才写入；幂等，可反复执行）
./install.sh --all --yes

# 自检 + 输出针对目标仓库的 MCP 注册 JSON
./install.sh --repo /path/to/your/repo

# 自检 + 为目标仓库安装 commit-msg 钩子
./install.sh --install-hook /path/to/your/repo

# 门禁自证：临时仓库真跑一次坏信息与一次合规信息，断言拦截与放行（只读）
./install.sh --verify-hook

# push 门禁自证：临时仓库真跑 git push，断言拦失败 / 不误伤其他仓库（只读）
./install.sh --verify-prepush

# 快档门禁：编译 + 配置文档同步 + 门禁自证（不含全量单测；CI 与 pre-push 钩子共用）
./install.sh --gate
```

### 手动启动验证

```bash
# 模块运行（cwd 须为包父目录）
python -m mcp_ai_commit.server --repo /path/to/repo

# 脚本直跑（无 cwd 依赖，推荐用于客户端注册）
python /path/to/chat_demo/mcp_ai_commit/server.py --repo /path/to/repo

# 握手冒烟测试
(echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'; sleep 1) \
  | python mcp_ai_commit/server.py --repo .
```

### 注册到 MCP 客户端

- **Trae IDE**：在 MCP 面板中手动添加，填入 `trae_mcp.example.json` 的内容
- **Claude Desktop**：复制 `claude_desktop_config.example.json` 到对应配置路径

---

## 文档导航

| 文档 | 内容 |
|---|---|
| [项目简介.md](项目简介.md) | **非技术读者首选**：用大白话说明项目是什么、能解决什么问题、怎么用、优势与不足 |
| [AGENTS.md](AGENTS.md) | **大模型/自动化首选**：3 步部署、验收断言（14 工具 / 2 skill / 钩子生效）、硬性约束 |
| [USER_GUIDE.md](mcp_ai_commit/USER_GUIDE.md) | **新用户首选**：安装、首次配置、日常使用、高级定制、FAQ |
| [mcp_ai_commit/README.md](mcp_ai_commit/README.md) | **协议适配**：目录结构、工具清单（14 个）、MCP 方法、错误码、配置说明 |
| [USAGE_GUIDE.md](mcp_ai_commit/USAGE_GUIDE.md) | **操作演示**：安装步骤、常用场景、工具速查表、FAQ |
| [HOW_IT_WORKS.md](mcp_ai_commit/HOW_IT_WORKS.md) | **运行原理**：内部机制、价值说明、架构图解 |
| [COMMIT_MESSAGE_SPEC.md](mcp_ai_commit/COMMIT_MESSAGE_SPEC.md) | **提交规范**：四要素结构化提交信息格式、严重性分级、示例 |
| [CONFIG_REFERENCE.md](mcp_ai_commit/CONFIG_REFERENCE.md) | **配置参考**：字段/类型/默认值（由 config.py 自动生成，勿手改） |
| [RETROSPECTIVE.md](RETROSPECTIVE.md) | **项目复盘**：阶段关键判断、主要挑战与应对、失败样本库（含未修复项）、经验去向 |

---

## 测试

```bash
# 全量测试
python -m unittest test_mcp_ai_commit test_ai_commit -v

# 仅端到端（真实拉起服务器子进程）
python -m unittest test_mcp_ai_commit.TestMcpServerEndToEnd -v
```

用例数随版本演进，运行上述命令即可获取当前数量。

**门禁在哪里真实生效**：`.github/workflows/ci.yml` 定义了 CI 门禁（全量测试 →
`./install.sh --gate`），但 **GitHub Actions 仅在仓库托管于 GitHub 时才会运行**；
本仓库当前远端是 Gitee，因此 CI 不会触发。**本机生效面是全局 `pre-push` 钩子**：
`./install.sh --all --yes` 安装后在 push 前自动执行同一条 `./install.sh --gate`
（编译 + 配置文档同步 + 门禁自证），失败即中止 push；门禁内容只有一处实现，
CI 与钩子都复用它。只对本项目生效（其他仓库静默放行，不误伤）；
暂不校验可 `MCP_AI_COMMIT_SKIP_PREPUSH=1 git push`（会留痕）；
随时可用 `./install.sh --verify-prepush` 自证。

---

## 独立 CLI

`ai_commit.py` 提供 CLI 入口（无需 MCP 客户端），适合脚本与 CI/CD：

```bash
python ai_commit.py --dry-run    # 仅打印建议的提交信息
python ai_commit.py --yes        # 自动确认并提交
python ai_commit.py --repo /path/to/repo -y   # 指定仓库（不必先 cd）
```

提交信息与 MCP 层由同一实现（`mcp_ai_commit/analyzer.py`）生成，两个入口
输出口径一致，均为四要素结构化格式，可被 commit-msg 钩子直接接受。
`--no-llm` 强制纯本地规则引擎；配置了 API 密钥时默认调用大模型润色措辞
（结构被破坏则自动回退规则结果）。