commit-check MCP
Validate commit messages, branch names, author info, push safety, and repo state.
Open source Open in the app JSON README (API)
About
Validate commit messages, branch names, author info, push safety, and repo state.
Details
- Kind
- MCP servers
- Topic
- Version control
- Publisher
- commit-check
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.10
- Stars
- 1
- Last push
- 2026-09-07T11:12:51Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:37
- Updated
- 2026-09-07 16:06:23
- Origin id
io.github.commit-check/commit-check-mcp
README
# commit-check-mcp
[](https://pypi.org/project/commit-check-mcp/)
[](https://pypi.org/project/commit-check-mcp/)
[](https://github.com/commit-check/commit-check-mcp/actions/workflows/main.yml)
[](https://codecov.io/gh/commit-check/commit-check-mcp)
[](https://modelcontextprotocol.io/)
[](https://registry.modelcontextprotocol.io/?q=commit-check-mcp)
[](https://glama.ai/mcp/servers/github/commit-check/commit-check-mcp)
Model Context Protocol (MCP) server for [commit-check](https://github.com/commit-check/commit-check).
`commit-check-mcp` exposes `commit-check` as local MCP tools so an MCP client can validate commit messages, branch names, author info, push safety, and repository state.
## Features
This MCP server exposes commit-check validations as MCP tools:
- `server_health` — returns server/sdk versions
- `validate_commit_message` — validates a commit message
- `validate_branch_name` — validates a branch name or the current repo branch
- `validate_push_safety` — validates that a push is not a force push (force pushes are always rejected by this tool)
- `validate_author_info` — validates author name/email or the repo's git author config
- `validate_commit_context` — runs combined checks in one call
- `validate_repository_state` — validates latest commit, current branch, author state, and optional push safety for a repo
- `describe_validation_rules` — returns the effective config and enabled rules after merging defaults and repo config
All validation tools return the same structured commit-check result shape:
```json
{
"status": "pass|fail|skip",
"warnings": 0,
"checks": [
{
"rule_id": "CC001",
"check": "message",
"status": "pass|fail|warn|skip",
"value": "...",
"error": "...",
"suggest": "...",
"fix": "...",
"docs_url": "https://commit-check.com/rules/#cc001"
}
]
}
```
`rule_id` is the stable id of the rule that produced the check and `docs_url`
links to its documentation.
Only `fail` is a rejection. A check reports `skip` when it did not run — the
author matched `ignore_authors`, or there was nothing to check — and the
top-level `status` is `skip` only when **every** check skipped, so a run that
validated nothing is never reported as a pass. A check reports `warn` when the
config lists it under `warn`: the finding is complete, but it does not fail
the run, the top-level `status` stays `pass`, and `warnings` counts them.
`suggest` is the advice a person reads. `fix` is the corrected value itself,
present only when the correction is unambiguous — `Fix: add x` comes back with
`"fix": "fix: add x"` — and an empty string otherwise, so an agent can apply
a non-empty `fix` as it stands and fall back to `suggest` when it is empty.
A call that cannot run at all — an empty `message`, a `repo_path` that does not
exist, a `repo_path` that is not a git repository when the tool has to read git
state (see the `repo_path` note under [Tool Usage](#tool-usage)), a malformed or rejected
commit-check config, a `push_refs` SHA that is not a commit in `repo_path` even
after the force-push check tried to fetch it — is returned as an MCP tool error
(`is_error`) whose text names the problem, for example
`repo_path is not a git repository: /path/to/dir`,
`invalid commit-check config: ...` or
`push_refs: <sha> is not a commit in the repository; fetch it first, the force-push check cannot be judged`,
rather than as a `pass`/`fail` result. In particular a push whose SHAs cannot
be judged is never reported as a pass.
## Installation
```bash
pip install commit-check-mcp
```
This installs the `commit-check-mcp` CLI entrypoint.
For local development from this repository:
```bash
pip install -e .
```
## Use With An MCP Client
This server runs over stdio, so it is meant to be launched by an MCP client rather than used as a long-running HTTP service.
With `uvx` (recommended — no install needed):
```bash
# Run once, no pip install required
uvx commit-check-mcp
```
> **Tip**: If `uv` is not installed, get it via `curl -LsSf https://astral.sh/uv/install.sh | sh`.
### Configure your client
Every client below launches the same command; only the config file and, for a
few clients, the wrapper key differ. This is the object to register:
```json
{
"mcpServers": {
"commit-check": {
"command": "uvx",
"args": ["commit-check-mcp"]
}
}
}
```
| Client | Where it goes | Notes |
|---|---|---|
| Claude Code | `claude mcp add commit-check -- uvx commit-check-mcp` | Add `--scope project` to write a shareable `.mcp.json` at the repo root (`--scope user` makes it available in all your projects). You can also commit a `.mcp.json` containing the block above; `"type": "stdio"` may be added inside the server object. MCP servers are **not** configured in `~/.claude/settings.json`. |
| Claude Desktop | macOS `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows `%APPDATA%\Claude\claude_desktop_config.json` | Block above as-is; restart Claude Desktop. |
| Cursor | project `.cursor/mcp.json` or global `~/.cursor/mcp.json` | Block above as-is (or **Settings → Cursor Settings → MCP → Add new MCP server** with command `uvx commit-check-mcp`). |
| VS Code (Copilot agent mode) | `.vscode/mcp.json` | **Different key**: `{"servers": {"commit-check": {"type": "stdio", "command": "uvx", "args": ["commit-check-mcp"]}}}` |
| Cline | MCP Servers panel → Configure → `cline_mcp_settings.json` (check your client's docs) | Block above as-is. |
| Roo Code | project `.roo/mcp.json` or global `mcp_settings.json` (**Edit Global MCP**) | Block above as-is; optional `"alwaysAllow": [...]`. |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` (check your client's docs) | Block above as-is. |
| Continue | `config.yaml` (or a file in `.continue/mcpServers/`) | **YAML list** under `mcpServers:`, see below. Continue also picks up the JSON block above when dropped into `.continue/mcpServers/`. |
| Zed | `~/.config/zed/settings.json` | **Different key**: `{"context_servers": {"commit-check": {"command": "uvx", "args": ["commit-check-mcp"]}}}` |
| Anything else | your client's MCP config | If the client cannot run `uvx`: `pip install commit-check-mcp`, then set `"command"` to the absolute path of the installed binary and drop `args`. Find it with `which commit-check-mcp` (macOS/Linux), `where commit-check-mcp` (Windows cmd) or `Get-Command commit-check-mcp \| Select-Object -ExpandProperty Source` (PowerShell). |
Continue's `config.yaml` entry in full (`name`, `version` and `schema` are required by Continue; drop them if you are adding only the `mcpServers` fragment to an existing file, or save this as a standalone file in `.continue/mcpServers/`):
```yaml
name: commit-check
version: 0.0.1
schema: v1
mcpServers:
- name: commit-check
command: uvx
args: ["commit-check-mcp"]
```
## Run Manually
```bash
# If installed via pip
commit-check-mcp
# Or via uvx (no install needed)
uvx commit-check-mcp
```
The server uses stdio transport, which is the recommended MCP default for local tool integrations.
## Tool Usage
After the client starts the server, it will expose these tools:
- `server_health`: returns server, SDK, and dependency versions
- `validate_commit_message(message, config?, repo_path?, config_path?)`
- `validate_branch_name(branch?, config?, repo_path?, config_path?)`
- `validate_push_safety(push_refs?, config?, repo_path?, config_path?)`
- `validate_author_info(author_name?, author_email?, config?, repo_path?, config_path?)`
- `validate_commit_context(message?, branch?, author_name?, author_email?, config?, repo_path?, config_path?)`
- `validate_repository_state(repo_path?, config?, config_path?, include_message?, include_branch?, include_author?, include_push?)`
- `describe_validation_rules(config?, repo_path?, config_path?)`
Every parameter carries a description in the tool's JSON input schema, so an
MCP client (and the model behind it) can see what each one expects without
reading this file: for example `push_refs` documents the git pre-push line
format `<local_ref> <local_sha> <remote_ref> <remote_sha>`. Each tool also has
a display `title` and MCP tool annotations: `destructiveHint: false` and
`idempotentHint: true` everywhere, `readOnlyHint: true` on the six tools that
only read, and `readOnlyHint: false` with `openWorldHint: true` on
`validate_push_safety` and `validate_repository_state`, because the force-push
check may run `git fetch` to resolve a SHA, which updates `FETCH_HEAD` and
remote-tracking refs (the working tree and commits are never touched). Clients
that gate tool calls on those hints can auto-approve the read-only six. The
server's `instructions` describe the intended
loop: validate first, read `status` (only `fail` rejects, `skip` is not
approval), apply a non-empty `fix` verbatim or follow `suggest`, then validate
again.
The common optional arguments are:
- `repo_path`: repository directory to validate against; it must be a git repository when the tool reads git state (branch, author, or push refs omitted, `validate_repository_state`, or `push_refs` given, whose SHAs must resolve there), and may be a plain directory holding a config file when every other value is supplied
- `config_path`: explicit TOML config file, used instead of the repository's own `cchk.toml`/`commit-check.toml`; relative paths resolve from `repo_path`
- `config`: ad-hoc config overrides merged on top of defaults and repo config
## Common Examples
Validate a commit message using repo-local rules:
```json
{
"message": "feat(api): add MCP validation tool",
"repo_path": "/path/to/repo"
}
```
Validate the current repository branch using an explicit config file:
```json
{
"repo_path": "/path/to/repo",
"config_path": ".github/commit-check.toml"
}
```
Validate the full repository state:
```json
{
"repo_path": "/path/to/repo",
"include_message": true,
"include_branch": true,
"include_author": true
}
```
Validate push safety from git pre-push hook ref metadata (`push_refs` must be non-empty when given; omit it to check the current branch against its upstream):
```json
{
"repo_path": "/path/to/repo",
"push_refs": "refs/heads/main abc123 refs/heads/main def456"
}
```
Inspect the final merged rules that will be applied:
```json
{
"repo_path": "/path/to/repo",
"config": {
"commit": {
"require_body": true
}
}
}
```
## Repository-Aware Validation
`commit-check` is most useful when it runs against a real git repository and its `cchk.toml` or `commit-check.toml` file. This MCP server now supports that directly:
- `repo_path` — run git-based validations against a specific repository
- `config_path` — point to an explicit TOML config file; relative paths are resolved from `repo_path`
- `config` — apply ad-hoc overrides on top of defaults and repo config
Typical patterns:
- Validate an explicit message with a repository's rules
- Validate the current repository state — the latest commit's message and author, and the current branch — without passing message/branch/author values manually
- Validate push safety using pre-push ref metadata, or check the current branch against its upstream
- Inspect which rules are actually enabled after config merging
Example payload for a repository-wide validation:
```json
{
"repo_path": "/path/to/repo",
"include_message": true,
"include_branch": true,
"include_author": true,
"include_push": true
}
```
Config precedence is:
1. `commit-check` built-in defaults
2. repository config loaded from `repo_path`, or the file named by `config_path` when it is provided (it replaces the repository's own config file)
3. inline `config` overrides passed to the tool
## Published On
| Directory | Link |
|---|---|
| **Official MCP Registry** | [`io.github.commit-check/commit-check-mcp`](https://registry.modelcontextprotocol.io/?q=commit-check-mcp) |
| **Glama.ai** | [`github/commit-check/commit-check-mcp`](https://glama.ai/mcp/servers/github/commit-check/commit-check-mcp) |
| **PyPI** | [`commit-check-mcp`](https://pypi.org/project/commit-check-mcp/) |
---
<!-- Required by MCP Registry for PyPI package ownership validation -->
<!-- https://registry.modelcontextprotocol.io -->
<sub>mcp-name: io.github.commit-check/commit-check-mcp</sub>