Skip to main content
Glama
theoklitosBam7

MCP Git Commit Generator

by theoklitosBam7
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

MCP Git Commit Generator

PyPI GitHub Release CI License

Generate Conventional Commit messages from staged Git changes through the Model Context Protocol (MCP).

MCP compatibility

This release uses the official Python MCP SDK v2 and targets the MCP 2026-07-28 specification.

The SDK can serve both protocol eras:

  • Modern clients use the 2026-07-28 server/discover flow.

  • Older clients can still use the legacy initialize handshake.

  • stdio is the default local transport.

  • streamable-http is the recommended network transport. Its default endpoint is /mcp.

  • sse remains available only for legacy integrations.

This server configures Streamable HTTP as stateless JSON because its tools do not need a server-to-client back-channel.

Related MCP server: git-auto-commit

Features

  • Generate a Conventional Commit prompt from staged changes only.

  • Inspect staged, unstaged, and untracked files.

  • Accept a repository root or a path inside a Git worktree.

  • Cap the staged diff preview at 1500 characters.

  • Treat repository text as untrusted model input.

  • Validate commit_type and scope before they enter a model prompt.

  • Run Git without a shell, external diff, pager, or interactive prompts.

  • Apply a 15-second timeout to Git commands.

  • Support stdio, Streamable HTTP, and legacy SSE.

  • Run the published container as a non-root user.

  • Test modern MCP 2026-07-28 and legacy MCP behavior.

Requirements

  • Python 3.14 or later.

  • Git.

  • An MCP-compatible client.

  • Optional: Docker.

  • Optional: Node.js 22.19 or later for MCP Inspector v2.

Install

uvx

uvx mcp-git-commit-generator

PyPI

pip install mcp-git-commit-generator

Docker

Mount only the repository that the server must inspect. A read-only mount is enough because the tools do not create commits or edit files.

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

Tools

generate_commit_message

Build a strict prompt for a Conventional Commit message from staged changes.

Parameters:

  • repo_path: optional repository path. A path inside a worktree is accepted.

  • commit_type: optional Conventional Commit type: feat, fix, docs, style, refactor, perf, build, ci, test, chore, or revert.

  • scope: optional 1-50 character scope. It can contain letters, numbers, ., _, /, and -.

check_git_status

Report the current branch plus staged, unstaged, and untracked files.

Parameter:

  • repo_path: optional repository path. A path inside a worktree is accepted.

Client configuration

uvx with stdio

Common MCP client format:

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

VS Code uses a top-level servers object:

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

Streamable HTTP

Start the local server:

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

Connect the client to:

http://127.0.0.1:3001/mcp

The HTTP mode has no application authentication. The default bind address is loopback for this reason. If you need remote access, put the server behind an authenticated TLS reverse proxy and restrict network access.

Legacy SSE

Older clients can still use SSE:

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

New integrations should use stdio or Streamable HTTP.

Development

Install the locked environment:

uv sync --all-groups

Run the checks:

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

MCP Inspector v2

Start the MCP server in one terminal from the repository root:

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

In another terminal, start Inspector with the local server configured:

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

Open the Inspector URL printed in the terminal, normally at http://127.0.0.1:6274. If the local server's connection switch is off, turn it on. Inspector calls the transport http; the Python server calls it streamable-http.

The /mcp URL is a protocol endpoint, not a web interface. Do not open it directly in the browser to use Inspector.

For VS Code debugging, select the project's .venv Python interpreter, install the Inspector dependencies with npm ci in inspector, and run Debug in Inspector (Chrome) or Debug in Inspector (Edge). These configurations start both processes and open Inspector on port 5173.

CI and supply-chain controls

The repository uses these controls:

  • GitHub Actions are pinned to full commit SHAs.

  • Python tests run on Linux, macOS, and Windows.

  • Python dependencies are locked with uv.lock and audited with pip-audit.

  • Inspector dependencies are locked with package-lock.json and checked with npm audit.

  • Pull requests use GitHub dependency review for high-severity dependency changes.

  • Dependabot checks uv, npm, GitHub Actions, and Docker dependencies.

  • Container builds produce provenance and an SBOM.

  • PyPI publishing uses GitHub OIDC trusted publishing and package attestations.

Security model

