docs: an MCP server guide, and a page comparing the other tools (#29)

Author: shenxianpeng

docs/compare/tools.md

@@ -0,0 +1,63 @@
+# Compared with other tools
+
+What else checks commit messages, branch names and pull request titles on
+GitHub, what each one does, and when it is the better choice. Prices and
+features are as the projects list them in September 2026; follow the links
+for the current state. GitHub's own rulesets are on
+[their own page](github-rules.md).
+
+## The field
+
+| Tool | What it is | What it checks | Where it runs | Price |
+|---|---|---|---|---|
+| [commitlint](https://commitlint.js.org/) with [commitlint-github-action](https://github.com/wagoid/commitlint-github-action) | The reference Conventional Commits linter in the JavaScript world: shared configs, plugins, a [commitizen](https://commitizen.github.io/cz-cli/) prompt | Commit messages | Node hook (husky), CI Action | Free, open source |
+| [action-semantic-pull-request](https://github.com/amannn/action-semantic-pull-request) | The most-used pull request title check; Electron, Vite and Vercel run it | The pull request title (optionally the single commit, for squash merges) | GitHub Action | Free, open source |
+| [Semantic PRs](https://github.com/Ezard/semantic-prs) | A GitHub App with the same idea: type and scope on the title or the commits | Pull request title or commits | GitHub App | Free, open source |
+| [commitcheck](https://github.com/marketplace/commitcheck) | A hosted App that applies one regular expression, set in its web admin | Commit message, pull request title or description, by regex | GitHub App | Free for public repositories; $25 a month for private ones |
+| [DCO app](https://github.com/apps/dco) and [DCO-2](https://github.com/cncf/dco2) | The sign-off check the Linux kernel and the CNCF use, with a remediation flow for missing sign-offs | `Signed-off-by` trailers | GitHub App | Free, open source |
+| [PRLint](https://github.com/ewolfe/prlint), [PR Title Checker](https://github.com/marketplace/actions/pr-title-checker) | Regular expressions over pull request fields | Title, body, labels, branch | App / Action | Free, open source |
+| **Commit Check** | One rule engine with [24 documented rules](../rules.md), run as a hook, a CLI, an Action, a hosted App or an MCP tool | Commit message, branch name, author name and email, sign-off, AI attribution, force pushes, file size and paths, tag names; the squash message of a pull request | All of the above | Free, open source; the App's private organization repositories move to a paid plan later |
+
+## What is different about Commit Check
+
+- **One config, every place it runs.** The same `cchk.toml` drives the
+  [pre-commit hook](../guides/pre-commit.md), the [Action](../guides/github-actions.md),
+  the [App](../guides/github-app.md) and the [MCP server](../guides/mcp.md).
+  The others cover one place each: commitlint is a Node hook and an Action;
+  the title checkers are Actions or Apps; commitcheck is an App.
+- **More than the message.** Branch names, author identity, sign-off, AI
+  attribution trailers, force pushes and file rules are rules, not separate
+  tools to find and wire up.
+- **A failure explains itself.** Every rule has a stable ID, a one-line error,
+  a suggestion and a documentation page, and the Action and App show all of
+  it where the failure is. A regex tool reports a mismatch.
+- **Squash-aware.** The App can check the message a squash merge would land,
+  built from the repository's merge settings, rather than every commit on the
+  branch or only the title.
+- **No JavaScript toolchain.** It is a Python package with no runtime
+  dependencies; a Go, Rust or Java repository does not need Node to lint its
+  commits.
+
+## Where the others are stronger
+
+- **commitlint's ecosystem.** Years of shared configs (`@commitlint/config-*`),
+  plugins and editor integrations, plus an interactive prompt for writing the
+  message. Commit Check has no prompt, and its rules are the ones it ships.
+- **A Node monorepo already on husky.** If commitlint is installed and the
+  policy is "message only", there is little to gain from switching.
+- **Sign-off remediation.** The DCO app can accept a later commit that
+  certifies earlier ones, and lets a maintainer override. Commit Check checks
+  the trailer and stops there.
+- **Rejecting the push itself.** Only GitHub's rulesets (and a server-side
+  hook on GitHub Enterprise Server) refuse a ref update; see the
+  [rulesets page](github-rules.md). Every tool above, Commit Check included,
+  marks the commit or blocks the merge.
+
+## Which to choose
+
+- You want the pull request title checked and nothing else: `action-semantic-pull-request`.
+- You are in a JavaScript repository with husky and want plugins: commitlint.
+- You need sign-off with a remediation flow: the DCO app, or DCO-2.
+- You want one policy for messages, branches and authors, the same everywhere
+  a commit is made and checked, with a hosted option that needs no workflow
+  file: Commit Check.

docs/guides/integrations.md

@@ -10,7 +10,7 @@ between what a developer sees locally and what is enforced on the pull request.
 | [GitHub Action](github-actions.md) | On every push and pull request, in CI | No | A workflow file in each repository |
 | [GitHub App](github-app.md) | On every push and pull request, hosted | No | Install once for the organization |
 | [Command line](../example.md) | Wherever you call it: a range of commits, a CI you write yourself | — | `pip install commit-check` |
-| [MCP server](https://github.com/commit-check/commit-check-mcp) | Before the commit exists, inside an AI coding agent | — | One entry in the agent's MCP config |
+| [MCP server](mcp.md) | Before the commit exists, inside an AI coding agent | — | One entry in the agent's MCP config |
 | [Organization config](organization.md) | Everywhere at once | — | One shared `cchk.toml`, whichever of the above runs it |
 
 ## Which one
@@ -63,6 +63,11 @@ ones created later, gets a **Commit Check** result on each commit of every
 push and pull request, with no workflow file and no CI minutes.
 [Set it up →](github-app.md)
 
+## MCP server
+
+The same rules as tools for an AI coding agent, so the message is right before
+the commit exists. One entry in the agent's MCP settings. [Set it up →](mcp.md)
+
 ## Across an organization { #across-an-organization }
 
 One `cchk.toml` in the organization's `.github` repository; each repository

docs/guides/mcp.md

@@ -0,0 +1,117 @@
+# MCP server
+
+[commit-check-mcp](https://github.com/commit-check/commit-check-mcp) exposes
+the same rules to an AI coding agent as
+[Model Context Protocol](https://modelcontextprotocol.io/) tools. An agent that
+writes commits can check the message, the branch name and the author before
+the commit exists, against the repository's own `cchk.toml`, and fix what
+fails instead of finding out from the hook or the pull request.
+
+## Add it to the agent
+
+The server runs over stdio and is started by the client. With
+[uv](https://docs.astral.sh/uv/) installed nothing else needs installing:
+
+=== "Claude Code"
+
+    ```json title=".claude/settings.local.json or ~/.claude/settings.json"
+    {
+      "mcpServers": {
+        "commit-check": {
+          "command": "uvx",
+          "args": ["commit-check-mcp"]
+        }
+      }
+    }
+    ```
+
+=== "Cursor"
+
+    ```json title=".cursor/mcp.json"
+    {
+      "mcpServers": {
+        "commit-check": {
+          "command": "uvx",
+          "args": ["commit-check-mcp"]
+        }
+      }
+    }
+    ```
+
+=== "Claude Desktop, Windsurf, Cline, Roo Code"
+
+    The same block, in each client's MCP settings file. The
+    [README](https://github.com/commit-check/commit-check-mcp#use-with-an-mcp-client)
+    lists the file for each.
+
+=== "Zed"
+
+    ```json title="~/.config/zed/settings.json"
+    {
+      "mcp_servers": {
+        "commit-check": {
+          "command": "uvx",
+          "args": ["commit-check-mcp"]
+        }
+      }
+    }
+    ```
+
+=== "Without uv"
+
+    ```console
+    $ pip install commit-check-mcp
+    $ which commit-check-mcp
+    ```
+
+    Then use that absolute path as the `command`, with no `args`.
+
+## Make the agent use it
+
+Tools an agent *can* call are not tools it *will* call. One line in the
+project's agent instructions — `CLAUDE.md`, `AGENTS.md`, a Cursor rule — makes
+the check part of every commit:
+
+```markdown title="CLAUDE.md"
+Before every commit, validate the message with the commit-check MCP tool
+(`validate_commit_message`) and rewrite it until it passes.
+```
+
+The result the agent gets back is the same structured verdict the CLI prints
+with `--format json`: a status, and for each check its value, the error and a
+suggestion. That is enough for the agent to correct the message on its own.
+
+## The tools
+
+| Tool | Checks |
+|---|---|
+| `validate_commit_message(message, …)` | A message against the [commit message rules](../rules.md#commit-message-rules) |
+| `validate_branch_name(branch?, …)` | A branch name, or the repository's current branch, against the [branch rules](../rules.md#branch-rules) |
+| `validate_author_info(author_name?, author_email?, …)` | A name and email, or the repository's git author config, against the [author rules](../rules.md#author-rules) |
+| `validate_push_safety(push_refs?, …)` | That a push is not a force push ([CC301](../rules.md#cc301)) |
+| `validate_commit_context(message?, branch?, author_name?, author_email?, …)` | Any combination of the above in one call |
+| `validate_repository_state(repo_path?, …)` | The latest commit, current branch and author config of a repository, with push safety on request |
+| `describe_validation_rules(…)` | The effective configuration after defaults, the repository's file and any overrides |
+| `server_health()` | Server, rule engine and SDK versions |
+
+Every validation tool takes the same optional arguments:
+
+- `repo_path` — the repository to validate against; the config file is looked
+  up there, in the [usual places](../configuration.md#where-the-config-file-lives).
+- `config_path` — a specific TOML file instead; a relative path resolves from
+  `repo_path`.
+- `config` — inline overrides, merged on top of the defaults and the file, for
+  a one-off stricter or looser check.
+
+All tools are read-only. Nothing is committed, pushed or written.
+
+## The same rules, one step earlier
+
+The MCP server reads the same `cchk.toml` as the [pre-commit hook](pre-commit.md),
+the [Action](github-actions.md) and the [App](github-app.md), through the same
+rule engine, so an agent that passes here passes there. It changes *when* the
+verdict arrives: before the commit exists, inside the tool that is writing it,
+instead of after, from a hook the agent may not be running or from a check on
+the pull request. For a repository that forbids AI attribution trailers
+([CC013](../rules.md#cc013)) or requires a sign-off ([CC012](../rules.md#cc012)),
+this is where the agent learns it.

docs/index.md

@@ -255,6 +255,7 @@ graph LR
     **MCP server** — exposes the validations as structured tools for AI coding
     agents such as Claude Code, Cursor and Copilot.
 
+    [:octicons-arrow-right-24: Guide](guides/mcp.md)
     [:octicons-arrow-right-24: Repo](https://github.com/commit-check/commit-check-mcp)
 
 </div>

mkdocs.yml

@@ -165,6 +165,7 @@ nav:
       - GitHub Action: guides/github-actions.md
       - GitHub App: guides/github-app.md
       - Across an organization: guides/organization.md
+      - MCP server: guides/mcp.md
       - Policy guides: guides/policies.md
       - Command-line recipes: example.md
       - Troubleshooting: troubleshoot.md
@@ -176,5 +177,6 @@ nav:
       - Privacy: privacy.md
   - Compare:
       - GitHub's built-in rules: compare/github-rules.md
+      - Other tools: compare/tools.md
   - Blog:
       - blog/index.md