MCP 服务器

ralph-loop-mcp

A cross-platform MCP server implementing the Ralph Loop iterative development technique where a worker model does the work and a reviewer model provides cross-model review until approval.

README

ralph-loop-runner

A cross-platform implementation of the Ralph Loop — a multi-model iterative development technique where a "worker" model does the work and a "reviewer" model provides cross-model review, iterating until the reviewer says "SHIP".

Based on:

Ralph Wiggum as a "software engineer" by Geoffrey Huntley
Ralph Loop | goose
ralph-wiggum-mcp npm package

Overview

The Ralph Loop implements a two-phase iterative workflow:

┌─────────────────────────────────────────────────────────────┐
│                    RALPH LOOP                               │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌─────────┐      WORK PHASE      ┌─────────┐             │
│   │  TASK   │ ──────────────────▶  │ WORKER  │             │
│   │         │   fresh context      │ (Model A)│             │
│   └─────────┘                      └────┬────┘             │
│                                         │                  │
│                                         ▼                  │
│                              ┌─────────────────┐          │
│                              │ Submit Work +   │          │
│                              │ Summary         │          │
│                              └────────┬────────┘          │
│                                       │                   │
│                                       ▼                   │
│   ┌─────────┐      REVIEW PHASE    ┌─────────┐           │
│   │ REVIEWER│ ◀─────────────────── │  WORK   │           │
│   │(Model B)│   cross-model review │ OUTPUT  │           │
│   └────┬────┘                      └─────────┘           │
│        │                                                  │
│        ▼                                                  │
│   ┌─────────┐                                             │
│   │ DECISION│                                             │
│   │ SHIP    │──────▶ COMPLETE ✓                            │
│   │ REVISE  │──────▶ Next Iteration (fresh context)        │
│   └─────────┘                                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Features

Cross-platform Native: Single script per platform (Bash for Linux/macOS, PowerShell for Windows) — no Node.js runtime required
Dual Mode Operation:
- MCP Server Mode — JSON-RPC 2.0 over stdio for integration with AI agents
- CLI Mode — Run the full loop directly from command line
Session-based: Multiple concurrent Ralph Loop sessions supported
File-based State: Persistent state stored in ~/.goose/ralph/{sessionId}/
11 MCP Tools: Complete workflow control via MCP tools, including ralph_loop_run for full automation
Cross-Model Review: Worker/reviewer model configuration with validation
Multiple LLM Providers: Anthropic (Claude), OpenAI, Google (Gemini), GitHub Copilot, Goose
Flexible Configuration: Environment variables, CLI arguments, or MCP tool calls

Implementations

Platform	File	Requirements
Linux/macOS	`ralph-loop-runner.sh`	bash, jq
Windows	`ralph-loop-runner.ps1`	PowerShell 5.1+, jq

Both implementations provide identical functionality in a single script file each.

Installation

Prerequisites

jq - JSON processor (required for both Bash and PowerShell)
- Linux: apt-get install jq / yum install jq / apk add jq
- macOS: brew install jq
- Windows: choco install jq / winget install jqlang.jq / scoop install jq
Bash (Linux/macOS) or PowerShell 5.1+ (Windows)
LLM CLI (for ralph_loop_run and CLI mode):
- claude (Anthropic)
- openai (OpenAI)
- gemini (Google)
- copilot (GitHub Copilot) — npm install -g @github/copilot
- goose (Goose) — go install github.com/aaif-goose/goose@latest

Setup

# Clone the repository
git clone https://github.com/sheldonrobinson/ralph-loop-mcp
cd ralph-loop-mcp

# Make executable (Linux/macOS)
chmod +x ralph-loop-runner.sh

# Configure in Claude Desktop (MCP mode):
{
  mode):
{
  "mcpServers": {
    "ralph-loop": {
      "command": "/path/to/ralph-loop-runner.sh",
      "args": []
    }
  }
}

Windows (PowerShell):

# Configure in claude_desktop_config.json:
{
  "mcpServers": {
    "ralph-loop": {
      "command": "powershell.exe",
      "args": ["-File", "C:\\path\\to\\ralph-loop-runner.ps1"]
    }
  }
}

Usage

CLI Mode (Direct Execution)

Run the complete Ralph Loop directly from the command line:

# Linux/macOS - task as argument
./ralph-loop-runner.sh "Implement user authentication with JWT tokens"

# Linux/macOS - task from file
./ralph-loop-runner.sh ./task.md

# Windows
.\ralph-loop-runner.ps1 "Implement user authentication with JWT tokens"
.\ralph-loop-runner.ps1 .\task.md

With environment variables:

RALPH_WORKER_MODEL=claude-3-5-sonnet \
RALPH_WORKER_PROVIDER=anthropic \
RALPH_REVIEWER_MODEL=gpt-4o \
RALPH_REVIEWER_PROVIDER=openai \
RALPH_MAX_ITERATIONS=5 \
./ralph-loop-runner.sh "Your task here"

With command-line arguments:

