You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit ed82c08
Browse filesBrowse the repository at this point in the historyBrowse files
docs: rebuild the README around setup, tools and results (#38)
The tools were listed twice (Features, Tool Usage), repo_path,
config_path and config were explained twice, and the Published On table
repeated what the badges already said.
- The header matches the core and Action READMEs: the v4 banner (light
and dark), the site's line, five badges in the brand colors and links
to the docs, the CLI, the Action and the App.
- Quick start leads with `claude mcp add`; the client table and the
Continue entry are unchanged.
- The tools are one table, with the shared arguments and the
read-only/fetch annotations stated once underneath; the example
payloads fold into <details>.
- Results keep the shape and cut the prose to three points.
- Installation, Run Manually and the dev install become Development.
- The Glama link was a 404; it now points at the listing's current
address.
The mcp-name line the MCP Registry reads for PyPI ownership is kept as
it was.
Model Context Protocol (MCP) server for [commit-check](https://github.com/commit-check/commit-check).
8
+
**Catch bad commits before they merge — inside your AI agent.**
12
9
13
-
`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.
`rule_id` is the stable id of the rule that produced the check and `docs_url`
50
-
links to its documentation.
51
-
52
-
Only `fail` is a rejection. A check reports `skip` when it did not run — the
53
-
author matched `ignore_authors`, or there was nothing to check — and the
54
-
top-level `status` is `skip` only when **every** check skipped, so a run that
55
-
validated nothing is never reported as a pass. A check reports `warn` when the
56
-
config lists it under `warn`: the finding is complete, but it does not fail
57
-
the run, the top-level `status` stays `pass`, and `warnings` counts them.
58
-
59
-
`suggest` is the advice a person reads. `fix` is the corrected value itself,
60
-
present only when the correction is unambiguous — `Fix: add x` comes back with
61
-
`"fix": "fix: add x"` — and an empty string otherwise, so an agent can apply
62
-
a non-empty `fix` as it stands and fall back to `suggest` when it is empty.
63
-
64
-
A call that cannot run at all — an empty `message`, a `repo_path` that does not
65
-
exist, a `repo_path` that is not a git repository when the tool has to read git
66
-
state (see the `repo_path` note under [Tool Usage](#tool-usage)), a malformed or rejected
67
-
commit-check config, a `push_refs` SHA that is not a commit in `repo_path` even
68
-
after the force-push check tried to fetch it — is returned as an MCP tool error
69
-
(`is_error`) whose text names the problem, for example
70
-
`repo_path is not a git repository: /path/to/dir`,
71
-
`invalid commit-check config: ...` or
72
-
`push_refs: <sha> is not a commit in the repository; fetch it first, the force-push check cannot be judged`,
73
-
rather than as a `pass`/`fail` result. In particular a push whose SHAs cannot
74
-
be judged is never reported as a pass.
75
-
76
-
## Installation
30
+
## Quick start
77
31
78
32
```bash
79
-
pip install commit-check-mcp
33
+
claude mcp add commit-check -- uvx commit-check-mcp
80
34
```
81
35
82
-
This installs the `commit-check-mcp` CLI entrypoint.
83
-
84
-
For local development from this repository:
85
-
86
-
```bash
87
-
pip install -e .
88
-
```
89
-
90
-
## Use With An MCP Client
91
-
92
-
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.
93
-
94
-
With `uvx` (recommended — no install needed):
95
-
96
-
```bash
97
-
# Run once, no pip install required
98
-
uvx commit-check-mcp
99
-
```
100
-
101
-
> **Tip**: If `uv` is not installed, get it via `curl -LsSf https://astral.sh/uv/install.sh | sh`.
102
-
103
-
### Configure your client
104
-
105
-
Every client below launches the same command; only the config file and, for a
106
-
few clients, the wrapper key differ. This is the object to register:
36
+
Every other client launches the same command. This is the object to register:
107
37
108
38
```json
109
39
{
@@ -116,6 +46,11 @@ few clients, the wrapper key differ. This is the object to register:
116
46
}
117
47
```
118
48
49
+
No `uv` yet? `curl -LsSf https://astral.sh/uv/install.sh | sh` — or use
50
+
`pip install commit-check-mcp`, as in the last row below.
51
+
52
+
### Where each client keeps it
53
+
119
54
| Client | Where it goes | Notes |
120
55
|---|---|---|
121
56
| 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`. |
@@ -141,56 +76,37 @@ mcpServers:
141
76
args: ["commit-check-mcp"]
142
77
```
143
78
144
-
## Run Manually
145
-
146
-
```bash
147
-
# If installed via pip
148
-
commit-check-mcp
149
-
150
-
# Or via uvx (no install needed)
151
-
uvx commit-check-mcp
152
-
```
79
+
## Tools
153
80
154
-
The server uses stdio transport, which is the recommended MCP default for local tool integrations.
155
-
156
-
## Tool Usage
157
-
158
-
After the client starts the server, it will expose these tools:
159
-
160
-
-`server_health`: returns server, SDK, and dependency versions
Every parameter carries a description in the tool's JSON input schema, so an
170
-
MCP client (and the model behind it) can see what each one expects without
171
-
reading this file: for example `push_refs` documents the git pre-push line
172
-
format `<local_ref> <local_sha> <remote_ref> <remote_sha>`. Each tool also has
173
-
a display `title` and MCP tool annotations: `destructiveHint: false` and
174
-
`idempotentHint: true` everywhere, `readOnlyHint: true` on the six tools that
175
-
only read, and `readOnlyHint: false` with `openWorldHint: true` on
176
-
`validate_push_safety` and `validate_repository_state`, because the force-push
177
-
check may run `git fetch` to resolve a SHA, which updates `FETCH_HEAD` and
178
-
remote-tracking refs (the working tree and commits are never touched). Clients
179
-
that gate tool calls on those hints can auto-approve the read-only six. The
180
-
server's `instructions` describe the intended
181
-
loop: validate first, read `status` (only `fail` rejects, `skip` is not
182
-
approval), apply a non-empty `fix` verbatim or follow `suggest`, then validate
183
-
again.
184
-
185
-
The common optional arguments are:
186
-
187
-
-`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
188
-
-`config_path`: explicit TOML config file, used instead of the repository's own `cchk.toml`/`commit-check.toml`; relative paths resolve from `repo_path`
189
-
-`config`: ad-hoc config overrides merged on top of defaults and repo config
190
-
191
-
## Common Examples
192
-
193
-
Validate a commit message using repo-local rules:
81
+
| Tool | What it checks | Arguments |
82
+
|---|---|---|
83
+
| `validate_commit_message` | A commit message: Conventional Commits, subject length and case, body, sign-off, WIP and fixup markers, AI attribution | `message` |
84
+
| `validate_branch_name` | A branch name, or the checked-out one, and its rebase target when configured | `branch?` |
85
+
| `validate_author_info` | Author name and email; read from the repository's git config when omitted | `author_name?` `author_email?` |
86
+
| `validate_commit_context` | Message, branch and author in one call, for whichever you pass | `message?` `branch?` `author_name?` `author_email?` |
87
+
| `validate_push_safety` | That a push is not a force push (CC301) | `push_refs?` — pre-push lines; omit to compare the branch with its upstream |
88
+
| `validate_repository_state` | The latest commit's message and author, the checked-out branch and, optionally, the push | `include_message` `include_branch` `include_author` (default `true`), `include_push` (default `false`) |
89
+
| `describe_validation_rules` | Nothing: returns the merged config and the rules it enables | — |
90
+
| `server_health` | Nothing: returns the server, commit-check and MCP SDK versions | — |
91
+
92
+
Every tool but `server_health` also takes:
93
+
94
+
- `repo_path`— the repository whose `cchk.toml` / `commit-check.toml` applies.
95
+
It must be a git repository when the tool reads git state; a plain directory
96
+
holding a config file is enough when you pass every value yourself.
97
+
- `config_path`— a config file to use instead of the repository's own;
98
+
relative paths resolve from `repo_path`.
99
+
- `config` — inline overrides merged on top, e.g. `{"commit": {"require_body": true}}`.
100
+
101
+
No tool changes the working tree or the commits. `validate_push_safety` and
102
+
`validate_repository_state`may run `git fetch` to resolve a SHA, so only they
103
+
are annotated as not read-only; a client that gates on MCP tool hints can
104
+
auto-approve the other six.
105
+
106
+
<details>
107
+
<summary><b>Example arguments</b></summary>
108
+
109
+
Validate a message with the repository's rules:
194
110
195
111
```json
196
112
{
@@ -199,27 +115,16 @@ Validate a commit message using repo-local rules:
199
115
}
200
116
```
201
117
202
-
Validate the current repository branch using an explicit config file:
118
+
Check the repository as it stands, including the push:
203
119
204
120
```json
205
121
{
206
122
"repo_path": "/path/to/repo",
207
-
"config_path": ".github/commit-check.toml"
208
-
}
209
-
```
210
-
211
-
Validate the full repository state:
212
-
213
-
```json
214
-
{
215
-
"repo_path": "/path/to/repo",
216
-
"include_message": true,
217
-
"include_branch": true,
218
-
"include_author": true
123
+
"include_push": true
219
124
}
220
125
```
221
126
222
-
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):
@@ -228,7 +133,7 @@ Validate push safety from git pre-push hook ref metadata (`push_refs` must be no
228
133
}
229
134
```
230
135
231
-
Inspect the final merged rules that will be applied:
136
+
See which rules apply once an override is merged in:
232
137
233
138
```json
234
139
{
@@ -241,46 +146,49 @@ Inspect the final merged rules that will be applied:
241
146
}
242
147
```
243
148
244
-
## Repository-Aware Validation
245
-
246
-
`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:
247
-
248
-
-`repo_path` — run git-based validations against a specific repository
249
-
-`config_path` — point to an explicit TOML config file; relative paths are resolved from `repo_path`
250
-
-`config` — apply ad-hoc overrides on top of defaults and repo config
149
+
</details>
251
150
252
-
Typical patterns:
151
+
## Results
253
152
254
-
- Validate an explicit message with a repository's rules
255
-
- Validate the current repository state — the latest commit's message and author, and the current branch — without passing message/branch/author values manually
256
-
- Validate push safety using pre-push ref metadata, or check the current branch against its upstream
257
-
- Inspect which rules are actually enabled after config merging
258
-
259
-
Example payload for a repository-wide validation:
153
+
Every `validate_*` tool returns the shape `commit-check --format json` prints:
0 commit comments