开源MCP工具

Quick Start

Requires Node.js 22+.

npx hatch3r init --default  # recommended: zero-prompt setup with the standard profile
npx hatch3r init            # interactive: customize profile, tools, and CLI tools (6 prompts for GitHub greenfield; +1 for Azure DevOps, +1 for `custom` preset, +1 for workspace mode)

--default generates a working standard-profile setup with no questions — the fastest path to a configured repo. The interactive init detects your repo, infers your project context (greenfield/brownfield, solo/team), then walks platform → repo identity → content profile (minimal/standard/full/custom) → tools → CLI-tools picker, and generates everything. MCP is not prompted — opt in with --mcp or npx hatch3r mcp setup later. The platform (GitHub, Azure DevOps, or GitLab) is auto-detected from your git remote either way. Run into issues? See Troubleshooting.

Already using Cursor? Carry your existing rules across with npx hatch3r init --import cursor — they land under .hatch3r/overrides/rules/ (.md + .mdc) with per-file conflict reporting. See Migrating from another tool.

MCP Configuration

Since 1.7.5, MCP is opt-in; since 2.0.0 interactive npx hatch3r init no longer offers an MCP prompt. Without an opt-in, init skips MCP entirely -- no .env.mcp, no mcp.json, no servers in the manifest, and features.mcp stays false. When you opt in (init --mcp on any init path, or npx hatch3r mcp setup afterwards), hatch3r writes a gitignored .env.mcp with the required environment variables and MCP config to the tool-appropriate location (.cursor/mcp.json, .mcp.json, .vscode/mcp.json).

• VS Code / Copilot: secrets pass via the env object in .vscode/mcp.json.
• Cursor / Claude Code / others: source the file first: set -a && source .env.mcp && set +a && cursor .

Manage MCP at any time via npx hatch3r mcp setup | list | remove <id> | env-check. CI note: interactive init no longer offers MCP, and npx hatch3r init --yes does not configure it by default -- opt in via npx hatch3r mcp setup or init --mcp. See MCP Setup for per-server details and PAT scope guidance.

CLI Commands

npx hatch3r init          # Interactive setup (or --default for zero prompts)
npx hatch3r setup [dir]   # Scaffold a new project (mkdir + git init) then run init
npx hatch3r config        # Reconfigure tools, MCP servers, features, and platform
npx hatch3r sync          # Re-generate from canonical state
npx hatch3r update        # Pull latest templates (safe merge)
npx hatch3r status        # Check sync status between canonical and generated files
npx hatch3r validate      # Validate bundled canonical content + on-disk adapter outputs
npx hatch3r verify        # Drift check on adapter outputs (non-zero exit on drift)
npx hatch3r clean         # Remove generated files (optional --reinit)
npx hatch3r worktree-setup <path>   # Set up gitignored files in a worktree
npx hatch3r worktree-cleanup <path> # Clean up worktree-specific files
npx hatch3r cli-tools     # Manage CLI tools (picker / list / install / detect)
npx hatch3r mcp           # Manage MCP servers (setup / list / remove / env-check)
npx hatch3r add <pack>    # Install a community pack (coming soon)

hatch3r cli-tools and hatch3r mcp are side-door entry points for users who skipped a section during init. cli-tools defaults to the picker (list, install, detect are the other subcommands); mcp requires a subcommand (setup, list, remove <id>, env-check).

Every non-stub command accepts --format <human|json> and --quiet; mutating commands add --dry-run. --format json emits exactly one JSON document on stdout and is an exit-2 usage error on a prompting invocation.

CLI Tools

Since 1.7.5, hatch3r ships a first-class CLI-tools surface as the token-efficient alternative to MCP. The picker runs during init (3 tiers grouped, tier-1 default-on, tier-2 conditional on detected project signals, tier-3 opt-in). Detection probes each tool via command -v / where with a 2s timeout; the installer prints copy-paste commands grouped by package manager and never executes on your behalf. 5 essentials (ripgrep, jq, gh, fd, fzf) ship as standalone skills; the remaining 24 tools live in a single hatch3r-cli-toolbox skill, emitted to all 3 adapters. Manage at any time via npx hatch3r cli-tools [list|install|detect]. See CLI Tools for the full 29-tool table and the trade-off discussion vs MCP.

Workflow

hatch3r provides a full project lifecycle, from setup to release:

1. Initialize -- npx hatch3r init detects your repo and platform, asks about profile, tools, and CLI tools, generates agents/skills/rules/commands. For headless CI, pass --yes (add --mcp to also configure MCP servers).
2. Set up the board -- hatch3r-board-init creates or connects a Projects V2 board with status fields, label taxonomy, and config writeback.
3. Define work -- Create a todo.md at the project root (one item per line).
4. Fill the board -- hatch3r-board-fill parses todo.md, classifies items, groups into epics, builds a dependency DAG, and marks issues status:ready.
5. Groom the backlog -- hatch3r-board-groom surfaces stale items, priority imbalances, and decomposition candidates.
6. Pick up work -- hatch3r-board-pickup auto-selects the next issue by dependency order and priority, creates a branch, delegates implementation, and opens a PR.
7. Review cycle -- Reviewer + fixer agents loop (max 3 iterations) until clean, then testability and security specialists run final checks.
8. Release -- hatch3r-release determines the semver bump, generates a changelog, tags, and publishes.

After init: For greenfield, run hatch3r-project-spec then hatch3r-roadmap. For brownfield, run hatch3r-codebase-map. For a single feature, run hatch3r-feature-plan. For small changes, run hatch3r-quick-change.

Editor Plugin

hatch3r ships plugin manifests for both Claude Code (.claude-plugin/marketplace.json) and Cursor (.cursor-plugin/plugin.json). Install it straight from this repo as a marketplace — in Claude Code, run /plugin marketplace add hatch3r/hatch3r then /plugin install hatch3r@hatch3r — for access to all rules, skills, agents, and commands without running init.

Why hatch3r vs just AGENTS.md?

AGENTS.md (Linux Foundation AAIF spec, 60K+ repos as of January 2026) is the greatest-common-denominator markdown standard for agent instructions; it is consumed by 20+ tools including Cursor, Copilot, Codex, and Gemini CLI. hatch3r is complementary: AGENTS.md describes one file's content; hatch3r owns the entire generation pipeline that emits tool-native configurations across 5 artifact classes (rules, skills, commands, hooks, MCP servers) for 3 supported platforms (Claude Code, Cursor, GitHub Copilot). Three measurable differences:

• Scope: AGENTS.md is one flat instruction file per repo; hatch3r generates platform-specific structured output (.mdc rules with frontmatter scoping for Cursor, CLAUDE.md with managed blocks for Claude Code, .github/instructions/ + .github/prompts/ for Copilot) plus board commands, MCP server configs, and event-driven hooks.
• Currency: AGENTS.md content is hand-edited per project; hatch3r ships canonical content (29 agents + 66 rules + 53 skills + 31 commands + 7 hooks + 10 MCP servers — see governance/inventory.json) audited weekly across 24 governance domains.
• Adoption path: AGENTS.md remains the spec hatch3r-emitted Cursor / Claude / Copilot configurations align with — the 1.9.0 hard-cut withdrew direct AGENTS.md emission per CONSTITUTION §6 Decision #12, but AAIF spec evolution feeds per-adapter feature work for the 3 supported adapters. Use AGENTS.md alone when one flat file suffices for your project; use hatch3r when you need the full content + tooling stack.