./ralph-loop-runner.sh "Your task here" \
  --worker-model claude-3-5-sonnet \
  --worker-provider anthropic \
  --worker-agent goose \
  --reviewer-model gpt-4o \
  --reviewer-provider openai \
  --reviewer-agent goose \
  --max-iterations 5 \
  --work-guidelines ./recipes/ralph-work.yaml \
  --review-guidelines ./recipes/ralph-review.yaml \
  --session-id my-feature

MCP Server Mode

When run without arguments, the script runs as an MCP server over stdio:

# Linux/macOS
./ralph-loop-runner.sh

# Windows
powershell.exe -File ralph-loop-runner.ps1

Quick Start: Full Automated Loop (Recommended)

Use the ralph_loop_run tool to run the complete worker/reviewer loop automatically:

{
  "method": "tools/call",
  "params": {
    "name": "ralph_loop_run",
    "arguments": {
      "sessionId": "my-feature",
      "task": "Implement user authentication with JWT tokens",
      "maxIterations": 5,
      "workerModel": "claude-3-5-sonnet",
      "workerProvider": "anthropic",
      "workerAgent": "goose",
      "reviewerModel": "gpt-4o",
      "reviewerProvider": "openai",
      "reviewerAgent": "goose",
      "crossModelReviewEnforced": true,
      "workGuidelines": "/path/to/ralph-work.yaml",
      "reviewGuidelines": "/path/to/ralph-review.yaml"
    }
  }
}

This tool handles:

Initialization - Creates session with worker/reviewer configuration
Orchestration - Loops through WORK → REVIEW phases
Execution - Calls LLM providers via CLI (claude, openai, gemini, copilot, goose)
State Management - Persists all state to ~/.goose/ralph/{sessionId}/

Manual Step-by-Step Workflow

For more control, use individual tools:

Initialize Session

{
  "method": "tools/call",
  "params": {
    "name": "ralph_loop_initialize",
    "arguments": {
      "sessionId": "my-feature",
      "task": "Implement user authentication with JWT tokens",
      "maxIterations": 5,
      "workerModel": "claude-3-5-sonnet",
      "workerProvider": "anthropic",
      "workerAgent": "goose",
      "reviewerModel": "gpt-4o",
      "reviewerProvider": "openai",
      "reviewerAgent": "goose"
    }
  }
}

Worker Phase - Get Task

{
  "method": "tools/call",
  "params": { "name": "ralph_loop_get_task", "arguments": { "sessionId": "my-feature" } }
}

Worker Phase - Submit Work

{
  "method": "tools/call",
  "params": {
    "name": "ralph_loop_submit_work",
    "arguments": {
      "sessionId": "my-feature",
      "iteration": 1,
      "work": "// Complete JWT implementation...",
      "summary": "Implemented JWT auth with access/refresh tokens, middleware, and tests"
    }
  }
}

Reviewer Phase - Get Work

{
  "method": "tools/call",
  "params": { "name": "ralph_loop_get_work", "arguments": { "sessionId": "my-feature" } }
}

Reviewer Phase - Submit Review

{
  "method": "tools/call",
  "params": {
    "name": "ralph_loop_submit_review",
    "arguments": {
      "sessionId": "my-feature",
      "iteration": 1,
      "decision": "REVISE",
      "feedback": "Add token expiration handling and improve error messages"
    }
  }
}

Next Iteration - Get Feedback

{
  "method": "tools/call",
  "params": { "name": "ralph_loop_get_feedback", "arguments": { "sessionId": "my-feature" } }
}

Available Tools

Tool	Description
`ralph_loop_initialize`	Initialize a new Ralph Loop session with a task
`ralph_loop_get_task`	Get the current task for the worker phase
`ralph_loop_submit_work`	Submit work results and summary from worker
`ralph_loop_get_work`	Get worker's submitted work for reviewer
`ralph_loop_submit_review`	Submit review decision (SHIP/REVISE) with feedback
`ralph_loop_get_feedback`	Get reviewer feedback for next iteration
`ralph_loop_get_status`	Get current session status (iteration, phase, state)
`ralph_loop_get_config`	Get worker/reviewer model configuration
`ralph_loop_reset`	Reset/clear a session
`ralph_loop_block`	Block current iteration with reason
`ralph_loop_run`	Run complete automated loop (initialization → orchestration → execution → state management)

State Management

State is stored in ~/.goose/ralph/{sessionId}/:

~/.goose/ralph/my-feature/
├── config.json           # Worker/reviewer model configuration
├── task.json             # Original task
├── work.json             # Current work submission
├── review.json           # Current review
├── work-complete.txt     # Worker completion flag
├── review-result.txt     # SHIP/REVISE decision
├── review-feedback.txt   # Reviewer feedback
├── RALPH-BLOCKED.md      # Blocking reason (if blocked)
└── iteration.txt         # Current iteration number

Cross-Model Review Setup

For true cross-model review, use different models for worker and reviewer:

Worker (e.g., Claude Sonnet):

Gets fresh context each iteration
Receives only task + feedback
Does the actual work

Reviewer (e.g., GPT-4, Gemini, or another Claude):

Reviews worker's output
Provides SHIP/REVISE decision
Gives specific feedback for revision

The crossModelReviewEnforced option (default: true) validates that worker and reviewer use different models/providers, warning if they are the same.

