mergecraft
Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 12
- Forks
- 5
01 前言 Front Matter
- name
- mergecraft
- description
- Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.
- compatibility
- Requires uv; gh CLI optional
03 SKILL.md 正文
mergeCraft
mergeCraft is an AI-powered PR reviewer: a GitHub Action plus a Python CLI
(mergecraft). BYOK — the user's Claude/ChatGPT subscription or API key; no
SaaS backend. Deterministic analyzers run first, then an LLM review agent, then
a read-only verifier; typed findings drive inline comments and the
mergecraft-approval commit status.
Setup checklist (new consumer repo)
-
Prereqs: <!-- BEGIN:requirements --> Requirements: uv is the only prerequisite for the install; it downloads a compatible Python (3.11+) itself, so no system Python is needed. The GitHub CLI (
gh auth login) is needed only forprovider auth --scope github(the default) or--scope both, which stores the secret withgh secret set.mergecraft initneeds neitherghnor a network;--scope localneeds nogh, but provider-specific authentication may need a network. Two providers need one more CLI at the credential step: the Codex CLI foropenaiand Claude Code foranthropic(provider table). <!-- END:requirements --> If uv cannot be installed, use the Docker Action only (docs/install.md). -
Install:
uv tool install mergecraft-action==0.1.0a6 mergecraft initDocs on
mainmay describe unreleased behavior. Use the matching release docs for this install; do not assume newer CLI flags or fixes are included. -
Authentication — STOP and ask the user. Use
mergecraft provider listto find the configured provider label or id frominit. Authenticate that entry withmergecraft provider auth <label-or-id> --scope localfor local evaluation, or--scope githubto adopt GitHub Actions. Examples below assume these provider labels are configured:mergecraft provider auth opencode --scope github(OpenCode Zen, billing-backed key)mergecraft provider auth opencode-go --scope github(OpenCode Go subscription)mergecraft provider auth openai --scope github(ChatGPT Plus/Pro/Team/Enterprise)mergecraft provider auth anthropic --scope github(Claude Pro/Max)mergecraft provider auth google --scope github(Google AI Studio)- API-key providers:
mergecraft provider auth deepseek|minimax|tokenhub|openrouter|xai --scope github
Never handle raw credentials; never commit secrets. GitHub scope checks the exact target repository before collecting credentials, stores Actions secrets, and rewrites
.github/workflows/mergecraft.ymlso the workflow passes them. Local scope writes only the displayed.envfile and never calls GitHub. After auth, runmergecraft doctor: itsworkflow authrow must be ok (if not, runmergecraft workflow sync --apply). -
Commit
.mergecraft/config.yaml,.mergecraft/learnings.md,.github/workflows/mergecraft.yml, and any.gitignorelinesinitadded; push; open a PR or runworkflow_dispatch. The default workflow does not listen for@mergecraft reviewcomments.
Standalone installation links
Install the generated skills/<harness>/mergecraft/SKILL.md package. The raw
skills/mergecraft/SKILL.md is a generator template; replace a copied template
with the generated package to repair relative links. Documentation links use the
v0.1.0a6 release tag, the release this checklist installs. Release
maintainers can set MERGECRAFT_AGENT_PACKAGES_REF when generating packages for another verified ref.
Fetch that ref first: an unresolved explicit override fails instead of silently
substituting a branch.
CLI quick reference
| Command | Purpose |
|---|---|
mergecraft init |
Scaffold config + workflow |
mergecraft review |
Review local diff / branch changes (primary local review command) |
mergecraft review --dry-run |
Print prompt, no LLM call |
mergecraft review --json out.json |
Machine-readable findings |
mergecraft provider auth … --scope github |
Interactive provider login → gh secret set |
mergecraft models list|show|set |
Inspect/configure model chains |
mergecraft analyzers list|detect|run|explain |
Deterministic analyzers |
mergecraft learnings active|staging |
Inspect learnings memory |
mergecraft findings export |
Export unresolved findings |
mergecraft mcp serve |
Start MCP HTTP server (Bearer token required) |
mergecraft mcp list |
List MCP tool surface for a role |
diff-review is a deprecated alias for mergecraft review (one stderr
warning per invocation) — teach mergecraft review instead.
MCP
Two profiles — do not confuse them:
| Profile | Command | Transport | Auth |
|---|---|---|---|
| Public product | mergecraft mcp serve --role public --transport stdio |
stdio JSON-RPC | None (local OS user) |
| Runtime harness | mergecraft mcp serve (default --role reviewer) |
HTTP on ephemeral port | Per-serve Bearer required |
Public install (Cursor, Claude Desktop, Codex, Gemini CLI, OpenCode): see
docs/mcp.md for copy-paste mcpServers JSON. Six tools only
(review_change, get_review, inspect_finding, explain_finding,
get_capabilities, get_policy). Registry: mcp-name: io.github.alexhawat/mergecraft.
Runtime harness HTTP: default mergecraft mcp serve mints a Bearer token on an
ephemeral port; omitting Authorization: Bearer … returns HTTP 401 / JSON-RPC
-32600. Reviewer tools live at /mcp/reviewer. Startup prints
MERGECRAFT_MCP_BEARER=<token> to stderr — pass that token on every HTTP request.
Optional HTTP public (--role public without --transport stdio) also requires Bearer.
Configuration essentials (.mergecraft/config.yaml)
models:ordered fallback chain, e.g.["anthropic/claude-sonnet", "openai/gpt-5.3-codex"]. Uncredentialed providers are skipped; transient failures fall through.model_pin: enabledopts out.prApproveEnabled: truelets trusted-tier runs submit a real APPROVE.- Trust tiers are fail-closed: fork PRs and
pull_request_targetrun with no secrets/network — do not "fix" this. - Learnings in
.mergecraft/learnings.md: new entries land in## Staging; only maintainer-associated authors promote to## Active.
Troubleshooting
mergecraft-approvalfailing/neutral — pure function of typed findings; runmergecraft findings exportand read blocking items. Prose verdict cannot override a blocker.- Workflow did not trigger on comment — only OWNER/MEMBER/COLLABORATOR
commenters are authorized; authorization reads
author_associationfrom the event payload, never the comment body. - Model skipped — no credential for that provider; run
mergecraft models list. - Full docs:
README.md,AGENTS-mergecraft.md,docs/REVIEW-CHECKS.md,docs/.
04 同仓库更多 Skills
git-archaeology
Investigate how code reached its current state — when a line, function, import, or whole file was changed or deleted, who removed it, and what it looked like before. Use when `git blame` came up empty, when content has been refactored away, or when you need the full evolution of a function across commits.
mergecraft
Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.
mergecraft
Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.
mergecraft
Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.
mergecraft
Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.
mergecraft
Set up, run, and troubleshoot mergeCraft — the BYOK AI PR review GitHub Action and CLI. Use when the user asks to install or configure mergeCraft, add AI PR review to a repo, run a local review, interpret mergecraft-approval status or findings, configure models in .mergecraft/config.yaml, use mergecraft mcp serve, or debug a failing mergeCraft workflow.