feat: add AGENTS.md, demo GIF, Smithery config, and README refresh

AGENTS.md

@@ -0,0 +1,136 @@
+# AGENTS.md — AI Coding Agent Instructions
+
+> This file tells AI coding agents (Claude Code, Cursor, Copilot, etc.) how to use
+> `commit-check-mcp` effectively when validating commits in this repository.
+
+## What commit-check-mcp does for you
+
+`commit-check-mcp` is an MCP server that exposes structured commit validation tools. As
+an AI agent, you can call these tools to validate:
+
+- **Commit messages** — Conventional Commits format, subject length, imperative mood, etc.
+- **Branch names** — Naming conventions (feature/, bugfix/, hotfix/, etc.)
+- **Author info** — Name and email format validation
+- **Push safety** — Force-push detection for pre-push hooks
+- **Repository state** — Combined validation of all the above in one call
+- **Validation rules** — Inspect the effective config (defaults + repo config + overrides)
+
+## Installing in your MCP client
+
+```json
+{
+  "mcpServers": {
+    "commit-check": {
+      "command": "commit-check-mcp"
+    }
+  }
+}
+```
+
+Or with `uvx` (no install needed):
+
+```json
+{
+  "mcpServers": {
+    "commit-check": {
+      "command": "uvx",
+      "args": ["commit-check-mcp"]
+    }
+  }
+}
+```
+
+## When to call each tool
+
+### Before creating a commit → `validate_commit_message`
+
+Always call this **before** writing a commit message. Pass the message you intend to use:
+
+```
+Tool: validate_commit_message
+Args: { "message": "feat(api): add user authentication endpoint" }
+```
+
+If it returns `"status": "fail"`, read the `checks[].suggest` field and fix the message
+before committing. Never commit a message that fails validation.
+
+### Before creating a branch → `validate_branch_name`
+
+When you need to create a new branch, validate the name first:
+
+```
+Tool: validate_branch_name
+Args: { "branch": "feature/user-auth" }
+```
+
+### After switching to a repo → `describe_validation_rules`
+
+On first entering a repository, inspect what rules are enforced:
+
+```
+Tool: describe_validation_rules
+Args: { "repo_path": "/path/to/repo" }
+```
+
+This tells you which checks are active so you can comply from the start.
+
+### Before pushing → `validate_push_safety`
+
+If the repo has pre-push hooks configured, validate push safety:
+
+```
+Tool: validate_push_safety
+Args: { "repo_path": "/path/to/repo" }
+```
+
+### Full state check → `validate_repository_state`
+
+For a comprehensive check of the current repo state:
+
+```
+Tool: validate_repository_state
+Args: { "repo_path": "/path/to/repo" }
+```
+
+## Understanding responses
+
+All validation tools return this shape:
+
+```json
+{
+  "status": "pass|fail",
+  "checks": [
+    {
+      "check": "message",
+      "status": "pass|fail",
+      "value": "the input that was checked",
+      "error": "reason for failure (only on fail)",
+      "suggest": "how to fix it (only on fail)"
+    }
+  ]
+}
+```
+
+### When a check fails
+
+1. Read `error` to understand what went wrong
+2. Read `suggest` for the recommended fix
+3. Apply the fix and re-validate
+4. Only proceed when `status` is `"pass"`
+
+### Config precedence
+
+When both `repo_path` and `config` are provided:
+
+1. commit-check built-in defaults
+2. `cchk.toml` / `commit-check.toml` from the repo
+3. Explicit `config_path` if given
+4. Inline `config` overrides (highest priority)
+
+## Best practices for AI agents
+
+1. **Validate early, validate often** — check commit messages before writing them, not after
+2. **Don't bypass failures** — if a check fails, fix it; never force-push or skip hooks
+3. **Use the suggest field** — it contains the exact fix needed
+4. **Check rules first** — call `describe_validation_rules` when entering a new repo
+5. **Prefer `validate_repository_state`** for a comprehensive check in one call

README.md