Blocking

If the worker gets stuck, they can block the iteration:

{
  "method": "tools/call",
  "params": {
    "name": "ralph_loop_block",
    "arguments": {
      "sessionId": "my-feature",
      "reason": "Cannot proceed - missing API credentials for external service"
    }
  }
}

This creates RALPH-BLOCKED.md and stops the loop until resolved.

Configuration

Environment Variables

Variable	Description	Default
`RALPH_WORKER_MODEL`	Worker model name	—
`RALPH_WORKER_PROVIDER`	Worker provider (anthropic/openai/google/copilot/goose)	—
`RALPH_WORKER_AGENT`	Worker agent (goose/claude/openai/gemini/copilot)	goose
`RALPH_REVIEWER_MODEL`	Reviewer model name	—
`RALPH_REVIEWER_PROVIDER`	Reviewer provider (anthropic/openai/google/copilot/goose)	—
`RALPH_REVIEWER_AGENT`	Reviewer agent (goose/claude/openai/gemini/copilot)	goose
`RALPH_MAX_ITERATIONS`	Max iterations (-1 for unlimited)	10
`RALPH_WORK_GUIDELINES`	Path to work guidelines/recipe	`$RALPH_RECIPE_DIR/ralph-work.yaml`
`RALPH_REVIEW_GUIDELINES`	Path to review guidelines/recipe	`$RALPH_RECIPE_DIR/ralph-review.yaml`
`RALPH_RECIPE_DIR`	Base directory for recipes	`/usr/local/share/ralph-loop-runner/recipes`

Command-Line Arguments (CLI Mode)

Argument	Description
`--worker-model MODEL`	Worker model name
`--worker-provider PROVIDER`	Worker provider (anthropic/openai/google/copilot/goose)
`--worker-agent AGENT`	Worker agent (goose/claude/openai/gemini/copilot)
`--reviewer-model MODEL`	Reviewer model name
`--reviewer-provider PROVIDER`	Reviewer provider (anthropic/openai/google/copilot/goose)
`--reviewer-agent AGENT`	Reviewer agent (goose/claude/openai/gemini/copilot)
`--max-iterations N`	Max iterations (-1 for unlimited)
`--work-guidelines FILE`	Work guidelines/recipe file
`--review-guidelines FILE`	Review guidelines/recipe file
`--session-id ID`	Custom session ID

Supported Providers

Provider	CLI Command	Notes
Anthropic	`claude --model <model> --print`	Requires Anthropic API key
OpenAI	`openai chat --model <model> --no-stream`	Requires OpenAI API key
Google	`gemini --model <model> --format=text`	Requires Google API key
GitHub Copilot	`copilot -p --allow-all-tools --model <model>`	Requires `gh auth login` + Copilot subscription
Goose	`goose run --recipe <file> --session <id>`	Uses Goose recipes for structured workflows

API Reference

ralph_loop_initialize

{
  sessionId?: string;              // default: "default"
  task: string;                    // required
  maxIterations?: number;          // default: 10, -1 = unlimited
  workerModel?: string;            // e.g., "claude-3-5-sonnet"
  workerProvider?: string;         // e.g., "anthropic"
  workerAgent?: string;            // e.g., "goose"
  reviewerModel?: string;          // e.g., "gpt-4o"
  reviewerProvider?: string;       // e.g., "openai"
  reviewerAgent?: string;          // e.g., "goose"
  crossModelReviewEnforced?: boolean; // default: true
  workGuidelines?: string;         // path to work guidelines
  reviewGuidelines?: string;       // path to review guidelines
}

ralph_loop_get_task

{ sessionId?: string; }  // default: "default"

ralph_loop_submit_work

{
  sessionId?: string;  // default: "default"
  work: string;        // required
  summary: string;     // required
  iteration: number;   // required, >= 1
}

ralph_loop_get_work

{ sessionId?: string; }  // default: "default"

ralph_loop_submit_review

{
  sessionId?: string;           // default: "default"
  decision: "SHIP" | "REVISE";  // required
  feedback?: string;            // required for REVISE
  iteration: number;            // required, >= 1
}

ralph_loop_get_feedback

{ sessionId?: string; }  // default: "default"

ralph_loop_get_status

{ sessionId?: string; }  // default: "default"

ralph_loop_get_config

{ sessionId?: string; }  // default: "default"

ralph_loop_reset

{ sessionId?: string; }  // default: "default"

ralph_loop_block

{
  sessionId?: string;  // default: "default"
  reason: string;      // required
}

ralph_loop_run

{
  sessionId?: string;              // default: "default"
  task: string;                    // required
  maxIterations?: number;          // default: 10, -1 = unlimited
  workerModel: string;             // required
  workerProvider: string;          // required
  workerAgent?: string;            // default: "goose"
  reviewerModel: string;           // required
  reviewerProvider: string;        // required
  reviewerAgent?: string;          // default: "goose"
  crossModelReviewEnforced?: boolean; // default: true
  workGuidelines?: string;         // path to work guidelines
  reviewGuidelines?: string;       // path to review guidelines
}

License

MIT