merlyn

local development coach with MCP server, interactive TUI, and AI-powered analysis. a stripped-down fork of midas-mcp with all cloud/dashboard/pilot code removed.

what it does

merlyn tracks your project phase and tells you what to do next.

1. run merlyn -- TUI starts, analyzes your project with AI
2. AI detects your phase -- PLAN / BUILD / SHIP / GROW
3. shows a suggested prompt -- "do this next" with explanation
4. press [c] to copy the prompt, paste in Cursor
5. Cursor calls MCP tools -- midas_analyze, midas_verify, etc.
6. tools update state -- phase advances, progress tracked
7. next time you run merlyn -- knows where you left off

quick start

npx merlyn-mcp

launches the interactive TUI coach. press ? for help.

cursor MCP config

add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "merlyn": {
      "command": "npx",
      "args": ["merlyn-mcp", "server"]
    }
  }
}

37 tools, 20 prompts, 5 resources -- all local, no cloud.

CLI commands

merlyn-mcp                interactive coach (recommended)
merlyn-mcp status         show current phase and progress
merlyn-mcp init <name>    initialize new project
merlyn-mcp audit          audit against 12 ingredients
merlyn-mcp docs           check planning docs
merlyn-mcp metrics        session metrics
merlyn-mcp weekly         weekly suggestion patterns
merlyn-mcp server         start MCP server
merlyn-mcp help           show help

the four phases

PLAN -- idea, research, PRD, gameplan. understand what you're building before you build it.

BUILD -- rules, index, read, research, implement, test, debug. the 7-step cycle. if stuck 3+ times, tornado: research + logs + tests.

SHIP -- review, deploy, monitor. gates must pass (build, test, lint) before advancing.

GROW -- feedback, analyze, iterate. collect data, triage, plan next cycle.

key tools

the MCP tools keep midas_ prefix for compatibility with existing cursor configs.

• midas_analyze -- AI analysis of project state and phase
• midas_suggest_prompt -- get phase-appropriate next action
• midas_advance_phase -- move to next step/phase
• midas_verify -- run build/test/lint gates
• midas_journal_save -- save conversation context
• midas_tornado -- research + logs + tests debugging cycle
• midas_oneshot -- construct retry prompt from error
• midas_horizon -- expand context when output doesn't fit
• midas_start_hotfix -- emergency bug fix mode
• midas_completeness -- 12-category production readiness score
• midas_vuln_scan -- security vulnerability scanner

three principles

oneshot -- when things break, go back with original prompt + error + "avoid this" instead of patching forward.

tornado -- three forces spinning together solve any problem: research + logs + tests.

horizon -- AI thinks vertical (implementation). you provide horizontal (context). wrong output means widen your context.

AI analysis

merlyn uses the Anthropic API for smart project analysis. optional but recommended (~$0.003/analysis). configure in ~/.midas/config.json or press k in the TUI.

without an API key, merlyn falls back to deterministic local analysis based on file presence and git history.

development

git clone https://github.com/christiancattaneo/merlyn-mcp
cd merlyn
npm install
npm run build
npm test

license

MIT