@@ -5,10 +5,34 @@
 [![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/)
+[![Smithery](https://img.shields.io/badge/Smithery-MCP%20Server-8B5CF6)](https://smithery.ai)
 
-Model Context Protocol (MCP) server for [commit-check](https://github.com/commit-check/commit-check).
+> **AI agent-friendly commit validation via MCP.** Built for AI coding agents (Claude Code, Cursor, Copilot, etc.) — not just human CI pipelines.
 
-`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.
+![Demo](demo/demo.gif)
+
+**commit-check-mcp** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes [commit-check](https://github.com/commit-check/commit-check) validations as structured tools. AI agents call these tools to validate commit messages, branch names, author info, push safety, and repository state — every tool returns pass/fail results with actionable suggestions.
+
+### Why this vs commitlint?
+
+| | commitlint | commit-check-mcp |
+|---|---|---|
+| **Target user** | Humans in CI pipelines | AI coding agents via MCP |
+| **Interface** | CLI + git hooks + config files | MCP tools (JSON in/out) |
+| **Output** | Terminal text, exit codes | Structured JSON with `.error` + `.suggest` fields |
+| **Agent awareness** | None | AGENTS.md instructions, tool descriptions optimized for LLM function calling |
+| **Integration** | husky + CI config | Drop-in MCP server config for any MCP client |
+| **Repository context** | Reads config from cwd | Explicit `repo_path` + `config_path` params — works across repos |
+
+## For AI Agents
+
+If you're an AI coding agent working in this repository, read **[AGENTS.md](AGENTS.md)** for instructions on how to use commit-check-mcp tools effectively.
+
+Key conventions for agents:
+- Always validate commit messages **before** writing them
+- Read `.suggest` on failures — it contains the exact fix
+- Call `describe_validation_rules` when entering a new repo
+- Use `validate_repository_state` for comprehensive checks in one call
 
 ## Features
 
@@ -92,6 +116,16 @@ Example using an absolute path:
 
 For local development from this repository, that absolute path may point to something like `.venv/bin/commit-check-mcp`.
 
+## Smithery / mcp.so
+
+commit-check-mcp is available on [Smithery](https://smithery.ai), the MCP server registry:
+
+```bash
+npx @smithery-ai/cli install commit-check-mcp
+```
+
+Or add it to your MCP client directly using the [Smithery config](smithery.yaml).
+
 ## Run Manually
 
 ```bash
@@ -205,3 +239,27 @@ Config precedence is:
 2. repository config loaded from `repo_path`
 3. `config_path` when explicitly provided
 4. inline `config` overrides passed to the tool
+
+## Development
+
+### Running tests
+
+```bash
+pip install -e .[dev]
+pytest -q --cov=src/commit_check_mcp
+```
+
+### Regenerating the demo GIF
+
+Requires [vhs](https://github.com/charmbracelet/vhs):
+
+```bash
+brew install vhs
+vhs demo/demo.tape --output demo/demo.gif
+```
+
+Edit `demo/demo-compact.py` to change the demo content.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

demo/demo-compact.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Compact terminal demo optimized for GIF recording."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from commit_check_mcp.server import (
+    _validate_message,
+    _validate_branch,
+    _validate_author,
+    _validate_push,
+    _validate_all,
+    server_health,
+)
+
+GREEN = "\033[32m"
+RED = "\033[31m"
+YELLOW = "\033[33m"
+CYAN = "\033[36m"
+BOLD = "\033[1m"
+RESET = "\033[0m"
+DIM = "\033[2m"
+
+
+def heading(text: str) -> None:
+    print(f"\n{BOLD}{CYAN}{text}{RESET}")
+
+
+def show(result: dict) -> None:
+    s = f"{GREEN}PASS{RESET}" if result["status"] == "pass" else f"{RED}FAIL{RESET}"
+    print(f"  [{s}]", end="")
+    for c in result["checks"]:
+        mark = f"{GREEN}✓{RESET}" if c["status"] == "pass" else f"{RED}✗{RESET}"
+        print(f" {mark}{c['check']}", end="")
+        if c["status"] == "fail" and c.get("suggest"):
+            print(f"\n    {YELLOW}→ {c['suggest'][:80]}{RESET}", end="")
+    print()
+
+
+# Header
+print(f"{BOLD}commit-check-mcp  —  AI Agent-Friendly Commit Validation{RESET}")
+print(f"{DIM}https://github.com/commit-check/commit-check-mcp{RESET}")
+
+heading("Server Health")
+health = server_health()
+print(f"  {health['server']} v{health['server_version']} | commit-check v{health['commit_check_version']}")
+
+heading("1. Commit Message")
+show(_validate_message("feat(api): add user auth endpoint"))
+show(_validate_message("add user auth"))
+
+heading("2. Branch Name")
+show(_validate_branch("feature/user-auth"))
+show(_validate_branch("my_branch"))
+
+heading("3. Author Info")
+show(_validate_author("Xianpeng Shen", "xianpeng.shen@gmail.com"))
+show(_validate_author("", "bad-email"))
+
+heading("4. Push Safety")
+show(_validate_push("refs/heads/main abc123 refs/heads/main def456"))
+
+heading("5. Combined Context")
+show(_validate_all(
+    message="chore(deps): bump requests",
+    branch="chore/update-deps",
+    author_name="Xianpeng Shen",
+    author_email="xianpeng.shen@gmail.com",
+))
+
+print(f"\n{BOLD}{GREEN}8 MCP tools for AI agents — install: pip install commit-check-mcp{RESET}")