# MCP Git Commit Generator
[](https://pypi.org/project/mcp-git-commit-generator/)
[](https://github.com/theoklitosBam7/mcp-git-commit-generator/releases)
[](https://github.com/theoklitosBam7/mcp-git-commit-generator/actions/workflows/pypi-publish.yml)
[](https://github.com/theoklitosBam7/mcp-git-commit-generator/actions/workflows/docker-publish.yml)
[](https://github.com/theoklitosBam7/mcp-git-commit-generator/blob/main/LICENSE)
Generate conventional commit messages from your staged git changes using Model Context Protocol (MCP).
## ✨ Features
- **Automatic commit message generation** based on staged git diffs.
- Supports [Conventional Commits](https://www.conventionalcommits.org/).
- MCP server with both stdio (default) and SSE transport options.
- Inspector UI for interactive inspection (via MCP Inspector).
## 📦 Requirements
- **For Docker usage**: [Docker](https://www.docker.com/) (for running the server in a container)
- **For PyPI/uvx usage**: [Python](https://www.python.org/) >= 3.13.5 and [uv](https://github.com/astral-sh/uv)
(recommended) or pip
- [Git](https://git-scm.com/) (for version control)
- An MCP-compatible client (VS Code with MCP extension, Claude Desktop, Cursor, Windsurf, etc.)
## 🚀 Installation
You can install and use the MCP Git Commit Generator in multiple ways:
### Option 1: Using uvx (Recommended)
The easiest way to use the package is with `uvx`, which automatically manages the virtual environment:
```sh
uvx mcp-git-commit-generator
```
### Option 2: Install from PyPI
```sh
pip install mcp-git-commit-generator
```
Or with uv:
```sh
uv pip install mcp-git-commit-generator
```
### Option 3: Using Docker
Use the pre-built Docker image from GitHub Container Registry (no installation required):
```sh
docker run -i --rm --mount type=bind,src=${HOME},dst=${HOME} ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest
```
## 🛠️ Available Tools
This MCP server provides the following tools to help you generate conventional commit messages:
### `generate_commit_message`
Generates a conventional commit message based on your staged git changes.
**Parameters:**
- `repo_path` (string, optional): Path to the git repository. If omitted, uses the current directory.
- `commit_type` (string, optional): Conventional commit type (e.g., `feat`, `fix`, `docs`, `style`, `refactor`,
`perf`, `build`, `ci`, `test`, `chore`, `revert`). If omitted, the type will be auto-detected.
- `scope` (string, optional): Scope of the change (e.g., file or module name). If omitted, the scope will be
auto-detected based on changed files.
**Usage:**
1. Stage your changes: `git add <files>`
2. Use the tool through your MCP client to generate a commit message
3. The tool will analyze your staged changes and generate an appropriate conventional commit message
### `check_git_status`
Checks the current git repository status, including staged, unstaged, and untracked files.
**Parameters:**
- `repo_path` (string, optional): Path to the git repository. If omitted, uses the current directory.
**Usage:**
Use this tool to get an overview of your current git repository state before generating commit messages.
## 🧩 MCP Client Configuration
Configure the MCP Git Commit Generator in your favorite MCP client. You have multiple options:
1. **Using uvx** (recommended - automatically manages dependencies)
2. **Using Docker** (no local Python installation required)
3. **Using local Python installation** (for development)
### VS Code
Add one of the following configurations to your VS Code `mcp.json` file (usually located at `.vscode/mcp.json` in your workspace):
#### Using uvx (Recommended)
```jsonc
{
"servers": {
"mcp-git-commit-generator": {
"command": "uvx",
"args": ["mcp-git-commit-generator"]
}
}
}
```
#### Using Docker
```jsonc
{
"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"
]
}
}
}
```
If you want to put the configuration in your user `settings.json` file, you can do so by adding:
```jsonc
{
"mcp": {
"servers": {
"mcp-git-commit-generator": {
"command": "uvx",
"args": ["mcp-git-commit-generator"]
}
}
}
}
```
### Cursor
Add one of the following to your Cursor MCP configuration file (usually located at `~/.cursor/mcp.json`):
#### Cursor with uvx (Recommended)
```jsonc
{
"mcpServers": {
"mcp-git-commit-generator": {
"command": "uvx",
"args": ["mcp-git-commit-generator"]
}
}
}
```
#### Cursor with Docker
```jsonc
{
"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
Configure Windsurf with one of the following MCP server settings (usually located at `~/.codeium/windsurf/mcp_config.json`):
#### Windsurf with uvx (Recommended)
```jsonc
{
"mcpServers": {
"mcp-git-commit-generator": {
"command": "uvx",
"args": ["mcp-git-commit-generator"]
}
}
}
```
#### Windsurf with Docker
```jsonc
{
"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
Add one of the following to your Claude Desktop configuration file (usually located at
`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
#### Claude Desktop with uvx (Recommended)
```jsonc
{
"mcpServers": {
"mcp-git-commit-generator": {
"command": "uvx",
"args": ["mcp-git-commit-generator"]
}
}
}
```
#### Claude Desktop with Docker
```jsonc
{
"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"
]
}
}
}
```
> **Note**: The `--mount` option in Docker configurations allows the Docker container to access your home
> directory, enabling it to work with git repositories located anywhere in your file system. When using uvx or pip
> installations, this mounting is not needed as the tool runs directly on your system. Adjust the mount path if your
> repositories are located elsewhere when using Docker.
## 🚀 Quick Start Guide
1. **Install the package** using one of the methods above:
- **Recommended**: `uvx mcp-git-commit-generator` (or configure in your MCP client)
- **Alternative**: `pip install mcp-git-commit-generator`
- **Docker**: Use the configurations above with Docker
2. **Configure your MCP client** using one of the configurations above
3. **Stage some changes** in a git repository:
```sh
git add <files>
```
4. **Use the tools** through your MCP client:
- Use `check_git_status` to see your current repository state
- Use `generate_commit_message` to create a conventional commit message
5. **Commit your changes** with the generated message
---
## 👨💻 Developer Guidelines
The following sections are intended for developers who want to contribute to or modify the MCP Git Commit Generator.
### Local Development Setup 🛠️
If you prefer not to use Docker for development, you can run the server locally:
**Requirements:**
- [Python](https://www.python.org/) >= 3.13.5
- [MCP CLI](https://pypi.org/project/mcp/) >= 1.10.1
- [uv](https://github.com/astral-sh/uv) (for dependency management, optional but recommended)
- [Node.js](https://nodejs.org/en) (for Inspector UI, optional)
- [Python Debugger Extension](https://marketplace.visualstudio.com/items?itemName=ms-python.debugpy) (for debugging, optional)
**Installation:**
1. **Clone the repository:**
```sh
git clone https://github.com/theoklitosBam7/mcp-git-commit-generator.git
cd mcp-git-commit-generator
```
2. **Prepare environment:**
There are two approaches to set up the environment for this project. You can choose either one based on your preference.
> Note: Reload VSCode or terminal to ensure the virtual environment python is used after creating the virtual environment.
| Approach | Steps |
| -------- | ----- |
| Using `uv` | 1. Create virtual environment: `uv venv` <br>2. Run VSCode Command "***Python: Select Interpreter***" and select the python from created virtual environment <br>3. Install dependencies (include dev dependencies): `uv pip install -r pyproject.toml --group dev` <br>4. Install `mcp-git-commit-generator` using the command: `uv pip install -e .`. |
| Using `pip` | 1. Create virtual environment: `python -m venv .venv` <br>2. Run VSCode Command "***Python: Select Interpreter***" and select the python from created virtual environment <br>3. Install dependencies: `pip install -e .`. <br>4. Install pip dev dependencies: `pip install -r requirements-dev.txt`. |
3. **(Optional) Install Inspector dependencies:**
```sh
cd inspector
npm install
```
### 📦 Publishing to PyPI
The project includes an automated PyPI publishing workflow (`.github/workflows/pypi-publish.yml`) that:
- **Triggers on**: Tag pushes matching `v*.*.*` pattern, manual workflow dispatch, or pull requests to main
- **Builds**: Python package distributions using the `build` package
- **Publishes**: Automatically publishes to PyPI using trusted publishing (OIDC) when tags are pushed
To publish a new version:
1. Update the version in `pyproject.toml`
2. Create and push a git tag: `git tag vX.Y.Z && git push origin vX.Y.Z`
3. The workflow will automatically build and publish to PyPI
### 🐳 Building and Running with Docker
You can build and run the MCP Git Commit Generator using Docker. The provided Dockerfile uses a multi-stage build
with [`uv`](https://github.com/astral-sh/uv) for dependency management and runs the server as a non-root user for security.
#### Build the Docker image
```sh
docker build -t mcp-git-commit-generator .
```
#### Run the server in a container (default: stdio transport)
You can run the published image directly from GitHub Container Registry.
```sh
docker run -d \
--name mcp-git-commit-generator \
ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest
```
By default, the container runs:
```sh
mcp-git-commit-generator --transport stdio
```
If you want to use SSE transport (for Inspector UI or remote access), override the entrypoint or run manually:
```sh
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
```
The server will be available at `http://localhost:3001` when using SSE.
### 🖥️ Running the Server Locally
**To run locally (without Docker):**
1. Set up your uv or Python environment as described in the Local Development Setup section.
2. From the project root, run:
<details>
<summary>mcp-git-commit-generator</summary>
```sh
# If you have mcp-git-commit-generator installed in your environment (default: stdio)
mcp-git-commit-generator
```
</details>
<details>
<summary>mcp-git-commit-generator with SSE transport</summary>
```sh
mcp-git-commit-generator --transport sse
```
</details>
<details>
<summary>Using uv</summary>
```sh
uv run -m mcp_git_commit_generator --transport sse
```
</details>
<details>
<summary>Using Python directly</summary>
```sh
python -m mcp_git_commit_generator --transport sse
```
</details>
<br/>
You can specify other options, for example:
```sh
python -m mcp_git_commit_generator --transport sse --host 0.0.0.0 --port 3001 -v
```
> The server listens on `0.0.0.0:3001` by default when using SSE, or as specified by the options above.
**Note:**
- If you want to use the CLI entrypoint, ensure the package is installed and your environment is activated.
- Do not use positional arguments (e.g., `python -m mcp_git_commit_generator sse`);
always use options like `--transport sse`.
- Available arguments with their values are:
- `--transport`: Transport type (e.g., `stdio` (default), `sse`).
- `--host`: Host to bind the server (default: `0.0.0.0`).
- `--port`: Port to bind the server (default: `3001`).
- `-v`, `--verbose`: Verbosity level (e.g., `-v`, `-vv`).
### 🔎 Start the Inspector UI
From the `inspector` directory:
```sh
npm run dev:inspector
```
> The Inspector UI will be available at `http://localhost:5173`.
### 🗂️ Project Structure
```sh
.
├── .github/ # GitHub workflows and issue templates
├── .gitignore
├── .markdownlint.jsonc
├── .python-version
├── .vscode/ # VSCode configuration
├── LICENSE
├── README.md
├── pyproject.toml # Python project configuration
├── requirements-dev.txt # Development dependencies
├── uv.lock # Python dependencies lock file
├── Dockerfile # Docker build file
├── build/ # Build artifacts
├── src/ # Python source code
│ └── mcp_git_commit_generator/
│ ├── __init__.py # Main entry point
│ ├── __main__.py # CLI entry point
│ └── server.py # Main server implementation
└── inspector/ # Inspector related files
├── package.json # Node.js dependencies
└── package-lock.json
```
### ⚙️ Advanced MCP Server Configuration for Development
The `.vscode/mcp.json` file configures how VS Code and related tools connect to your MCP Git Commit Generator server.
This file defines available server transports and their connection details, making it easy to switch between
different modes (stdio is default, SSE is optional) for development and debugging.
#### Example Development `mcp.json`
```jsonc
{
"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**: Runs the server in a Docker container (default: stdio transport), using the published image.
- **sse-mcp-git-commit-generator**: Connects to the MCP server using Server-Sent Events (SSE) at `http://localhost:3001/sse`.
Only useful if you run the server with `--transport sse`.
- **stdio-mcp-git-commit-generator**: Connects using standard input/output (stdio), running the server as a subprocess.
This is the default and recommended for local development and debugging.
- **uvx-mcp-git-commit-generator**: Uses uvx to automatically install and run the package from PyPI.
### 🐞 Debugging the MCP Server
> Notes:
>
> - [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a visual developer tool for testing
and debugging MCP servers.
> - All debugging modes support breakpoints, so you can add breakpoints to the tool implementation code.
> - **You can test tool arguments directly in the Inspector UI**: When using the Inspector, select a tool and provide
arguments in the input fields to simulate real usage and debug argument handling.
| Debug Mode | Description | Steps to debug |
| ---------- | ----------- | --------------- |
| MCP Inspector | Debug the MCP server using the MCP Inspector. | 1. Install [Node.js](https://nodejs.org/)<br> 2. Set up Inspector: `cd inspector` && `npm install` <br> 3. Open VS Code Debug panel. Select `Debug in Inspector (Edge)` or `Debug in Inspector (Chrome)`. Press F5 to start debugging.<br> 4. When MCP Inspector launches in the browser, click the `Connect` button to connect this MCP server.<br> 5. Then you can `List Tools`, select a tool, input parameters (see arguments above), and `Run Tool` to debug your server code.<br> |
### ⚙️ Default Ports and Customizations
| Debug Mode | Ports | Definitions | Customizations | Note |
| ---------- | ----- | ------------ | -------------- |-------------- |
| MCP Inspector | 3001 (Server, SSE only); 5173 and 3000 (Inspector) | [tasks.json](.vscode/tasks.json) | Edit [launch.json](.vscode/launch.json), [tasks.json](.vscode/tasks.json), [\_\_init\_\_.py](src/__init__.py), [mcp.json](.vscode/mcp.json) to change above ports.| N/A |
## 💬 Feedback
If you have any feedback or suggestions, please open an issue on the [MCP Git Commit Generator GitHub repository](https://github.com/theoklitosBam7/mcp-git-commit-generator/issues)
## 📄 License
[MIT](./LICENSE) License © 2025 [Theoklitos Bampouris](https://github.com/theoklitosBam7)
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-git-commit-generator",
"maintainer": "Theoklitos Bampouris",
"docs_url": null,
"requires_python": ">=3.13.5",
"maintainer_email": "Theoklitos Bampouris <th.bampouris@gmail.com>",
"keywords": "mcp, model context protocol, git, commit, conventional commits, conventional commit messages",
"author": "Theoklitos Bampouris",
"author_email": "Theoklitos Bampouris <th.bampouris@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/27/ed/d682465bb80cbdbc02680131cee642912e50477e3b39405296c7052f968d/mcp_git_commit_generator-2.0.3.tar.gz",
"platform": null,
"description": "# MCP Git Commit Generator\n\n[](https://pypi.org/project/mcp-git-commit-generator/)\n[](https://github.com/theoklitosBam7/mcp-git-commit-generator/releases)\n[](https://github.com/theoklitosBam7/mcp-git-commit-generator/actions/workflows/pypi-publish.yml)\n[](https://github.com/theoklitosBam7/mcp-git-commit-generator/actions/workflows/docker-publish.yml)\n[](https://github.com/theoklitosBam7/mcp-git-commit-generator/blob/main/LICENSE)\n\nGenerate conventional commit messages from your staged git changes using Model Context Protocol (MCP).\n\n## \u2728 Features\n\n- **Automatic commit message generation** based on staged git diffs.\n- Supports [Conventional Commits](https://www.conventionalcommits.org/).\n- MCP server with both stdio (default) and SSE transport options.\n- Inspector UI for interactive inspection (via MCP Inspector).\n\n## \ud83d\udce6 Requirements\n\n- **For Docker usage**: [Docker](https://www.docker.com/) (for running the server in a container)\n- **For PyPI/uvx usage**: [Python](https://www.python.org/) >= 3.13.5 and [uv](https://github.com/astral-sh/uv)\n (recommended) or pip\n- [Git](https://git-scm.com/) (for version control)\n- An MCP-compatible client (VS Code with MCP extension, Claude Desktop, Cursor, Windsurf, etc.)\n\n## \ud83d\ude80 Installation\n\nYou can install and use the MCP Git Commit Generator in multiple ways:\n\n### Option 1: Using uvx (Recommended)\n\nThe easiest way to use the package is with `uvx`, which automatically manages the virtual environment:\n\n```sh\nuvx mcp-git-commit-generator\n```\n\n### Option 2: Install from PyPI\n\n```sh\npip install mcp-git-commit-generator\n```\n\nOr with uv:\n\n```sh\nuv pip install mcp-git-commit-generator\n```\n\n### Option 3: Using Docker\n\nUse the pre-built Docker image from GitHub Container Registry (no installation required):\n\n```sh\ndocker run -i --rm --mount type=bind,src=${HOME},dst=${HOME} ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest\n```\n\n## \ud83d\udee0\ufe0f Available Tools\n\nThis MCP server provides the following tools to help you generate conventional commit messages:\n\n### `generate_commit_message`\n\nGenerates a conventional commit message based on your staged git changes.\n\n**Parameters:**\n\n- `repo_path` (string, optional): Path to the git repository. If omitted, uses the current directory.\n- `commit_type` (string, optional): Conventional commit type (e.g., `feat`, `fix`, `docs`, `style`, `refactor`,\n `perf`, `build`, `ci`, `test`, `chore`, `revert`). If omitted, the type will be auto-detected.\n- `scope` (string, optional): Scope of the change (e.g., file or module name). If omitted, the scope will be\n auto-detected based on changed files.\n\n**Usage:**\n\n1. Stage your changes: `git add <files>`\n2. Use the tool through your MCP client to generate a commit message\n3. The tool will analyze your staged changes and generate an appropriate conventional commit message\n\n### `check_git_status`\n\nChecks the current git repository status, including staged, unstaged, and untracked files.\n\n**Parameters:**\n\n- `repo_path` (string, optional): Path to the git repository. If omitted, uses the current directory.\n\n**Usage:**\n\nUse this tool to get an overview of your current git repository state before generating commit messages.\n\n## \ud83e\udde9 MCP Client Configuration\n\nConfigure the MCP Git Commit Generator in your favorite MCP client. You have multiple options:\n\n1. **Using uvx** (recommended - automatically manages dependencies)\n2. **Using Docker** (no local Python installation required)\n3. **Using local Python installation** (for development)\n\n### VS Code\n\nAdd one of the following configurations to your VS Code `mcp.json` file (usually located at `.vscode/mcp.json` in your workspace):\n\n#### Using uvx (Recommended)\n\n```jsonc\n{\n \"servers\": {\n \"mcp-git-commit-generator\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-git-commit-generator\"]\n }\n }\n}\n```\n\n#### Using Docker\n\n```jsonc\n{\n \"servers\": {\n \"mcp-git-commit-generator\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"-i\",\n \"--rm\",\n \"--mount\",\n \"type=bind,src=${userHome},dst=${userHome}\",\n \"ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest\"\n ]\n }\n }\n}\n```\n\nIf you want to put the configuration in your user `settings.json` file, you can do so by adding:\n\n```jsonc\n{\n \"mcp\": {\n \"servers\": {\n \"mcp-git-commit-generator\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-git-commit-generator\"]\n }\n }\n }\n}\n```\n\n### Cursor\n\nAdd one of the following to your Cursor MCP configuration file (usually located at `~/.cursor/mcp.json`):\n\n#### Cursor with uvx (Recommended)\n\n```jsonc\n{\n \"mcpServers\": {\n \"mcp-git-commit-generator\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-git-commit-generator\"]\n }\n }\n}\n```\n\n#### Cursor with Docker\n\n```jsonc\n{\n \"mcpServers\": {\n \"mcp-git-commit-generator\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"-i\",\n \"--rm\",\n \"--mount\",\n \"type=bind,src=${userHome},dst=${userHome}\",\n \"ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest\"\n ]\n }\n }\n}\n```\n\n### Windsurf\n\nConfigure Windsurf with one of the following MCP server settings (usually located at `~/.codeium/windsurf/mcp_config.json`):\n\n#### Windsurf with uvx (Recommended)\n\n```jsonc\n{\n \"mcpServers\": {\n \"mcp-git-commit-generator\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-git-commit-generator\"]\n }\n }\n}\n```\n\n#### Windsurf with Docker\n\n```jsonc\n{\n \"mcpServers\": {\n \"mcp-git-commit-generator\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"-i\",\n \"--rm\",\n \"--mount\",\n \"type=bind,src=${userHome},dst=${userHome}\",\n \"ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest\"\n ]\n }\n }\n}\n```\n\n### Claude Desktop\n\nAdd one of the following to your Claude Desktop configuration file (usually located at\n`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n#### Claude Desktop with uvx (Recommended)\n\n```jsonc\n{\n \"mcpServers\": {\n \"mcp-git-commit-generator\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-git-commit-generator\"]\n }\n }\n}\n```\n\n#### Claude Desktop with Docker\n\n```jsonc\n{\n \"mcpServers\": {\n \"mcp-git-commit-generator\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"-i\",\n \"--rm\",\n \"--mount\",\n \"type=bind,src=${userHome},dst=${userHome}\",\n \"ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest\"\n ]\n }\n }\n}\n```\n\n> **Note**: The `--mount` option in Docker configurations allows the Docker container to access your home\n> directory, enabling it to work with git repositories located anywhere in your file system. When using uvx or pip\n> installations, this mounting is not needed as the tool runs directly on your system. Adjust the mount path if your\n> repositories are located elsewhere when using Docker.\n\n## \ud83d\ude80 Quick Start Guide\n\n1. **Install the package** using one of the methods above:\n - **Recommended**: `uvx mcp-git-commit-generator` (or configure in your MCP client)\n - **Alternative**: `pip install mcp-git-commit-generator`\n - **Docker**: Use the configurations above with Docker\n2. **Configure your MCP client** using one of the configurations above\n3. **Stage some changes** in a git repository:\n\n ```sh\n git add <files>\n ```\n\n4. **Use the tools** through your MCP client:\n - Use `check_git_status` to see your current repository state\n - Use `generate_commit_message` to create a conventional commit message\n5. **Commit your changes** with the generated message\n\n---\n\n## \ud83d\udc68\u200d\ud83d\udcbb Developer Guidelines\n\nThe following sections are intended for developers who want to contribute to or modify the MCP Git Commit Generator.\n\n### Local Development Setup \ud83d\udee0\ufe0f\n\nIf you prefer not to use Docker for development, you can run the server locally:\n\n**Requirements:**\n\n- [Python](https://www.python.org/) >= 3.13.5\n- [MCP CLI](https://pypi.org/project/mcp/) >= 1.10.1\n- [uv](https://github.com/astral-sh/uv) (for dependency management, optional but recommended)\n- [Node.js](https://nodejs.org/en) (for Inspector UI, optional)\n- [Python Debugger Extension](https://marketplace.visualstudio.com/items?itemName=ms-python.debugpy) (for debugging, optional)\n\n**Installation:**\n\n1. **Clone the repository:**\n\n ```sh\n git clone https://github.com/theoklitosBam7/mcp-git-commit-generator.git\n cd mcp-git-commit-generator\n ```\n\n2. **Prepare environment:**\n\n There are two approaches to set up the environment for this project. You can choose either one based on your preference.\n\n > Note: Reload VSCode or terminal to ensure the virtual environment python is used after creating the virtual environment.\n\n | Approach | Steps |\n | -------- | ----- |\n | Using `uv` | 1. Create virtual environment: `uv venv` <br>2. Run VSCode Command \"***Python: Select Interpreter***\" and select the python from created virtual environment <br>3. Install dependencies (include dev dependencies): `uv pip install -r pyproject.toml --group dev` <br>4. Install `mcp-git-commit-generator` using the command: `uv pip install -e .`. |\n | Using `pip` | 1. Create virtual environment: `python -m venv .venv` <br>2. Run VSCode Command \"***Python: Select Interpreter***\" and select the python from created virtual environment <br>3. Install dependencies: `pip install -e .`. <br>4. Install pip dev dependencies: `pip install -r requirements-dev.txt`. |\n\n3. **(Optional) Install Inspector dependencies:**\n\n ```sh\n cd inspector\n npm install\n ```\n\n### \ud83d\udce6 Publishing to PyPI\n\nThe project includes an automated PyPI publishing workflow (`.github/workflows/pypi-publish.yml`) that:\n\n- **Triggers on**: Tag pushes matching `v*.*.*` pattern, manual workflow dispatch, or pull requests to main\n- **Builds**: Python package distributions using the `build` package\n- **Publishes**: Automatically publishes to PyPI using trusted publishing (OIDC) when tags are pushed\n\nTo publish a new version:\n\n1. Update the version in `pyproject.toml`\n2. Create and push a git tag: `git tag vX.Y.Z && git push origin vX.Y.Z`\n3. The workflow will automatically build and publish to PyPI\n\n### \ud83d\udc33 Building and Running with Docker\n\nYou can build and run the MCP Git Commit Generator using Docker. The provided Dockerfile uses a multi-stage build\nwith [`uv`](https://github.com/astral-sh/uv) for dependency management and runs the server as a non-root user for security.\n\n#### Build the Docker image\n\n```sh\ndocker build -t mcp-git-commit-generator .\n```\n\n#### Run the server in a container (default: stdio transport)\n\nYou can run the published image directly from GitHub Container Registry.\n\n```sh\ndocker run -d \\\n --name mcp-git-commit-generator \\\n ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest\n```\n\nBy default, the container runs:\n\n```sh\nmcp-git-commit-generator --transport stdio\n```\n\nIf you want to use SSE transport (for Inspector UI or remote access), override the entrypoint or run manually:\n\n```sh\ndocker run -d \\\n --name mcp-git-commit-generator \\\n -p 3001:3001 \\\n --entrypoint mcp-git-commit-generator \\\n ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest --transport sse --host 0.0.0.0 --port 3001\n```\n\nThe server will be available at `http://localhost:3001` when using SSE.\n\n### \ud83d\udda5\ufe0f Running the Server Locally\n\n**To run locally (without Docker):**\n\n1. Set up your uv or Python environment as described in the Local Development Setup section.\n2. From the project root, run:\n\n <details>\n <summary>mcp-git-commit-generator</summary>\n\n ```sh\n # If you have mcp-git-commit-generator installed in your environment (default: stdio)\n mcp-git-commit-generator\n ```\n\n </details>\n\n <details>\n <summary>mcp-git-commit-generator with SSE transport</summary>\n\n ```sh\n mcp-git-commit-generator --transport sse\n ```\n\n </details>\n\n <details>\n <summary>Using uv</summary>\n\n ```sh\n uv run -m mcp_git_commit_generator --transport sse\n ```\n\n </details>\n\n <details>\n <summary>Using Python directly</summary>\n\n ```sh\n python -m mcp_git_commit_generator --transport sse\n ```\n\n </details>\n\n <br/>\n\n You can specify other options, for example:\n\n ```sh\n python -m mcp_git_commit_generator --transport sse --host 0.0.0.0 --port 3001 -v\n ```\n\n > The server listens on `0.0.0.0:3001` by default when using SSE, or as specified by the options above.\n\n**Note:**\n\n- If you want to use the CLI entrypoint, ensure the package is installed and your environment is activated.\n- Do not use positional arguments (e.g., `python -m mcp_git_commit_generator sse`);\nalways use options like `--transport sse`.\n- Available arguments with their values are:\n - `--transport`: Transport type (e.g., `stdio` (default), `sse`).\n - `--host`: Host to bind the server (default: `0.0.0.0`).\n - `--port`: Port to bind the server (default: `3001`).\n - `-v`, `--verbose`: Verbosity level (e.g., `-v`, `-vv`).\n\n### \ud83d\udd0e Start the Inspector UI\n\nFrom the `inspector` directory:\n\n```sh\nnpm run dev:inspector\n```\n\n> The Inspector UI will be available at `http://localhost:5173`.\n\n### \ud83d\uddc2\ufe0f Project Structure\n\n```sh\n.\n\u251c\u2500\u2500 .github/ # GitHub workflows and issue templates\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 .markdownlint.jsonc\n\u251c\u2500\u2500 .python-version\n\u251c\u2500\u2500 .vscode/ # VSCode configuration\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 pyproject.toml # Python project configuration\n\u251c\u2500\u2500 requirements-dev.txt # Development dependencies\n\u251c\u2500\u2500 uv.lock # Python dependencies lock file\n\u251c\u2500\u2500 Dockerfile # Docker build file\n\u251c\u2500\u2500 build/ # Build artifacts\n\u251c\u2500\u2500 src/ # Python source code\n\u2502 \u2514\u2500\u2500 mcp_git_commit_generator/\n\u2502 \u251c\u2500\u2500 __init__.py # Main entry point\n\u2502 \u251c\u2500\u2500 __main__.py # CLI entry point\n\u2502 \u2514\u2500\u2500 server.py # Main server implementation\n\u2514\u2500\u2500 inspector/ # Inspector related files\n \u251c\u2500\u2500 package.json # Node.js dependencies\n \u2514\u2500\u2500 package-lock.json\n```\n\n### \u2699\ufe0f Advanced MCP Server Configuration for Development\n\nThe `.vscode/mcp.json` file configures how VS Code and related tools connect to your MCP Git Commit Generator server.\nThis file defines available server transports and their connection details, making it easy to switch between\ndifferent modes (stdio is default, SSE is optional) for development and debugging.\n\n#### Example Development `mcp.json`\n\n```jsonc\n{\n \"servers\": {\n \"mcp-git-commit-generator\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"-i\",\n \"--rm\",\n \"--mount\",\n \"type=bind,src=${userHome},dst=${userHome}\",\n \"ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest\"\n ]\n },\n \"sse-mcp-git-commit-generator\": {\n \"type\": \"sse\",\n \"url\": \"http://localhost:3001/sse\"\n },\n \"stdio-mcp-git-commit-generator\": {\n \"type\": \"stdio\",\n \"command\": \"${command:python.interpreterPath}\",\n \"args\": [\"-m\", \"mcp_git_commit_generator\", \"--transport\", \"stdio\"]\n },\n \"uvx-mcp-git-commit-generator\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-git-commit-generator\"]\n }\n }\n}\n```\n\n- **mcp-git-commit-generator**: Runs the server in a Docker container (default: stdio transport), using the published image.\n- **sse-mcp-git-commit-generator**: Connects to the MCP server using Server-Sent Events (SSE) at `http://localhost:3001/sse`.\nOnly useful if you run the server with `--transport sse`.\n- **stdio-mcp-git-commit-generator**: Connects using standard input/output (stdio), running the server as a subprocess.\nThis is the default and recommended for local development and debugging.\n- **uvx-mcp-git-commit-generator**: Uses uvx to automatically install and run the package from PyPI.\n\n### \ud83d\udc1e Debugging the MCP Server\n\n> Notes:\n>\n> - [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a visual developer tool for testing\nand debugging MCP servers.\n> - All debugging modes support breakpoints, so you can add breakpoints to the tool implementation code.\n> - **You can test tool arguments directly in the Inspector UI**: When using the Inspector, select a tool and provide\narguments in the input fields to simulate real usage and debug argument handling.\n\n| Debug Mode | Description | Steps to debug |\n| ---------- | ----------- | --------------- |\n| MCP Inspector | Debug the MCP server using the MCP Inspector. | 1. Install [Node.js](https://nodejs.org/)<br> 2. Set up Inspector: `cd inspector` && `npm install` <br> 3. Open VS Code Debug panel. Select `Debug in Inspector (Edge)` or `Debug in Inspector (Chrome)`. Press F5 to start debugging.<br> 4. When MCP Inspector launches in the browser, click the `Connect` button to connect this MCP server.<br> 5. Then you can `List Tools`, select a tool, input parameters (see arguments above), and `Run Tool` to debug your server code.<br> |\n\n### \u2699\ufe0f Default Ports and Customizations\n\n| Debug Mode | Ports | Definitions | Customizations | Note |\n| ---------- | ----- | ------------ | -------------- |-------------- |\n| MCP Inspector | 3001 (Server, SSE only); 5173 and 3000 (Inspector) | [tasks.json](.vscode/tasks.json) | Edit [launch.json](.vscode/launch.json), [tasks.json](.vscode/tasks.json), [\\_\\_init\\_\\_.py](src/__init__.py), [mcp.json](.vscode/mcp.json) to change above ports.| N/A |\n\n## \ud83d\udcac Feedback\n\nIf you have any feedback or suggestions, please open an issue on the [MCP Git Commit Generator GitHub repository](https://github.com/theoklitosBam7/mcp-git-commit-generator/issues)\n\n## \ud83d\udcc4 License\n\n[MIT](./LICENSE) License \u00a9 2025 [Theoklitos Bampouris](https://github.com/theoklitosBam7)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate conventional commit messages from your staged git changes using Model Context Protocol (MCP).",
"version": "2.0.3",
"project_urls": {
"Homepage": "https://github.com/theoklitosBam7/mcp-git-commit-generator",
"Issues": "https://github.com/theoklitosBam7/mcp-git-commit-generator/issues"
},
"split_keywords": [
"mcp",
" model context protocol",
" git",
" commit",
" conventional commits",
" conventional commit messages"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d68d153c24df6b24ef7507a5147c8f60d18a20961ba58b761986dd3c2298ec8d",
"md5": "ef05af8e0648a4923d96ecffdce576f4",
"sha256": "af88c2a193cc0be32ccc94a34085a54c5e4a9b95183f00236d96b6458cde5c95"
},
"downloads": -1,
"filename": "mcp_git_commit_generator-2.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ef05af8e0648a4923d96ecffdce576f4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13.5",
"size": 11270,
"upload_time": "2025-08-10T17:07:34",
"upload_time_iso_8601": "2025-08-10T17:07:34.096118Z",
"url": "https://files.pythonhosted.org/packages/d6/8d/153c24df6b24ef7507a5147c8f60d18a20961ba58b761986dd3c2298ec8d/mcp_git_commit_generator-2.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "27edd682465bb80cbdbc02680131cee642912e50477e3b39405296c7052f968d",
"md5": "b1d3b14c8b1c0345878e100d700522a3",
"sha256": "8e6489161cbe755ece71f79ad19f827a68e3d79382d0cb447aa34ca0c5438e78"
},
"downloads": -1,
"filename": "mcp_git_commit_generator-2.0.3.tar.gz",
"has_sig": false,
"md5_digest": "b1d3b14c8b1c0345878e100d700522a3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13.5",
"size": 9699,
"upload_time": "2025-08-10T17:07:35",
"upload_time_iso_8601": "2025-08-10T17:07:35.235073Z",
"url": "https://files.pythonhosted.org/packages/27/ed/d682465bb80cbdbc02680131cee642912e50477e3b39405296c7052f968d/mcp_git_commit_generator-2.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 17:07:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "theoklitosBam7",
"github_project": "mcp-git-commit-generator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mcp-git-commit-generator"
}
JSON
