mcp-git-commit-generator

🚀 MCP Git Commit Generator

MCP Git Commit Generator 能够依据你暂存的 Git 更改，利用模型上下文协议（MCP）自动生成符合规范的提交信息，助力开发者更高效地管理代码提交。

项目徽章

✨ 主要特性

• 自动生成提交信息：基于暂存的 Git 差异自动生成提交信息。
• 支持规范提交：支持 Conventional Commits 规范。
• MCP 服务器：提供标准输入输出（默认）和 Server-Sent Events（SSE）两种传输选项。
• 交互式检查器 UI：可通过 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：

方式一：使用 uvx（推荐）

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

uvx mcp-git-commit-generator

方式二：从 PyPI 安装

pip install mcp-git-commit-generator

或者使用 uv 安装：

uv pip install mcp-git-commit-generator

方式三：使用 Docker

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

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

快速上手步骤

1. 安装包：选择上述任意一种安装方法进行安装。
   • 推荐：使用 uvx mcp-git-commit-generator（或在 MCP 客户端中进行配置）。
   • 其他选择：使用 pip install mcp-git-commit-generator。
   • 使用 Docker：按照上述 Docker 配置进行操作。
2. 配置 MCP 客户端：根据以下不同客户端的配置示例进行配置。
3. 暂存更改：在 Git 仓库中暂存一些更改：

git add <files>

4. 使用工具：通过 MCP 客户端使用工具：
   • 使用 check_git_status 查看当前仓库状态。
   • 使用 generate_commit_message 生成符合规范的提交信息。
5. 提交更改：使用生成的提交信息提交更改。

🛠️ 可用工具

generate_commit_message

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

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

1. 暂存更改：git add <files>
2. 通过 MCP 客户端使用该工具生成提交信息。
3. 工具将分析你暂存的更改，并生成合适的规范提交信息。

check_git_status

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

• repo_path（字符串，可选）：Git 仓库的路径。若未提供，则使用当前目录。 使用方法：在生成提交信息之前，使用该工具查看当前 Git 仓库的状态。

🧩 MCP 客户端配置

你可以在喜欢的 MCP 客户端中配置 MCP Git Commit Generator，有以下几种配置选项：

1. 使用 uvx（推荐 - 自动管理依赖）
2. 使用 Docker（无需本地安装 Python）
3. 使用本地 Python 安装（用于开发）

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 时仓库位于其他位置，请调整挂载路径。

👨‍💻 开发者指南

本地开发设置

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

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

安装步骤：

1. 克隆仓库：

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

2. 准备环境：有两种环境设置方法，你可以根据自己的喜好选择。

   注意：创建虚拟环境后，重新加载 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。 |

3. （可选）安装检查器依赖：

cd inspector
npm install

📦 发布到 PyPI

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

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

发布新版本的步骤如下：

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

🐳 使用 Docker 构建和运行

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

构建 Docker 镜像

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

在容器中运行服务器（默认：标准输入输出传输）

你可以直接从 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 在本地运行：

1. 按照本地开发设置部分的说明设置 uv 或 Python 环境。
2. 从项目根目录运行以下命令：

# 如果你已经在环境中安装了 mcp-git-commit-generator（默认：标准输入输出）
mcp-git-commit-generator

mcp-git-commit-generator --transport sse

uv run -m mcp_git_commit_generator --transport sse

python -m mcp_git_commit_generator --transport sse

你可以指定其他选项，例如：

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）。

🔎 启动检查器 UI

从 inspector 目录运行以下命令：

npm run dev: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/              # 检查器相关文件
    ├── package.json        # Node.js 依赖
    └── package-lock.json

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

.vscode/mcp.json 文件配置了 VS Code 及相关工具如何连接到 MCP Git Commit Generator 服务器。该文件定义了可用的服务器传输方式及其连接细节，方便在开发和调试时在不同模式（默认是标准输入输出，可选 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 容器中运行服务器（默认：标准输入输出传输），使用已发布的镜像。
• sse-mcp-git-commit-generator：使用 Server-Sent Events（SSE）连接到 MCP 服务器，地址为 http://localhost:3001/sse。仅在使用 --transport sse 运行服务器时有用。
• stdio-mcp-git-commit-generator：使用标准输入输出（stdio）进行连接，将服务器作为子进程运行。这是本地开发和调试的默认推荐方式。
• uvx-mcp-git-commit-generator：使用 uvx 自动从 PyPI 安装并运行包。

🐞 调试 MCP 服务器

💡 使用建议

• MCP Inspector 是一个用于测试和调试 MCP 服务器的可视化开发工具。
• 所有调试模式都支持断点，你可以在工具实现代码中添加断点。
• 你可以在检查器 UI 中直接测试工具参数：使用检查器时，选择一个工具并在输入字段中提供参数，以模拟实际使用并调试参数处理。

| 调试模式 | 描述 | 调试步骤 | | ---- | ---- | ---- | | MCP Inspector | 使用 MCP Inspector 调试 MCP 服务器。 | 1. 安装 Node.js。
2. 设置检查器：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（检查器） | tasks.json | 编辑 launch.json、tasks.json、__init__.py、mcp.json 来更改上述端口。 | 无 |

💬 反馈

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

📄 许可证

本项目采用 MIT 许可证，版权所有 © 2025 Theoklitos Bampouris。