Mcp Git Commit Generator

MCP Git Commit Generator

通过模型上下文协议（MCP），根据已暂存的 Git 更改生成 Conventional Commit 消息。

MCP 兼容性

此版本使用官方 Python MCP SDK v2，并以 MCP 2026-07-28 规范为目标。

该 SDK 可兼容两个协议时代：

• 新版客户端使用 2026-07-28 的 server/discover 流程。
• 较旧的客户端仍可使用旧版 initialize 握手。
• stdio 是默认的本地传输方式。
• streamable-http 是推荐的网络传输方式。其默认端点为 /mcp。
• sse 仅继续用于旧版集成。

此服务将 Streamable HTTP 配置为无状态 JSON，因为其工具不需要服务端到客户端的反向通道。

功能

• 仅根据已暂存的更改生成 Conventional Commit 提示词。
• 检查已暂存、未暂存和未跟踪的文件。
• 接受仓库根目录或 Git 工作树内的路径。
• 将已暂存差异预览限制在 1500 个字符以内。
• 将仓库文本视为不可信的模型输入。
• 在 commit_type 和 scope 进入模型提示词之前进行验证。
• 运行 Git 时不使用 shell、外部差异工具、分页器或交互式提示。
• 为 Git 命令设置 15 秒超时。
• 支持 stdio、Streamable HTTP 和旧版 SSE。
• 以非 root 用户运行已发布的容器。
• 测试现代 MCP 2026-07-28 和旧版 MCP 的行为。

要求

• Python 3.14 或更高版本。
• Git。
• 与 MCP 兼容的客户端。
• 可选：Docker。
• 可选：用于 MCP Inspector v2 的 Node.js 22.19 或更高版本。

安装

uvx

uvx mcp-git-commit-generator

PyPI

pip install mcp-git-commit-generator

Docker

仅挂载服务需要检查的仓库。只读挂载即可，因为这些工具不会创建提交或编辑文件。

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges:true \
  --mount type=bind,src="$PWD",dst="$PWD",readonly \
  ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest

工具

generate_commit_message

根据已暂存的更改，构建用于生成 Conventional Commit 消息的严格提示词。

参数：

• repo_path：可选的仓库路径。接受工作树内的路径。
• commit_type：可选的 Conventional Commit 类型：feat、fix、docs、style、refactor、perf、build、ci、test、chore 或 revert。
• scope：可选的 1–50 个字符的范围。可包含字母、数字、.、_、/ 和 -。

check_git_status

报告当前分支以及已暂存、未暂存和未跟踪的文件。

参数：

• repo_path：可选的仓库路径。接受工作树内的路径。

客户端配置

使用 stdio 的 uvx

常见的 MCP 客户端格式：

{
  "mcpServers": {
    "mcp-git-commit-generator": {
      "command": "uvx",
      "args": ["mcp-git-commit-generator"]
    }
  }
}

VS Code 使用顶层 servers 对象：

{
  "servers": {
    "mcp-git-commit-generator": {
      "command": "uvx",
      "args": ["mcp-git-commit-generator"]
    }
  }
}

Streamable HTTP

启动本地服务：

uv run mcp-git-commit-generator \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 3001

将客户端连接到：

http://127.0.0.1:3001/mcp

HTTP 模式没有应用身份验证。因此，默认绑定地址为环回地址。如果需要远程访问，请将服务置于经过身份验证的 TLS 反向代理之后，并限制网络访问。

旧版 SSE

较旧的客户端仍可使用 SSE：

uv run mcp-git-commit-generator \
  --transport sse \
  --host 127.0.0.1 \
  --port 3001

新的集成应使用 stdio 或 Streamable HTTP。

开发

安装锁定的环境：

uv sync --all-groups

运行检查：

uv run python -m compileall -q src tests
uv run pytest
uv run pip-audit --local
uv build

MCP Inspector v2

在一个终端中，从仓库根目录启动 MCP 服务：

uv run mcp-git-commit-generator \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 3001

在另一个终端中，使用本地服务配置启动 Inspector：

cd inspector
npm ci
npm run dev:inspector -- \
  --transport http \
  --server-url http://127.0.0.1:3001/mcp \
  --protocol-era modern

打开终端中显示的 Inspector URL，通常为 http://127.0.0.1:6274。如果本地服务的连接开关处于关闭状态，请将其打开。Inspector 将传输方式称为 http；Python 服务则称其为 streamable-http。

/mcp URL 是协议端点，不是 Web 界面。请勿直接在浏览器中打开它来使用 Inspector。

如需在 VS Code 中调试，请选择项目的 .venv Python 解释器，在 inspector 中使用 npm ci 安装 Inspector 依赖，然后运行 在 Inspector (Chrome) 中调试或在 Inspector (Edge) 中调试。这些配置会启动两个进程，并在端口 5173 上打开 Inspector。

CI 和供应链控制

此仓库使用以下控制措施：

• GitHub Actions 固定到完整的提交 SHA。
• Python 测试在 Linux、macOS 和 Windows 上运行。
• Python 依赖项使用 uv.lock 锁定，并通过 pip-audit 审计。
• Inspector 依赖项使用 package-lock.json 锁定，并通过 npm audit 检查。
• 拉取请求使用 GitHub 依赖项审查来检查高严重性依赖项变更。
• Dependabot 检查 uv、npm、GitHub Actions 和 Docker 依赖项。
• 容器构建会生成来源证明和 SBOM。
• 发布到 PyPI 使用 GitHub OIDC 可信发布和软件包证明。

安全模型

仓库名称、路径、文件内容和差异均为攻击者可控的输入。服务会将仓库上下文序列化为 JSON，并告知下游模型仅将这些值用作有关变更的证据。服务不会将暂存差异中隐藏的指令视为可信指令。

Git 以参数列表方式执行，行为等同于 shell=False。服务会为工具操作禁用外部差异、交互式提示和分页器。此外，服务还会设置命令超时。

使用 Docker 时，建议挂载范围较窄的只读仓库，而不要挂载整个主目录。

发布

1. 更新 pyproject.toml 中的 version。
2. 运行所有检查并更新两个锁文件。
3. 创建匹配的标签，例如 v3.0.0。
4. 推送标签。

推送标签会构建并发布 Python 软件包和容器映像。PyPI 使用可信发布。

许可证

MIT © 2025-2026 Theoklitos Bampouris