Repository names, paths, file contents, and diffs are attacker-controlled input. The server serializes repository context as JSON and tells the downstream model to use those values only as evidence about the change. It does not treat instructions hidden inside a staged diff as trusted instructions.

Git is executed as an argument list with shell=False behavior. The server disables external diffs, interactive prompts, and pagers for tool operations. It also applies a command timeout.

For Docker, prefer a narrow read-only repository mount instead of mounting the whole home directory.

Release

  1. Update version in pyproject.toml.

  2. Run all checks and refresh both lockfiles.

  3. Create a matching tag, for example v3.0.0.

  4. Push the tag.

Tag pushes build and publish the Python package and container image. PyPI uses trusted publishing.

License

MIT © 2025-2026 Theoklitos Bampouris

Available Tools

2 tools
check_git_statusC

Return staged, unstaged, and untracked files for a Git worktree.

ParametersJSON Schema
NameRequiredDescriptionDefault
repo_pathNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. 'Return' implies a read-only operation, but it does not disclose what happens with an invalid or missing repo_path, whether it errors outside a Git worktree, or any side effects, which leaves meaningful gaps for a zero-annotation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler that immediately conveys the tool's output. It is arguably terse to the point of omitting needed detail, but nothing in it is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the operation is simple. However, with no annotations and no parameter documentation, the description should at least clarify the repo_path default and error behavior to be complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and repo_path has a default of null, yet the description never mentions the parameter or explains what path it expects or what happens when it is omitted (current directory? default worktree?). With one undocumented, optional path parameter, this is a real gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Return') and resource ('staged, unstaged, and untracked files for a Git worktree'), so an agent knows exactly what it retrieves. It doesn't need sibling differentiation because generate_commit_message is plainly a different task, but it stops short of explicitly distinguishing the two.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says only what is returned; it gives no when-to-use guidance, no prerequisites (e.g. must be inside a repo), and no mention of the sibling generate_commit_message as a follow-on or alternative. Usage must be entirely inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_commit_messageB

Prepare a prompt for a Conventional Commit message from staged changes only.

ParametersJSON Schema
NameRequiredDescriptionDefault
scopeNo
repo_pathNo
commit_typeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses two traits: it produces a 'prompt' (not the message itself) and reads staged changes only, but it says nothing about mutation, permissions, or whether repo_path affects git state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero waste. The scope qualifier ('staged changes only') is placed where it matters, and nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, which helps. However, for a three-parameter tool with zero schema description coverage and no annotations, the description is too thin to fully orient the agent on the arguments it must supply.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across three parameters (scope, repo_path, commit_type). The description alludes to Conventional Commit conventions, which loosely maps to commit_type and scope, but it never explains any parameter's meaning or the repo_path argument, leaving the schema and description jointly silent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Prepare a prompt') and resource ('Conventional Commit message'), and adds the key scope qualifier 'from staged changes only'. The purpose is clear, but it does not explicitly distinguish itself from the sibling check_git_status or clarify that it produces a prompt rather than the commit itself in contrast to alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'from staged changes only' clause implies the appropriate context (changes must be staged first), but there is no explicit when-to-use guidance and no mention of alternatives such as check_git_status. Usage must be inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev3.0.0
    • Changedgenerate_commit_message1 field changed
      • changedInput schema / properties / commit_type / anyOf
        Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "feat",
+      "fix",
+      "docs",
+      "style",
+      "refactor",
+      "perf",
+      "build",
+      "ci",
+      "test",
+      "chore",
+      "revert"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
  2. 2 tool updates
    • First observedcheck_git_status
    • First observedgenerate_commit_message
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

B3.4/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one generates a commit-message prompt, while the other inspects Git worktree status. There is no meaningful overlap that would cause an agent to confuse them.

Naming Consistency5/5

Both names use snake_case with a consistent verb_noun structure. The pattern is predictable and easy to parse.

Tool Count3/5

The server has only 2 tools, which is thin even for a focused utility. They are relevant, but the set feels borderline minimal rather than well-scoped.

Completeness4/5

For a commit-message generator, the surface covers the core need: checking Git state and preparing a commit prompt from staged changes. Minor gaps remain, such as no direct way to inspect staged diffs separately or execute the commit, but those are outside the stated generator scope.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers