Ralph Loop MCP (Node + TypeScript)

This MCP server turns the repo's .ralph/ folder into a 3-phase workflow:

• Phase 1: Create or refine plan documents under .github/plans/. Phase 1 produces plan files only.
• Phase 2: Generate/refine specs under .ralph/specs/** and tasks in .ralph/fix_plan.md.
• Phase 3: Iterate one task at a time with strict verification (npm run ci + npm run test:e2e).

See docs/DESIGN.md for architecture and positioning.

Phase 1 generator script

ralph.generate_phase1 bootstraps .ralph/phase1.sh and seeds .github/plans/project-plan.md when missing. The generated Phase 1 session is intentionally constrained to planning output only:

• It writes plan documents only under .github/plans/

• It does not create .ralph/specs/**

• It does not create .ralph/fix_plan.md task items

• Run directly: bash ./.ralph/phase1.sh

• Run via MCP tool: ralph.generate_phase1

Phase 2 generator script

ralph.generate_phase2 scaffolds .ralph/phase2.sh and creates the baseline Phase 2 artifacts:

• .ralph/specs/*.md

• .ralph/fix_plan.md

• .ralph/config.json

• .ralph/logs/progress.txt

• .ralph/logs/learnings.md

• Run directly: bash ./.ralph/phase2.sh

• Run via MCP tool: ralph.generate_phase2

ralph.generate_phase2 performs a lightweight schema validation of .ralph/config.json. If the file exists and is invalid, the tool reports validation errors without executing the script.

Phase 3 generator script

ralph.generate_phase3 scaffolds .ralph/phase3.sh and creates the Phase 3 prompt files. It fails with a clear error if .ralph/fix_plan.md does not yet exist. When the fix plan has fewer than five unchecked active tasks, it seeds Phase 2 planning items as checkboxes automatically.

Artifacts created:

• .ralph/phase3.sh

• .ralph/phase3-plan-prompt.md

• .ralph/phase3-dev-prompt.md

• .ralph/phase3-dev-signoff-prompt.md

• .ralph/phase3-qa-prompt.md

• .ralph/phase3-qa-close-prompt.md

• .ralph/logs/phase3-feedback.md

• Run directly: bash ./.ralph/phase3.sh

• Run via MCP tool: ralph.generate_phase3

Prerequisites

• Node.js 20 or later
• npm
• Build the package before running or testing (see Build section below)

Install

Standalone (this repo cloned directly as the package root):

npm install

Nested (package embedded under a parent monorepo, e.g. at ./mcp/ralph_loop_mcp):

npm install --prefix ./mcp/ralph_loop_mcp

Build

Standalone:

npm run build

Nested:

npm run --prefix ./mcp/ralph_loop_mcp build

Run (stdio)

Standalone:

node dist/index.js

Nested:

node ./mcp/ralph_loop_mcp/dist/index.js

VS Code MCP registration

Set cwd to the target project -- the repo whose .ralph/ folder the server will manage. This is typically the project you are actively developing, not the directory where this MCP package lives.

Example configuration for a standalone clone (open the target project folder in VS Code so ${workspaceFolder} resolves to it):

{
  "mcpServers": {
    "ralph-loop": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Example for a nested layout where the package lives at ./mcp/ralph_loop_mcp inside the target project:

{
  "mcpServers": {
    "ralph-loop": {
      "command": "node",
      "args": ["./mcp/ralph_loop_mcp/dist/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}

If VS Code reports ${workspaceFolder} cannot be resolved, open the repository with File -> Open Folder..., or set cwd to an absolute path pointing at the target project root.

Verification prereqs

ralph.run_verification runs npm run ci followed by npm run test:e2e on the target repo (the project under cwd). Both scripts must be defined in that repo's package.json, or the tool will reject them by design.

To extend the allowlist for additional scripts, add an allowedNpmScripts array to .ralph/config.json in the target repo:

{
  "allowedNpmScripts": ["lint", "type-check"]
}

Conventions

• .ralph/fix_plan.md is the task source of truth.
• Blocked tasks live under a dedicated heading: ## Blocked (or ## Blocked Tasks).
• Phase 1 planning documents live under .github/plans/.
• Phase 2 generator script lives at .ralph/phase2.sh and is auto-created by ralph.generate_phase2 when absent.
• Phase 3 generator script lives at .ralph/phase3.sh and is auto-created by ralph.generate_phase3 when absent.

Dev tests

Standalone:

npm test

Nested:

npm run --prefix ./mcp/ralph_loop_mcp test

Note: Run npm run build before running tests for the first time so dist/index.js exists for integration tests.