feat(mcp): add experimental MCP server support

Cargo.toml

@@ -5,6 +5,7 @@ members = [
     "crates/ralph-core",
     "crates/ralph-adapters",
     "crates/ralph-tui",
+    "crates/ralph-mcp",
     "crates/ralph-cli",
     "crates/ralph-bench",
 ]
@@ -102,6 +103,10 @@ chrono = { version = "0.4", features = ["serde"] }
 # Testing
 tempfile = "3"
 
+# MCP (Model Context Protocol)
+rmcp = { version = "0.8", features = ["server", "transport-io", "macros"] }
+schemars = "1.0"
+
 # PTY support
 portable-pty = "0.9"
 nix = { version = "0.29", features = ["signal", "term"] }
@@ -114,6 +119,7 @@ ralph-proto = { version = "2.0.9", path = "crates/ralph-proto" }
 ralph-core = { version = "2.0.9", path = "crates/ralph-core" }
 ralph-adapters = { version = "2.0.9", path = "crates/ralph-adapters" }
 ralph-tui = { version = "2.0.9", path = "crates/ralph-tui" }
+ralph-mcp = { version = "2.0.9", path = "crates/ralph-mcp" }
 ralph-cli = { version = "2.0.9", path = "crates/ralph-cli" }
 ralph-bench = { version = "2.0.9", path = "crates/ralph-bench" }
 

README.md

