ai-commit-helper-mcp
# 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.
```bash
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.
```bash
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.
```bash
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.
## Use the commit message helper
Stage the changes you want to describe, then start Codex or Claude Code.
```bash
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.
```text
# 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.
```json
{
"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`.
```bash
npm run build
node --test tests/validate.test.mjs
```
To try the tools directly, start MCP Inspector.
```bash
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.
```bash
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.
```bash
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](LICENSE)
TDQS
Scored across 3 tools
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.
All three tools follow a strict verb_noun snake_case pattern (get_/validate_/create_ + commit-related noun). The naming is predictable and self-documenting.
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.
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.