开源MCP工具

Quick Start

Requires Node.js 22+.

npx hatch3r init

That's it. hatch3r detects your repo, asks about your project context (greenfield/brownfield, solo/team), lets you choose a content profile (minimal/standard/full/custom), and generates everything. The platform (GitHub, Azure DevOps, or GitLab) is auto-detected from your git remote. Run into issues? See Troubleshooting.

MCP Configuration

Since 1.7.5, MCP is opt-in. npx hatch3r init gates MCP behind a Yes/No prompt (default No) after the features picker. Declining the gate skips MCP entirely — no .env.mcp, no mcp.json, no servers in the manifest. When you accept the gate, hatch3r init creates a .env.mcp file with required environment variables for your selected MCP servers (gitignored by default) and writes MCP config to the tool-appropriate location (.cursor/mcp.json, .mcp.json, .vscode/mcp.json, etc.).

• VS Code / Copilot: Secrets are passed 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. See MCP Setup for full setup, per-server details, and PAT scope guidance.

CLI Commands

npx hatch3r init          # Interactive setup
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 or want to revisit later. Each accepts subcommands: cli-tools defaults to opening the picker (list, install, detect are the other subcommands); mcp requires a subcommand (setup, list, remove <id>, env-check).

CLI Tools

Since 1.7.5, hatch3r ships a first-class CLI-tools surface area 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 advanced). 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 (skills/hatch3r-cli-{id}/SKILL.md); the remaining 24 tools live in a single category-indexed hatch3r-cli-toolbox skill, emitted to all 3 supported adapters.

Manage CLI tools at any time:

npx hatch3r cli-tools           # open picker
npx hatch3r cli-tools list      # selection + install status
npx hatch3r cli-tools install   # print install commands for missing tools
npx hatch3r cli-tools detect    # read-only detection report

See CLI Tools for the full 29-tool table, decision tree, and 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 context and profile, generates agents/skills/rules/commands/MCP. For headless CI, pass --yes with optional flags. See agentic process diagrams.
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 for selective refinement.
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 test-writer and security-auditor 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.

Platform Agentic Workflows

hatch3r includes a complete board management system supporting GitHub, Azure DevOps, and GitLab. Configure in hatch.json:

{
  "board": {
    "owner": "my-org",
    "repo": "my-repo",
    "projectNumber": 1,
    "areas": ["area:frontend", "area:backend", "area:infra"]
  },
  "models": {
    "default": "opus",
    "agents": { "hatch3r-lint-fixer": "sonnet" }
  }
}

Cursor Plugin

hatch3r is also available as a Cursor plugin. Enable it for instant access to all rules, skills, agents, and commands without running init.