Enhanced MCP server implementing the Ralph Wiggum technique with history tracking, git integration, and external tools
npm install ralph-wiggum-mcpralph_iterate
claude_desktop_config.json):
json
{
"mcpServers": {
"ralph-wiggum": {
"command": "npx",
"args": ["ralph-wiggum-mcp"]
}
}
}
`
That's it! The package will be automatically downloaded and run on first use.
$3
If you want to develop or contribute:
`bash
git clone https://github.com/cbuntingde/ralph-wiggum-mcp.git
cd ralph-wiggum-mcp
npm install
npm run build
`
Then configure your MCP client to use the local build:
`json
{
"mcpServers": {
"ralph-wiggum": {
"command": "node",
"args": ["C:/path/to/ralph-wiggum-mcp/dist/index.js"]
}
}
}
`
Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| RALPH_MAX_ITERATIONS | 50 | Default maximum iterations |
| RALPH_AUTO_COMMIT | false | Enable auto-commit by default |
| RALPH_HISTORY_LIMIT | 100 | Maximum history entries |
| RALPH_STAGNATION_THRESHOLD | 5 | Iterations before stagnation warning |
Tools Reference
$3
#### ralph_loop
Start an iterative development loop.
Parameters:
- prompt (string, optional*) – Task prompt
- template_id (string, optional) – Pre-built template ID
- max_iterations (number, optional) – Max iterations (0 = unlimited)
- completion_promise (string, optional) – Promise phrase signaling completion
- git_enabled (boolean, optional) – Enable git integration (default: true)
- auto_commit (boolean, optional) – Auto-commit after each iteration (default: false)
*Either prompt or template_id required.
#### ralph_iterate
Process the next iteration with tracking.
Parameters:
- last_output (string, required) – Your last output/response
- files_modified (array, optional) – Files modified
- commands_run (array, optional) – Commands executed
- errors (array, optional) – Errors encountered
- run_tools (array, optional) – External tool presets (e.g., ['javascript-test'])
#### ralph_cancel
Cancel the active Ralph loop.
#### ralph_status
Get current status with progress insights.
Returns: iteration number, history summary, stagnation detection, estimated iterations remaining.
$3
#### ralph_history
Get detailed iteration history report.
Returns: timestamps, durations, files modified, commands run, errors, git commits, tool results.
$3
#### ralph_list_templates
List available templates.
Parameter: category (optional) – Filter by category: api, testing, refactoring, debugging, documentation, performance, security, database
#### ralph_get_template
Get template details.
Parameter: template_id (required) – Template ID
Returns: full prompt text, suggested settings, recommended tools.
$3
#### ralph_git_status
Get git status and diff summary.
#### ralph_git_commit
Create a git commit manually.
Parameter: message (required) – Commit message
#### ralph_git_context
Get context from recent Ralph commits.
Parameter: count (optional) – Number of commits (default: 5)
$3
#### ralph_run_tools
Run external tool presets.
Parameter: presets (required, array) – Preset names
Available presets:
- javascript-test – npm test
- javascript-lint – ESLint
- python-test – pytest
- python-lint – ruff
- rust-test – cargo test
- rust-lint – clippy
- go-test – go test
- build – Verify project builds
#### ralph_detect_tools
Detect available tool presets for your project.
#### ralph_list_tools
List all tool presets with descriptions.
Usage Examples
$3
Step 1: Start the loop
Tell your AI to use ralph_loop with:
`
prompt: "Create a simple to-do list app with Node.js and Express.
Requirements:
- Add, view, delete todos
- Store in memory
- Output DONE when complete"
`
Step 2: AI starts working
The AI will create initial files. When it reports what it did, it calls ralph_iterate with:
`
last_output: "I created server.js with Express and endpoints for todos"
files_modified: ["server.js", "package.json"]
`
Step 3: AI continues iterating
The AI keeps improving the code, calling ralph_iterate each time with updates.
Step 4: Completion
When the AI meets all requirements, it outputs and the loop stops.
$3
Step 1: Start a development loop
`
ralph_loop with:
- prompt: "Create a calculator module with add, subtract, multiply, divide functions.
Write tests first. Keep iterating until tests pass.
Output CALCULATOR_DONE when complete."
- max_iterations: 20
`
Step 2: AI writes first test
`
ralph_iterate with:
- last_output: "Created calculator.test.js with test for add() function"
- files_modified: ["calculator.test.js"]
`
Step 3: AI implements function
`
ralph_iterate with:
- last_output: "Implemented add() function in calculator.js"
- files_modified: ["calculator.js"]
- run_tools: ["javascript-test"]
`
Step 4: Check if tests pass
The run_tools parameter runs npm test. If tests fail, the AI sees the errors and tries again.
Step 5: Repeat until success
The loop continues calling ralph_iterate until all tests pass, then outputs .
$3
Step 1: See available templates
`
ralph_list_templates
`
Step 2: Get a specific template
`
ralph_get_template with template_id: "rest-api"
`
This shows you the full prompt and recommended settings.
Step 3: Start with the template
`
ralph_loop with:
- template_id: "rest-api"
- auto_commit: true
`
The AI automatically uses the template's prompt and settings.
$3
While a loop is running, you can check progress:
`
ralph_status
`
This shows:
- Current iteration number
- Files modified so far
- Errors encountered
- Whether you've been stuck on the same error
`
ralph_history
`
Shows detailed history of every iteration.
$3
Quick start using built-in templates:
`
ralph_loop with:
- template_id: "rest-api"
- auto_commit: true
Each iteration:
ralph_iterate with:
- last_output: your response
- run_tools: ["javascript-test", "javascript-lint"]
`
$3
`
ralph_loop with:
- template_id: "tdd"
Each iteration:
ralph_iterate with:
- last_output: your response
- files_modified: ["src/calculator.ts", "src/calculator.test.ts"]
- run_tools: ["javascript-test"]
`
$3
`
ralph_loop with:
- prompt: "Fix authentication bug. Output BUG_FIXED when tests pass."
- max_iterations: 15
Track with:
- ralph_status
- ralph_history
- ralph_git_context
`
Best Practices
1. Clear Completion Criteria
`
Build a REST API for todos.
Requirements:
- All CRUD endpoints working
- Input validation
- Tests passing (coverage > 80%)
- README with API docs
Output API_COMPLETE when done.
`
2. Use External Tools
`
Implement feature X with tests.
Each iteration:
- ralph_iterate with run_tools: ["javascript-test"]
- Only output COMPLETE when tests pass
`
3. Enable Auto-Commit
`
Refactor codebase with auto_commit: true.
Each successful step is saved automatically.
If broken, revert to last working state.
`
4. Leverage Templates
`
ralph_list_templates → view available templates
ralph_get_template with template_id: "tdd" → view full prompt
ralph_loop with template_id: "tdd" → start loop
`
Philosophy
1. Iteration > Perfection – Let the loop refine the work
2. Failures Are Data – Predictable failures inform prompt tuning
3. Operator Skill Matters – Success depends on good prompts
4. Persistence Wins – Keep trying until success
5. Measurement Improves Outcomes – Track and learn from history
When to Use
Best For:
- Well-defined tasks with clear success criteria
- Tasks requiring iteration and refinement
- Greenfield projects
- Tasks with automatic verification (tests, linters)
- Refactoring with safety nets
Not Recommended For:
- Human judgment or design decisions
- One-shot operations
- Unclear success criteria
- Production debugging (use targeted debugging instead)
Development
| Command | Description |
|---------|-------------|
| npm run build | Compile TypeScript |
| npm run dev | Watch mode |
| npm start | Start server |
| npm test | Run tests |
| npm run test:security | Security tests |
| npm run test:coverage | Coverage tests |
Project Structure:
`
ralph-wiggum-mcp/
├── src/
│ ├── index.ts # Server entry
│ ├── handlers/ # Tool handlers
│ ├── templates/ # Loop templates
│ └── utils/ # Utilities
├── dist/ # Compiled output
└── package.json
``