Skip to main content
Glama
ai-commit-helper-mcp

ai-commit-helper-mcp

by mahshid

AI Commit Helper

Three commit-message suggestions from the changes you've staged, using your repository's preferred format. Works with Codex CLI and Claude Code.

Built with TypeScript, the MCP SDK, and Zod, AI Commit Helper uses skills to guide Codex and Claude Code through generating commit messages. It supports formats like feat: add password reset and #234 Add password reset, and validates each suggestion against your repository’s format and length limit.

You choose the message. The plugin doesn't stage files, create commits, or push.

Install

You'll need Git, Node.js, npm, and either Codex CLI or Claude Code with plugin support. I used Node.js 26.6.0 and npm 11.18.0 during development.

Clone or download this repository, open a terminal in its root, and build the server.

npm ci
npm run build
npm link

Then install the plugin in your preferred tool. You can install it in both.

Codex CLI

Run these commands from the repository root.

codex plugin marketplace add .
codex plugin add ai-commit-helper@commit-helper-dev
codex plugin list --marketplace commit-helper-dev

Claude Code

Run these commands from the repository root.

claude plugin marketplace add ./
claude plugin install ai-commit-helper@commit-helper-dev --scope user
claude plugin list

Claude Code uses the catalog in .claude-plugin/marketplace.json. Codex uses .agents/plugins/marketplace.json. Both point to plugins/ai-commit-helper and share the same skills and server.

Open a fresh session after installation. Run /mcp inside your chosen tool to check that the helper's server is connected.

This is a local installation. Keep the checkout where it is, since npm link points to the built server inside it. Installing the plugin alone doesn't build or install the server.

Related MCP server: mcp-dev-tools

Use the commit message helper

Stage the changes you want to describe, then start Codex or Claude Code.

git add README.md

Action

Codex CLI

Claude Code

Suggest messages

$ai-commit-helper:commit-msg

/ai-commit-helper:commit-msg

Set up repository rules

$ai-commit-helper:setup-commit-helper

/ai-commit-helper:setup-commit-helper

If no rules are saved, choose the defaults or configure the repository. For ticket messages, include the ticket number in your request.

# Codex
$ai-commit-helper:commit-msg Use ticket 234.

# Claude Code
/ai-commit-helper:commit-msg Use ticket 234.

Choose one of the three suggestions, review it, and commit it yourself. If interactive choices aren't available, reply with the option number. The helper stops if nothing is staged or it can't read or validate the changes.

Repository rules

Run the setup skill to choose a format and maximum title length. It creates .commit-helper.json in the repository root, even if nothing is staged. It won't overwrite an existing file.

You can also create or edit the file yourself.

{
  "format": "ticket",
  "maxSubjectLength": 100
}

Format

Example

typed

feat: add password reset or fix(auth): handle expired tokens

ticket

#234 Add password reset

Messages must be a single line. The length limit includes the prefix and spaces. Typed messages use a lowercase type with an optional scope. The validator doesn't currently support the breaking-change ! marker.

Without a file, the defaults are typed and 72. Choosing defaults doesn't save them, so the skill asks again on a later run. Use setup to save your preferences and skip that question.

Both fields are required. Invalid JSON, extra fields, unsupported formats, and length limits that aren't positive integers cause an error. Commit the configuration file if you want your team to share the same rules.

How it works

The MCP server reads the staged diff and repository rules, then validates three suggestions generated by Codex or Claude Code.

Tool

Purpose

get_commit_context

Read the staged diff and active rules.

validate_commit_message

Check a message's format and length.

create_commit_rules

Save rules without overwriting existing ones.

No separate AI API key is needed. Unstaged changes are ignored, and you should review each suggestion for accuracy.

Development

Build before running the tests. They use Node's built-in test runner and import the compiled files from build.

npm run build
node --test tests/validate.test.mjs

To try the tools directly, start MCP Inspector.

npx @modelcontextprotocol/inspector ai-commit-helper-mcp

Use an absolute repository path. Subdirectory paths work too, since the server finds the repository root. Use a disposable Git repository to test configuration creation and the refusal to overwrite an existing file.

To load the plugin temporarily in Claude Code, run this from the project root.

claude --plugin-dir ./plugins/ai-commit-helper

After changing TypeScript, rebuild and restart the agent session. Changes to installed skills or plugin configuration may also require refreshing or reinstalling the plugin.

Troubleshooting

Starting the server gives a permission error.

On macOS or Linux, run this from the checkout, then try again.

chmod u+x build/mcp.js

The server starts but prints nothing.

That's expected when you run it alone. It communicates over stdio and waits for an MCP client such as Codex, Claude Code, or Inspector. Don't add console.log debugging to the server's stdout. Use console.error for diagnostic messages.

Suggestions describe an older version of my changes.

Check git diff --staged. Saving a file doesn't update its staged version, and generating suggestions doesn't clear the staging area.

Choice prompts don't appear.

Their availability depends on the host and session mode. The skills fall back to asking for a text reply.

License

ISC

Available Tools

3 tools
create_commit_rulesB

Create a .commit-helper.json file in the repository root using the user's chosen commit-message rules. Fails if the file already exists.

Inputs: rules (required), repositoryPath (required).

get_commit_contextB

Get the staged Git diff and effective commit-message rules for a local repository. Returns a status of "changes" or "no_changes", the diff, and the rules to use when generating commit-message suggestions.

Inputs: repositoryPath (required).

validate_commit_messageA

Validate a proposed commit message against the target repository's configured format and maximum subject length. Returns whether the message is valid and a list of validation errors.

Inputs: message (required), repositoryPath (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: one retrieves context (diff + rules), one validates a message, one writes a rules file. There is no realistic overlap that would cause an agent to pick the wrong tool.

    Naming Consistency5/5

    All three tools follow a strict verb_noun snake_case pattern (get_/validate_/create_ + commit-related noun). The naming is predictable and self-documenting.

    Tool Count4/5

    Three tools is on the thin side but fits a narrowly scoped commit-message helper; each tool earns its place. No filler or redundant tools are present.

    Completeness3/5

    The read/validate/create surface is coherent, but create_commit_rules explicitly fails when a config already exists and there is no update or delete counterpart, leaving a real dead end for modifying rules. Agents would have to fall back to manual file editing for edits or removal.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Automatically generates conventional commit messages from staged git changes and checks repository status. Analyzes git diffs to create properly formatted commit messages following conventional commit standards.
      2
      9
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Codex users to review workspace and staged files, preview diffs, stage or unstage changes, generate AI-written Chinese Conventional Commit messages from staged diffs, and switch, merge, update, and push branches from a local panel. All Git operations run through a locally registered MCP service without a cloud deployment.
      MIT