Mcp Git Commit Generator

开发 Python

🚀 MCP Git Commit Generator

MCP Git Commit Generator 借助 Model Context Protocol (MCP)，依据你暂存的 Git 更改自动生成符合规范的提交信息，助力高效的版本管理。

✨ 主要特性

自动生成提交信息：基于暂存的 Git 差异自动生成提交信息。
支持规范提交：支持 Conventional Commits 规范。
灵活的传输选项：MCP 服务器提供标准输入输出（默认）和 Server-Sent Events (SSE) 两种传输方式。
交互式检查界面：通过 MCP Inspector 提供交互式检查界面。

📦 安装要求

使用 Docker：需安装 Docker 以在容器中运行服务器。
使用 PyPI/uvx：需要 Python >= 3.13.5 以及 uv（推荐）或 pip。
版本控制：需安装 Git 进行版本控制。
兼容客户端：需要一个支持 MCP 的客户端，如带有 MCP 扩展的 VS Code、Claude Desktop、Cursor、Windsurf 等。

🚀 快速开始

📦 安装

你可以通过多种方式安装和使用 MCP Git Commit Generator：

选项 1：使用 uvx（推荐）

使用 uvx 是使用该包的最简单方式，它会自动管理虚拟环境：

uvx mcp-git-commit-generator

选项 2：从 PyPI 安装

pip install mcp-git-commit-generator

或者使用 uv：

uv pip install mcp-git-commit-generator

选项 3：使用 Docker

使用来自 GitHub Container Registry 的预构建 Docker 镜像（无需安装）：

docker run -i --rm --mount type=bind,src=${HOME},dst=${HOME} ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest

💻 配置 MCP 客户端

根据你的客户端，选择合适的配置方式：

VS Code

在 VS Code 的 mcp.json 文件（通常位于工作区的 .vscode/mcp.json）中添加以下配置之一：

使用 uvx（推荐）

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

使用 Docker

{
"servers": {
"mcp-git-commit-generator": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount",
"type=bind,src=${userHome},dst=${userHome}",
"ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest"
]
}
}
}

如果你想将配置添加到用户的 settings.json 文件中，可以这样做：

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

Cursor

在 Cursor 的 MCP 配置文件（通常位于 ~/.cursor/mcp.json）中添加以下配置之一：

使用 uvx（推荐）

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

使用 Docker

{
"mcpServers": {
"mcp-git-commit-generator": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount",
"type=bind,src=${userHome},dst=${userHome}",
"ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest"
]
}
}
}

Windsurf

在 Windsurf 的 MCP 服务器设置文件（通常位于 ~/.codeium/windsurf/mcp_config.json）中添加以下配置之一：

使用 uvx（推荐）

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

使用 Docker

{
"mcpServers": {
"mcp-git-commit-generator": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount",
"type=bind,src=${userHome},dst=${userHome}",
"ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest"
]
}
}
}

Claude Desktop

在 Claude Desktop 的配置文件（在 macOS 上通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json）中添加以下配置之一：

使用 uvx（推荐）

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

使用 Docker

{
"mcpServers": {
"mcp-git-commit-generator": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount",
"type=bind,src=${userHome},dst=${userHome}",
"ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest"
]
}
}
}

⚠️ 重要提示

Docker 配置中的 --mount 选项允许 Docker 容器访问你的主目录，使其能够处理文件系统中任何位置的 Git 仓库。使用 uvx 或 pip 安装时，不需要此挂载，因为工具直接在你的系统上运行。如果使用 Docker 时仓库位于其他位置，请调整挂载路径。

🚀 开始使用

安装包：使用上述方法之一安装包。
配置 MCP 客户端：使用上述配置之一配置你的 MCP 客户端。
暂存更改：在 Git 仓库中暂存一些更改：
```
git add 
```
使用工具：通过 MCP 客户端使用工具：
- 使用 check_git_status 查看当前仓库状态。
- 使用 generate_commit_message 创建符合规范的提交信息。
提交更改：使用生成的信息提交更改。

🛠️ 可用工具

`generate_commit_message`

根据你暂存的 Git 更改生成符合规范的提交信息。参数：

repo_path（字符串，可选）：Git 仓库的路径。如果省略，使用当前目录。
commit_type（字符串，可选）：符合规范的提交类型（例如，feat、fix、docs、style、refactor、perf、build、ci、test、chore、revert）。如果省略，类型将自动检测。
scope（字符串，可选）：更改的范围（例如，文件或模块名称）。如果省略，范围将根据更改的文件自动检测。用法：

