ralph-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 G0d2i11a
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# Ralph MCP
+
+MCP server for autonomous PRD execution with Claude Code. Git worktree isolation, progress tracking, auto-merge.
+
+Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/).
+
+## Features
+
+- **PRD Parsing** - Extracts User Stories from markdown PRD files
+- **Git Worktree Isolation** - Each PRD runs in isolated worktree
+- **Progress Tracking** - Real-time status via `ralph_status()`
+- **Auto Merge** - One-click merge with conflict resolution
+- **Notifications** - Windows Toast when PRD completes
+
+## Installation
+
+### From npm
+
+```bash
+npm install -g ralph-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/G0d2i11a/ralph-mcp.git
+cd ralph-mcp
+npm install
+npm run build
+```
+
+## Configuration
+
+Add to `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ralph": {
+      "command": "npx",
+      "args": ["ralph-mcp"]
+    }
+  }
+}
+```
+
+Or if installed from source:
+
+```json
+{
+  "mcpServers": {
+    "ralph": {
+      "command": "node",
+      "args": ["/path/to/ralph-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Code to load.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `ralph_start` | Start PRD execution (parse PRD, create worktree, return agent prompt) |
+| `ralph_status` | View all PRD execution status |
+| `ralph_get` | Get single PRD details |
+| `ralph_update` | Update User Story status (called by agent) |
+| `ralph_stop` | Stop execution |
+| `ralph_merge` | Merge to main + cleanup worktree |
+| `ralph_merge_queue` | Manage serial merge queue |
+| `ralph_set_agent_id` | Record Task agent ID |
+
+## Usage
+
+```javascript
+// Start PRD execution
+ralph_start({ prdPath: "tasks/prd-feature.md" })
+
+// Check all status
+ralph_status()
+
+// Get single PRD details
+ralph_get({ branch: "ralph/prd-feature" })
+
+// Update US status (agent calls this after completing a story)
+ralph_update({ branch: "ralph/prd-feature", storyId: "US-1", passes: true, notes: "..." })
+
+// Merge completed PRD
+ralph_merge({ branch: "ralph/prd-feature" })
+```
+
+## PRD Format
+
+Ralph parses markdown PRD files with User Stories:
+
+```markdown
+# Feature Name
+
+## User Stories
+
+### US-1: Story Title
+
+**Acceptance Criteria:**
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+### US-2: Another Story
+...
+```
+
+## Conflict Resolution
+
+`ralph_merge` supports these strategies:
+
+| Strategy | Behavior |
+|----------|----------|
+| `auto_theirs` | `git merge -X theirs`, prefer main |
+| `auto_ours` | `git merge -X ours`, prefer branch |
+| `notify` | Pause, notify user to resolve manually |
+| `agent` | Launch merge subagent to resolve (default) |
+
+## Data Storage
+
+- State: `~/.ralph/state.json` (JSON file)
+- Logs: `~/.ralph/logs/`
+
+## License
+
+MIT

package/dist/db/client.d.ts

@@ -0,0 +1,7 @@
+import Database from "better-sqlite3";
+import * as schema from "./schema.js";
+declare const RALPH_DATA_DIR: string;
+export declare const db: import("drizzle-orm/better-sqlite3").BetterSQLite3Database<typeof schema> & {
+    $client: Database.Database;
+};
+export { RALPH_DATA_DIR };

package/dist/db/client.js

@@ -0,0 +1,55 @@
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { existsSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import * as schema from "./schema.js";
+const RALPH_DATA_DIR = process.env.RALPH_DATA_DIR?.replace("~", homedir()) ||
+    join(homedir(), ".ralph");
+// Ensure data directory exists
+if (!existsSync(RALPH_DATA_DIR)) {
+    mkdirSync(RALPH_DATA_DIR, { recursive: true });
+}
+const DB_PATH = join(RALPH_DATA_DIR, "state.db");
+const sqlite = new Database(DB_PATH);
+// Enable WAL mode for better concurrency
+sqlite.pragma("journal_mode = WAL");
+export const db = drizzle(sqlite, { schema });
+// Initialize tables
+sqlite.exec(`
+  CREATE TABLE IF NOT EXISTS executions (
+    id TEXT PRIMARY KEY,
+    project TEXT NOT NULL,
+    branch TEXT NOT NULL UNIQUE,
+    description TEXT NOT NULL,
+    prd_path TEXT NOT NULL,
+    project_root TEXT NOT NULL,
+    worktree_path TEXT,
+    status TEXT NOT NULL DEFAULT 'pending',
+    agent_task_id TEXT,
+    on_conflict TEXT DEFAULT 'agent',
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS user_stories (
+    id TEXT PRIMARY KEY,
+    execution_id TEXT NOT NULL REFERENCES executions(id) ON DELETE CASCADE,
+    story_id TEXT NOT NULL,
+    title TEXT NOT NULL,
+    description TEXT NOT NULL,
+    acceptance_criteria TEXT NOT NULL,
+    priority INTEGER NOT NULL,
+    passes INTEGER NOT NULL DEFAULT 0,
+    notes TEXT DEFAULT ''
+  );
+
+  CREATE TABLE IF NOT EXISTS merge_queue (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    execution_id TEXT NOT NULL REFERENCES executions(id) ON DELETE CASCADE,
+    position INTEGER NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    created_at INTEGER NOT NULL
+  );
+`);
+export { RALPH_DATA_DIR };