{
  "markdown": "# commit-check-mcp\n\n[![PyPI version](https://img.shields.io/pypi/v/commit-check-mcp)](https://pypi.org/project/commit-check-mcp/)\n[![Python versions](https://img.shields.io/pypi/pyversions/commit-check-mcp)](https://pypi.org/project/commit-check-mcp/)\n[![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)\n[![Coverage](https://codecov.io/gh/commit-check/commit-check-mcp/graph/badge.svg)](https://codecov.io/gh/commit-check/commit-check-mcp)\n[![MCP server](https://img.shields.io/badge/MCP-server-0A7B83)](https://modelcontextprotocol.io/)\n[![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)\n[![Glama](https://img.shields.io/badge/Glama-commit--check--mcp-blue)](https://glama.ai/mcp/servers/github/commit-check/commit-check-mcp)\n\nModel Context Protocol (MCP) server for [commit-check](https://github.com/commit-check/commit-check).\n\n`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.\n\n## Features\n\nThis MCP server exposes commit-check validations as MCP tools:\n\n- `server_health` — returns server/sdk versions\n- `validate_commit_message` — validates a commit message\n- `validate_branch_name` — validates a branch name or the current repo branch\n- `validate_push_safety` — validates that a push is not a force push (force pushes are always rejected by this tool)\n- `validate_author_info` — validates author name/email or the repo's git author config\n- `validate_commit_context` — runs combined checks in one call\n- `validate_repository_state` — validates latest commit, current branch, author state, and optional push safety for a repo\n- `describe_validation_rules` — returns the effective config and enabled rules after merging defaults and repo config\n\nAll validation tools return the same structured commit-check result shape:\n\n```json\n{\n  \"status\": \"pass|fail|skip\",\n  \"warnings\": 0,\n  \"checks\": [\n    {\n      \"rule_id\": \"CC001\",\n      \"check\": \"message\",\n      \"status\": \"pass|fail|warn|skip\",\n      \"value\": \"...\",\n      \"error\": \"...\",\n      \"suggest\": \"...\",\n      \"fix\": \"...\",\n      \"docs_url\": \"https://commit-check.com/rules/#cc001\"\n    }\n  ]\n}\n```\n\n`rule_id` is the stable id of the rule that produced the check and `docs_url`\nlinks to its documentation.\n\nOnly `fail` is a rejection. A check reports `skip` when it did not run — the\nauthor matched `ignore_authors`, or there was nothing to check — and the\ntop-level `status` is `skip` only when **every** check skipped, so a run that\nvalidated nothing is never reported as a pass. A check reports `warn` when the\nconfig lists it under `warn`: the finding is complete, but it does not fail\nthe run, the top-level `status` stays `pass`, and `warnings` counts them.\n\n`suggest` is the advice a person reads. `fix` is the corrected value itself,\npresent only when the correction is unambiguous — `Fix: add x` comes back with\n`\"fix\": \"fix: add x\"` — and an empty string otherwise, so an agent can apply\na non-empty `fix` as it stands and fall back to `suggest` when it is empty.\n\nA call that cannot run at all — an empty `message`, a `repo_path` that does not\nexist, a `repo_path` that is not a git repository when the tool has to read git\nstate (see the `repo_path` note under [Tool Usage](#tool-usage)), a malformed or rejected\ncommit-check config, a `push_refs` SHA that is not a commit in `repo_path` even\nafter the force-push check tried to fetch it — is returned as an MCP tool error\n(`is_error`) whose text names the problem, for example\n`repo_path is not a git repository: /path/to/dir`,\n`invalid commit-check config: ...` or\n`push_refs: <sha> is not a commit in the repository; fetch it first, the force-push check cannot be judged`,\nrather than as a `pass`/`fail` result. In particular a push whose SHAs cannot\nbe judged is never reported as a pass.\n\n## Installation\n\n```bash\npip install commit-check-mcp\n```\n\nThis installs the `commit-check-mcp` CLI entrypoint.\n\nFor local development from this repository:\n\n```bash\npip install -e .\n```\n\n## Use With An MCP Client\n\nThis server runs over stdio, so it is meant to be launched by an MCP client rather than used as a long-running HTTP service.\n\nWith `uvx` (recommended — no install needed):\n\n```bash\n# Run once, no pip install required\nuvx commit-check-mcp\n```\n\n> **Tip**: If `uv` is not installed, get it via `curl -LsSf https://astral.sh/uv/install.sh | sh`.\n\n### Configure your client\n\nEvery client below launches the same command; only the config file and, for a\nfew clients, the wrapper key differ. This is the object to register:\n\n```json\n{\n  \"mcpServers\": {\n    \"commit-check\": {\n      \"command\": \"uvx\",\n      \"args\": [\"commit-check-mcp\"]\n    }\n  }\n}\n```\n\n| Client | Where it goes | Notes |\n|---|---|---|\n| 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`. |\n| 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. |\n| 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`). |\n| VS Code (Copilot agent mode) | `.vscode/mcp.json` | **Different key**: `{\"servers\": {\"commit-check\": {\"type\": \"stdio\", \"command\": \"uvx\", \"args\": [\"commit-check-mcp\"]}}}` |\n| Cline | MCP Servers panel → Configure → `cline_mcp_settings.json` (check your client's docs) | Block above as-is. |\n| Roo Code | project `.roo/mcp.json` or global `mcp_settings.json` (**Edit Global MCP**) | Block above as-is; optional `\"alwaysAllow\": [...]`. |\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` (check your client's docs) | Block above as-is. |\n| 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/`. |\n| Zed | `~/.config/zed/settings.json` | **Different key**: `{\"context_servers\": {\"commit-check\": {\"command\": \"uvx\", \"args\": [\"commit-check-mcp\"]}}}` |\n| 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). |\n\nContinue'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/`):\n\n```yaml\nname: commit-check\nversion: 0.0.1\nschema: v1\nmcpServers:\n  - name: commit-check\n    command: uvx\n    args: [\"commit-check-mcp\"]\n```\n\n## Run Manually\n\n```bash\n# If installed via pip\ncommit-check-mcp\n\n# Or via uvx (no install needed)\nuvx commit-check-mcp\n```\n\nThe server uses stdio transport, which is the recommended MCP default for local tool integrations.\n\n## Tool Usage\n\nAfter the client starts the server, it will expose these tools:\n\n- `server_health`: returns server, SDK, and dependency versions\n- `validate_commit_message(message, config?, repo_path?, config_path?)`\n- `validate_branch_name(branch?, config?, repo_path?, config_path?)`\n- `validate_push_safety(push_refs?, config?, repo_path?, config_path?)`\n- `validate_author_info(author_name?, author_email?, config?, repo_path?, config_path?)`\n- `validate_commit_context(message?, branch?, author_name?, author_email?, config?, repo_path?, config_path?)`\n- `validate_repository_state(repo_path?, config?, config_path?, include_message?, include_branch?, include_author?, include_push?)`\n- `describe_validation_rules(config?, repo_path?, config_path?)`\n\nEvery parameter carries a description in the tool's JSON input schema, so an\nMCP client (and the model behind it) can see what each one expects without\nreading this file: for example `push_refs` documents the git pre-push line\nformat `<local_ref> <local_sha> <remote_ref> <remote_sha>`. Each tool also has\na display `title` and MCP tool annotations: `destructiveHint: false` and\n`idempotentHint: true` everywhere, `readOnlyHint: true` on the six tools that\nonly read, and `readOnlyHint: false` with `openWorldHint: true` on\n`validate_push_safety` and `validate_repository_state`, because the force-push\ncheck may run `git fetch` to resolve a SHA, which updates `FETCH_HEAD` and\nremote-tracking refs (the working tree and commits are never touched). Clients\nthat gate tool calls on those hints can auto-approve the read-only six. The\nserver's `instructions` describe the intended\nloop: validate first, read `status` (only `fail` rejects, `skip` is not\napproval), apply a non-empty `fix` verbatim or follow `suggest`, then validate\nagain.\n\nThe common optional arguments are:\n\n- `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\n- `config_path`: explicit TOML config file, used instead of the repository's own `cchk.toml`/`commit-check.toml`; relative paths resolve from `repo_path`\n- `config`: ad-hoc config overrides merged on top of defaults and repo config\n\n## Common Examples\n\nValidate a commit message using repo-local rules:\n\n```json\n{\n  \"message\": \"feat(api): add MCP validation tool\",\n  \"repo_path\": \"/path/to/repo\"\n}\n```\n\nValidate the current repository branch using an explicit config file:\n\n```json\n{\n  \"repo_path\": \"/path/to/repo\",\n  \"config_path\": \".github/commit-check.toml\"\n}\n```\n\nValidate the full repository state:\n\n```json\n{\n  \"repo_path\": \"/path/to/repo\",\n  \"include_message\": true,\n  \"include_branch\": true,\n  \"include_author\": true\n}\n```\n\nValidate 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):\n\n```json\n{\n  \"repo_path\": \"/path/to/repo\",\n  \"push_refs\": \"refs/heads/main abc123 refs/heads/main def456\"\n}\n```\n\nInspect the final merged rules that will be applied:\n\n```json\n{\n  \"repo_path\": \"/path/to/repo\",\n  \"config\": {\n    \"commit\": {\n      \"require_body\": true\n    }\n  }\n}\n```\n\n## Repository-Aware Validation\n\n`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:\n\n- `repo_path` — run git-based validations against a specific repository\n- `config_path` — point to an explicit TOML config file; relative paths are resolved from `repo_path`\n- `config` — apply ad-hoc overrides on top of defaults and repo config\n\nTypical patterns:\n\n- Validate an explicit message with a repository's rules\n- Validate the current repository state — the latest commit's message and author, and the current branch — without passing message/branch/author values manually\n- Validate push safety using pre-push ref metadata, or check the current branch against its upstream\n- Inspect which rules are actually enabled after config merging\n\nExample payload for a repository-wide validation:\n\n```json\n{\n  \"repo_path\": \"/path/to/repo\",\n  \"include_message\": true,\n  \"include_branch\": true,\n  \"include_author\": true,\n  \"include_push\": true\n}\n```\n\nConfig precedence is:\n\n1. `commit-check` built-in defaults\n2. 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)\n3. inline `config` overrides passed to the tool\n\n## Published On\n\n| Directory | Link |\n|---|---|\n| **Official MCP Registry** | [`io.github.commit-check/commit-check-mcp`](https://registry.modelcontextprotocol.io/?q=commit-check-mcp) |\n| **Glama.ai** | [`github/commit-check/commit-check-mcp`](https://glama.ai/mcp/servers/github/commit-check/commit-check-mcp) |\n| **PyPI** | [`commit-check-mcp`](https://pypi.org/project/commit-check-mcp/) |\n\n---\n\n<!-- Required by MCP Registry for PyPI package ownership validation -->\n<!-- https://registry.modelcontextprotocol.io -->\n<sub>mcp-name: io.github.commit-check/commit-check-mcp</sub>\n",
  "bytes": 12849,
  "sha": "7282062bee5ef721b63a91a2d79414a0b80b4f45fe2ccb46fd524ddf6b2f3a53",
  "repo_slug": "commit-check/commit-check-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_commit_check_commit_check_mcp_c9070516/readme"
}