暂存更改：git add
通过 MCP 客户端使用该工具生成提交信息。
工具将分析你暂存的更改并生成合适的符合规范的提交信息。

`check_git_status`

检查当前 Git 仓库的状态，包括已暂存、未暂存和未跟踪的文件。参数：

repo_path（字符串，可选）：Git 仓库的路径。如果省略，使用当前目录。用法：在生成提交信息之前，使用此工具查看当前 Git 仓库的状态。

👨‍💻 开发者指南

🛠️ 本地开发设置

如果你不想在开发中使用 Docker，可以在本地运行服务器：要求：

Python >= 3.13.5
MCP CLI >= 1.10.1
uv（用于依赖管理，可选但推荐）
Node.js（用于 Inspector UI，可选）
Python Debugger Extension（用于调试，可选）安装：

克隆仓库：

git clone https://github.com/theoklitosBam7/mcp-git-commit-generator.git
cd mcp-git-commit-generator

准备环境：有两种方法可以为这个项目设置环境。你可以根据自己的喜好选择其中一种。

注意：创建虚拟环境后，重新加载 VSCode 或终端以确保使用虚拟环境中的 Python。

方法	步骤
使用 `uv`	1. 创建虚拟环境：`uv venv` 2. 运行 VSCode 命令 "Python: Select Interpreter" 并选择创建的虚拟环境中的 Python 3. 安装依赖（包括开发依赖）：`uv pip install -r pyproject.toml --group dev` 4. 使用以下命令安装 `mcp-git-commit-generator`：`uv pip install -e .`。
使用 `pip`	1. 创建虚拟环境：`python -m venv .venv` 2. 运行 VSCode 命令 "Python: Select Interpreter" 并选择创建的虚拟环境中的 Python 3. 安装依赖：`pip install -e .`。 4. 安装 pip 开发依赖：`pip install -r requirements-dev.txt`。

（可选）安装 Inspector 依赖：
```
cd inspector
npm install
```

📦 发布到 PyPI

项目包含一个自动化的 PyPI 发布工作流（.github/workflows/pypi-publish.yml），它：

触发条件：当推送匹配 v*.*.* 模式的标签、手动触发工作流或向主分支提交拉取请求时触发。
构建：使用 build 包构建 Python 包分发。
发布：当推送标签时，使用可信发布（OIDC）自动发布到 PyPI。要发布新版本：

在 pyproject.toml 中更新版本。
创建并推送 Git 标签：git tag vX.Y.Z && git push origin vX.Y.Z
工作流将自动构建并发布到 PyPI。

🐳 使用 Docker 构建和运行

你可以使用 Docker 构建和运行 MCP Git Commit Generator。提供的 Dockerfile 使用多阶段构建，使用 uv 进行依赖管理，并以非根用户身份运行服务器以提高安全性。

构建 Docker 镜像

docker build -t mcp-git-commit-generator .

在容器中运行服务器（默认：stdio 传输）

你可以直接从 GitHub Container Registry 运行已发布的镜像。

docker run -d \
--name mcp-git-commit-generator \
ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest

默认情况下，容器运行：

mcp-git-commit-generator --transport stdio

如果你想使用 SSE 传输（用于 Inspector UI 或远程访问），可以覆盖入口点或手动运行：

docker run -d \
--name mcp-git-commit-generator \
-p 3001:3001 \
--entrypoint mcp-git-commit-generator \
ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest --transport sse --host 0.0.0.0 --port 3001

使用 SSE 时，服务器将在 http://localhost:3001 可用。

🖥️ 本地运行服务器

本地运行（不使用 Docker）：

按照本地开发设置部分的说明设置 uv 或 Python 环境。
从项目根目录运行：

mcp-git-commit-generator

```sh # 如果你在环境中安装了 mcp-git-commit-generator（默认：stdio） mcp-git-commit-generator ```

mcp-git-commit-generator with SSE transport

```sh mcp-git-commit-generator --transport sse ```

Using uv

```sh uv run -m mcp_git_commit_generator --transport sse ```

Using Python directly

```sh python -m mcp_git_commit_generator --transport sse ```

