# commit-check-mcp

[![PyPI version](https://img.shields.io/pypi/v/commit-check-mcp)](https://pypi.org/project/commit-check-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/commit-check-mcp)](https://pypi.org/project/commit-check-mcp/)
[![Build](https://github.com/commit-check/commit-check-mcp/actions/workflows/main.yml/badge.svg)](https://github.com/commit-check/commit-check-mcp/actions/workflows/main.yml)
[![Coverage](https://codecov.io/gh/commit-check/commit-check-mcp/graph/badge.svg)](https://codecov.io/gh/commit-check/commit-check-mcp)
[![MCP server](https://img.shields.io/badge/MCP-server-0A7B83)](https://modelcontextprotocol.io/)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.commit--check/commit--check--mcp-7B3F00)](https://registry.modelcontextprotocol.io/?q=commit-check-mcp)
[![Glama](https://img.shields.io/badge/Glama-commit--check--mcp-blue)](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>