@@ -24,6 +24,7 @@ v1.0.0 was ralphed into existence with little oversight and guidance. v2.0.0 is
 - [Presets](#presets)
 - [Key Concepts](#key-concepts)
 - [CLI Reference](#cli-reference)
+- [MCP Support (Experimental)](#mcp-support-experimental)
 - [Architecture](#architecture)
 - [Building & Testing](#building--testing)
 - [Contributing](#contributing)
@@ -69,6 +70,7 @@ See [AGENTS.md](AGENTS.md) for the full philosophy.
 - **Presets Library** — 20+ pre-configured workflows for common development patterns
 - **Interactive TUI** — Real-time terminal UI for monitoring Ralph's activity (experimental)
 - **Session Recording** — Record and replay sessions for debugging and testing (experimental)
+- **MCP Server** — Expose Ralph as an MCP server for integration with Claude Desktop and other MCP clients (experimental)
 
 ## Installation
 
@@ -426,6 +428,7 @@ tests: pass, lint: pass, typecheck: pass
 | `ralph init` | Initialize configuration file |
 | `ralph clean` | Clean up `.agent/` directory |
 | `ralph emit` | Emit an event to the event log |
+| `ralph mcp serve` | Start MCP server over stdio (experimental) |
 
 ### Global Options
 
@@ -473,16 +476,79 @@ tests: pass, lint: pass, typecheck: pass
 | `<INPUT>` | Optional description text or path to PDD plan file |
 | `-b, --backend <BACKEND>` | Backend to use (overrides config and auto-detection) |
 
+## MCP Support (Experimental)
+
+Ralph can run as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server, allowing integration with Claude Desktop and other MCP-compatible clients.
+
+### Starting the MCP Server
+
+```bash
+# Start MCP server over stdio
+ralph mcp serve
+
+# With specific config file
+ralph mcp serve -c my-ralph.yml
+```
+
+### Available Tools
+
+When running as an MCP server, Ralph exposes these tools:
+
+| Tool | Description |
+|------|-------------|
+| `ralph_run` | Start a new Ralph orchestration session with a prompt |
+| `ralph_status` | Get status of a running or completed session |
+| `ralph_stop` | Stop a running session (idempotent) |
+| `ralph_list_sessions` | List all sessions |
+| `ralph_list_hats` | List available hats from the config |
+
+### Claude Desktop Configuration
+
+Add Ralph to your Claude Desktop MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "ralph": {
+      "command": "ralph",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+With a specific config file:
+
+```json
+{
+  "mcpServers": {
+    "ralph": {
+      "command": "ralph",
+      "args": ["mcp", "serve", "-c", "/path/to/your/ralph.yml"]
+    }
+  }
+}
+```
+
+### Example Usage
+
+Once configured, you can ask Claude Desktop to:
+
+- "Use Ralph to implement a REST API for user management"
+- "Start a Ralph session to fix the failing tests"
+- "Check the status of the running Ralph session"
+
 ## Architecture
 
-Ralph is organized as a Cargo workspace with six crates:
+Ralph is organized as a Cargo workspace with seven crates:
 
 | Crate | Purpose |
 |-------|---------|
 | `ralph-proto` | Protocol types: Event, Hat, Topic, Error |
 | `ralph-core` | Business logic: EventLoop, HatRegistry, Config |
 | `ralph-adapters` | CLI backend integrations (Claude, Kiro, Gemini, etc.) |
 | `ralph-tui` | Terminal UI with ratatui |
+| `ralph-mcp` | MCP server for Claude Desktop integration |
 | `ralph-cli` | Binary entry point and CLI parsing |
 | `ralph-bench` | Benchmarking harness (dev-only) |
 

crates/ralph-cli/Cargo.toml

@@ -23,6 +23,7 @@ ralph-proto.workspace = true
 ralph-core.workspace = true
 ralph-adapters.workspace = true
 ralph-tui.workspace = true
+ralph-mcp.workspace = true
 
 tokio.workspace = true
 clap.workspace = true

crates/ralph-cli/src/main.rs

@@ -227,6 +227,9 @@ enum Commands {
 
     /// Generate code task files from descriptions or plans
     Task(TaskArgs),
+
+    /// MCP (Model Context Protocol) server commands
+    Mcp(McpArgs),
 }
 
 /// Arguments for the init subcommand.
@@ -442,6 +445,20 @@ struct TaskArgs {
     backend: Option<String>,
 }
 
+/// Arguments for the mcp subcommand.
+#[derive(Parser, Debug)]
+struct McpArgs {
+    #[command(subcommand)]
+    command: McpCommands,
+}
+
+/// MCP (Model Context Protocol) subcommands.
+#[derive(Subcommand, Debug)]
+enum McpCommands {
+    /// Start the MCP server over stdio
+    Serve,
+}
+
 #[tokio::main]
 async fn main() -> Result<()> {
     // Install panic hook to restore terminal state on crash
@@ -465,6 +482,7 @@ async fn main() -> Result<()> {
         Some(Commands::Emit(args)) => emit_command(cli.color, args),
         Some(Commands::Plan(args)) => plan_command(cli.config, cli.color, args),
         Some(Commands::Task(args)) => task_command(cli.config, cli.color, args),
+        Some(Commands::Mcp(args)) => mcp_command(args).await,
         None => {
             // Default to run with no overrides (backwards compatibility)
             let args = RunArgs {
@@ -1126,6 +1144,16 @@ fn task_command(config_path: PathBuf, color_mode: ColorMode, args: TaskArgs) ->
     })
 }
 
+/// Runs MCP (Model Context Protocol) commands.
+async fn mcp_command(args: McpArgs) -> Result<()> {
+    match args.command {
+        McpCommands::Serve => {
+            // Note: MCP servers log to stderr since stdout is reserved for the protocol
+            ralph_mcp::serve_stdio().await
+        }
+    }
+}
+
 /// Lists directory contents recursively for dry-run mode.
 fn list_directory_contents(path: &Path, use_colors: bool, indent: usize) -> Result<()> {
     let entries = fs::read_dir(path)?;

crates/ralph-mcp/Cargo.toml

@@ -0,0 +1,31 @@
+[package]
+name = "ralph-mcp"
+edition.workspace = true
+version.workspace = true
+license.workspace = true
+description = "MCP server for Ralph Orchestrator"
+repository.workspace = true
+homepage.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+ralph-proto.workspace = true
+ralph-core.workspace = true
+
+tokio.workspace = true
+async-trait.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+serde_yaml.workspace = true
+thiserror.workspace = true
+anyhow.workspace = true
+tracing.workspace = true
+
+rmcp.workspace = true
+schemars.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true
+wait-timeout = "0.2"

crates/ralph-mcp/src/lib.rs

@@ -0,0 +1,17 @@
+//! # ralph-mcp
+//!
+//! MCP (Model Context Protocol) server for Ralph Orchestrator.
+//!
+//! This crate provides an MCP server that exposes Ralph's orchestration
+//! capabilities to MCP clients like Claude Desktop. Tools available:
+//!
+//! - `ralph_run` - Start a new Ralph orchestration session
+//! - `ralph_status` - Get status of a running/completed session
+//! - `ralph_stop` - Stop a running session
+//! - `ralph_list_sessions` - List all sessions
+//! - `ralph_list_hats` - List available hats from config
+
+mod server;
+mod tools;
+
+pub use server::{RalphMcpServer, serve_stdio};