你可以指定其他选项，例如： ```sh python -m mcp_git_commit_generator --transport sse --host 0.0.0.0 --port 3001 -v ``` > 使用 SSE 时，服务器默认监听 `0.0.0.0:3001`，或根据上述选项指定的地址。 **注意**： - 如果你想使用 CLI 入口点，请确保包已安装且环境已激活。 - 不要使用位置参数（例如，`python -m mcp_git_commit_generator sse`）；始终使用选项，如 `--transport sse`。 - 可用的参数及其值如下： - `--transport`：传输类型（例如，`stdio`（默认）、`sse`）。 - `--host`：绑定服务器的主机（默认：`0.0.0.0`）。 - `--port`：绑定服务器的端口（默认：`3001`）。 - `-v`, `--verbose`：详细程度（例如，`-v`、`-vv`）。

🔎 启动 Inspector UI

从 inspector 目录运行：

npm run dev:inspector

Inspector UI 将在 http://localhost:5173 可用。

🗂️ 项目结构

.
├── .github/                # GitHub 工作流和问题模板
├── .gitignore
├── .markdownlint.jsonc
├── .python-version
├── .vscode/                # VSCode 配置
├── LICENSE
├── README.md
├── pyproject.toml          # Python 项目配置
├── requirements-dev.txt    # 开发依赖
├── uv.lock                 # Python 依赖锁定文件
├── Dockerfile              # Docker 构建文件
├── build/                  # 构建工件
├── src/                    # Python 源代码
│   └── mcp_git_commit_generator/
│       ├── __init__.py     # 主入口点
│       ├── __main__.py     # CLI 入口点
│       └── server.py       # 主服务器实现
└── inspector/              # Inspector 相关文件
├── package.json        # Node.js 依赖
└── package-lock.json

⚙️ 开发用高级 MCP 服务器配置

.vscode/mcp.json 文件配置了 VS Code 和相关工具如何连接到 MCP Git Commit Generator 服务器。该文件定义了可用的服务器传输方式及其连接详细信息，使你可以轻松在不同模式（默认是 stdio，可选 SSE）之间切换进行开发和调试。

示例开发 `mcp.json`

{
"servers": {
"mcp-git-commit-generator": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount",
"type=bind,src=${userHome},dst=${userHome}",
"ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest"
]
},
"sse-mcp-git-commit-generator": {
"type": "sse",
"url": "http://localhost:3001/sse"
},
"stdio-mcp-git-commit-generator": {
"type": "stdio",
"command": "${command:python.interpreterPath}",
"args": ["-m", "mcp_git_commit_generator", "--transport", "stdio"]
},
"uvx-mcp-git-commit-generator": {
"command": "uvx",
"args": ["mcp-git-commit-generator"]
}
}
}

mcp-git-commit-generator：在 Docker 容器中运行服务器（默认：stdio 传输），使用已发布的镜像。
sse-mcp-git-commit-generator：使用 Server-Sent Events (SSE) 在 http://localhost:3001/sse 连接到 MCP 服务器。仅在使用 --transport sse 运行服务器时有用。
stdio-mcp-git-commit-generator：使用标准输入输出 (stdio) 连接，将服务器作为子进程运行。这是默认的，也是本地开发和调试的推荐方式。
uvx-mcp-git-commit-generator：使用 uvx 自动从 PyPI 安装和运行包。

🐞 调试 MCP 服务器

注意：

MCP Inspector 是一个用于测试和调试 MCP 服务器的可视化开发工具。

所有调试模式都支持断点，因此你可以在工具实现代码中添加断点。

你可以在 Inspector UI 中直接测试工具参数：使用 Inspector 时，选择一个工具并在输入字段中提供参数，以模拟实际使用并调试参数处理。

调试模式	描述	调试步骤
MCP Inspector	使用 MCP Inspector 调试 MCP 服务器。	1. 安装 Node.js 2. 设置 Inspector：`cd inspector` 并执行 `npm install` 3. 打开 VS Code 调试面板。选择 `Debug in Inspector (Edge)` 或 `Debug in Inspector (Chrome)`。按 F5 开始调试。 4. 当 MCP Inspector 在浏览器中启动时，点击 `Connect` 按钮连接此 MCP 服务器。 5. 然后你可以 `List Tools`，选择一个工具，输入参数（见上述参数），并 `Run Tool` 来调试服务器代码。

⚙️ 默认端口和自定义设置

调试模式	端口	定义	自定义	注意
MCP Inspector	3001（服务器，仅 SSE）；5173 和 3000（Inspector）	tasks.json	编辑 launch.json、tasks.json、__init__.py、mcp.json 以更改上述端口。	无

💬 反馈

如果你有任何反馈或建议，请在 MCP Git Commit Generator GitHub 仓库上创建一个问题。

📄 许可证

0 条评论
分类：开发

Mcp Git Commit Generator