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。

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 Git Commit Generator GitHub 倉庫 上創建一個問題。

📄 許可證

本項目採用 MIT 許可證，版權所有 © 2025 Theoklitos Bampouris。