commit-check-mcp

Model Context Protocol (MCP) server for 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:

{
  "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), 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

pip install commit-check-mcp

This installs the commit-check-mcp CLI entrypoint.

For local development from this repository:

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):

# 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:

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

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/):

name: commit-check
version: 0.0.1
schema: v1
mcpServers:
  - name: commit-check
    command: uvx
    args: ["commit-check-mcp"]

Run Manually

# 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:

{
  "message": "feat(api): add MCP validation tool",
  "repo_path": "/path/to/repo"
}

Validate the current repository branch using an explicit config file:

{
  "repo_path": "/path/to/repo",
  "config_path": ".github/commit-check.toml"
}

Validate the full repository state:

{
  "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):

{
  "repo_path": "/path/to/repo",
  "push_refs": "refs/heads/main abc123 refs/heads/main def456"
}

Inspect the final merged rules that will be applied:

{
  "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:

{
  "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

_{mcp-name: io.github.commit-check/commit-check-mcp}