ralph-mcp 1.0.0

package/dist/utils/prd-parser.js

@@ -0,0 +1,137 @@
+import { readFileSync } from "fs";
+import matter from "gray-matter";
+/**
+ * Parse a PRD markdown file into structured data.
+ * Supports both markdown format and JSON format.
+ */
+export function parsePrdFile(filePath) {
+    const content = readFileSync(filePath, "utf-8");
+    // Check if it's JSON format
+    if (filePath.endsWith(".json")) {
+        return parsePrdJson(content);
+    }
+    return parsePrdMarkdown(content);
+}
+function parsePrdJson(content) {
+    const data = JSON.parse(content);
+    return {
+        title: data.description || data.title || "Untitled PRD",
+        description: data.description || "",
+        branchName: data.branchName || "ralph/unnamed",
+        userStories: (data.userStories || []).map((us, index) => ({
+            id: us.id || `US-${String(index + 1).padStart(3, "0")}`,
+            title: us.title || "",
+            description: us.description || "",
+            acceptanceCriteria: us.acceptanceCriteria || [],
+            priority: us.priority || index + 1,
+        })),
+    };
+}
+function parsePrdMarkdown(content) {
+    // Normalize line endings (CRLF -> LF)
+    content = content.replace(/\r\n/g, "\n");
+    const { data: frontmatter, content: body } = matter(content);
+    // Extract title from first H1 or frontmatter
+    const titleMatch = body.match(/^#\s+(.+)$/m);
+    const title = frontmatter.title || titleMatch?.[1] || "Untitled PRD";
+    // Extract branch name from frontmatter or generate from title
+    const branchName = frontmatter.branch ||
+        `ralph/${title.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+    // Extract description
+    const descMatch = body.match(/##\s*(?:Description|描述|Overview|概述)\s*\n([\s\S]*?)(?=\n##|\n$)/i);
+    const description = descMatch?.[1]?.trim() || title;
+    // Extract user stories
+    const userStories = extractUserStories(body);
+    return {
+        title,
+        description,
+        branchName,
+        userStories,
+    };
+}
+function extractUserStories(content) {
+    const stories = [];
+    // First, try to find the User Stories section
+    const userStoriesSection = content.match(/##\s*(?:User Stories|用户故事)\s*\n([\s\S]*?)(?=\n##[^#]|$)/i);
+    // Add leading newline to ensure pattern matches at start
+    const searchContent = userStoriesSection?.[1]
+        ? "\n" + userStoriesSection[1]
+        : content;
+    // Pattern 1: ### US-XXX: Title format (supports US-1, US-01, US-001)
+    const usPattern = /\n###\s*(US-\d+)[:\s]+(.+?)\n([\s\S]*?)(?=\n###\s*US-|\n##[^#]|$)/gi;
+    let match;
+    while ((match = usPattern.exec(searchContent)) !== null) {
+        const [, id, title, body] = match;
+        const story = parseUserStoryBody(id.toUpperCase(), title, body);
+        story.priority = stories.length + 1;
+        stories.push(story);
+    }
+    // Pattern 2: Numbered list with checkboxes (only if no US-XXX found)
+    if (stories.length === 0) {
+        const listPattern = /^\d+\.\s*\[[ x]\]\s*\*\*(.+?)\*\*[:\s]*([\s\S]*?)(?=\n\d+\.\s*\[|\n##|$)/gim;
+        let index = 0;
+        while ((match = listPattern.exec(searchContent)) !== null) {
+            const [, title, body] = match;
+            index++;
+            const id = `US-${String(index).padStart(3, "0")}`;
+            const story = parseUserStoryBody(id, title.trim(), body);
+            stories.push(story);
+        }
+    }
+    // Pattern 3: Simple numbered list (only in User Stories section, not entire content)
+    if (stories.length === 0 && userStoriesSection) {
+        const simplePattern = /^\d+\.\s*(.+?)(?:\n|$)/gm;
+        let index = 0;
+        while ((match = simplePattern.exec(userStoriesSection[1])) !== null) {
+            const [, title] = match;
+            if (title.trim() && !title.startsWith("#")) {
+                index++;
+                stories.push({
+                    id: `US-${String(index).padStart(3, "0")}`,
+                    title: title.trim(),
+                    description: "",
+                    acceptanceCriteria: [],
+                    priority: index,
+                });
+            }
+        }
+    }
+    return stories;
+}
+function parseUserStoryBody(id, title, body) {
+    // Extract description (As a... I want... So that...)
+    const descMatch = body.match(/As\s+a[n]?\s+.+?(?:,\s*)?I\s+want.+?(?:,\s*)?So\s+that.+?(?:\.|$)/is);
+    const description = descMatch?.[0]?.trim() || "";
+    // Extract acceptance criteria
+    const acMatch = body.match(/(?:Acceptance\s*Criteria|验收标准|AC)[:\s]*([\s\S]*?)(?=\n(?:Priority|优先级|Notes|备注)|$)/i);
+    const acContent = acMatch?.[1] || body;
+    const acceptanceCriteria = [];
+    const acPattern = /[-*]\s*(.+?)(?:\n|$)/g;
+    let acItem;
+    while ((acItem = acPattern.exec(acContent)) !== null) {
+        const criterion = acItem[1].trim();
+        if (criterion && !criterion.startsWith("As a")) {
+            acceptanceCriteria.push(criterion);
+        }
+    }
+    // Extract priority
+    const priorityMatch = body.match(/(?:Priority|优先级)[:\s]*(\d+)/i);
+    const priority = priorityMatch ? parseInt(priorityMatch[1], 10) : 1;
+    return {
+        id,
+        title: title.trim(),
+        description,
+        acceptanceCriteria,
+        priority,
+    };
+}
+/**
+ * Generate branch name from PRD title
+ */
+export function generateBranchName(title) {
+    return `ralph/${title
+        .toLowerCase()
+        .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 50)}`;
+}

package/dist/utils/worktree.d.ts

@@ -0,0 +1,34 @@
+export interface WorktreeInfo {
+    path: string;
+    branch: string;
+    commit: string;
+}
+/**
+ * Create a new git worktree for a branch
+ */
+export declare function createWorktree(projectRoot: string, branch: string): Promise<string>;
+/**
+ * Remove a git worktree
+ */
+export declare function removeWorktree(projectRoot: string, worktreePath: string): Promise<void>;
+/**
+ * List all worktrees
+ */
+export declare function listWorktrees(projectRoot: string): WorktreeInfo[];
+/**
+ * Merge a branch into main
+ */
+export declare function mergeBranch(projectRoot: string, branch: string, description: string, onConflict?: "auto_theirs" | "auto_ours" | "notify" | "agent"): Promise<{
+    success: boolean;
+    commitHash?: string;
+    hasConflicts: boolean;
+    conflictFiles?: string[];
+}>;
+/**
+ * Abort a merge in progress
+ */
+export declare function abortMerge(projectRoot: string): Promise<void>;
+/**
+ * Get list of conflict files
+ */
+export declare function getConflictFiles(projectRoot: string): Promise<string[]>;

package/dist/utils/worktree.js

@@ -0,0 +1,136 @@
+import { execSync, exec } from "child_process";
+import { existsSync } from "fs";
+import { join } from "path";
+import { promisify } from "util";
+const execAsync = promisify(exec);
+/**
+ * Create a new git worktree for a branch
+ */
+export async function createWorktree(projectRoot, branch) {
+    // Extract short name from branch (ralph/task1-agent -> task1-agent)
+    const shortName = branch.replace(/^ralph\//, "");
+    const worktreePath = join(projectRoot, ".tmp", "worktrees", `ralph-${shortName}`);
+    // Check if worktree already exists
+    if (existsSync(worktreePath)) {
+        console.log(`Worktree already exists at ${worktreePath}`);
+        return worktreePath;
+    }
+    // Check if branch exists
+    const branchExists = await checkBranchExists(projectRoot, branch);
+    if (branchExists) {
+        // Worktree for existing branch
+        await execAsync(`git worktree add "${worktreePath}" "${branch}"`, { cwd: projectRoot });
+    }
+    else {
+        // Create new branch from main
+        await execAsync(`git worktree add -b "${branch}" "${worktreePath}" main`, { cwd: projectRoot });
+    }
+    return worktreePath;
+}
+/**
+ * Remove a git worktree
+ */
+export async function removeWorktree(projectRoot, worktreePath) {
+    if (!existsSync(worktreePath)) {
+        console.log(`Worktree does not exist at ${worktreePath}`);
+        return;
+    }
+    await execAsync(`git worktree remove "${worktreePath}" --force`, {
+        cwd: projectRoot,
+    });
+}
+/**
+ * List all worktrees
+ */
+export function listWorktrees(projectRoot) {
+    const output = execSync("git worktree list --porcelain", {
+        cwd: projectRoot,
+        encoding: "utf-8",
+    });
+    const worktrees = [];
+    const entries = output.split("\n\n").filter(Boolean);
+    for (const entry of entries) {
+        const lines = entry.split("\n");
+        const pathLine = lines.find((l) => l.startsWith("worktree "));
+        const commitLine = lines.find((l) => l.startsWith("HEAD "));
+        const branchLine = lines.find((l) => l.startsWith("branch "));
+        if (pathLine) {
+            worktrees.push({
+                path: pathLine.replace("worktree ", ""),
+                commit: commitLine?.replace("HEAD ", "") || "",
+                branch: branchLine?.replace("branch refs/heads/", "") || "",
+            });
+        }
+    }
+    return worktrees;
+}
+/**
+ * Check if a branch exists
+ */
+async function checkBranchExists(projectRoot, branch) {
+    try {
+        await execAsync(`git rev-parse --verify "${branch}"`, { cwd: projectRoot });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Merge a branch into main
+ */
+export async function mergeBranch(projectRoot, branch, description, onConflict = "agent") {
+    // Checkout main and pull
+    await execAsync("git checkout main && git pull", { cwd: projectRoot });
+    // Try to merge
+    let mergeStrategy = "";
+    if (onConflict === "auto_theirs") {
+        mergeStrategy = "-X theirs";
+    }
+    else if (onConflict === "auto_ours") {
+        mergeStrategy = "-X ours";
+    }
+    try {
+        const { stdout } = await execAsync(`git merge --no-ff ${mergeStrategy} "${branch}" -m "merge: ${branch} - ${description}"`, { cwd: projectRoot });
+        // Get commit hash
+        const { stdout: hash } = await execAsync("git rev-parse HEAD", {
+            cwd: projectRoot,
+        });
+        return {
+            success: true,
+            commitHash: hash.trim(),
+            hasConflicts: false,
+        };
+    }
+    catch (error) {
+        // Check for conflicts
+        const { stdout: status } = await execAsync("git status --porcelain", {
+            cwd: projectRoot,
+        });
+        const conflictFiles = status
+            .split("\n")
+            .filter((line) => line.startsWith("UU ") || line.startsWith("AA "))
+            .map((line) => line.slice(3));
+        if (conflictFiles.length > 0) {
+            return {
+                success: false,
+                hasConflicts: true,
+                conflictFiles,
+            };
+        }
+        throw error;
+    }
+}
+/**
+ * Abort a merge in progress
+ */
+export async function abortMerge(projectRoot) {
+    await execAsync("git merge --abort", { cwd: projectRoot });
+}
+/**
+ * Get list of conflict files
+ */
+export async function getConflictFiles(projectRoot) {
+    const { stdout } = await execAsync("git diff --name-only --diff-filter=U", { cwd: projectRoot });
+    return stdout.split("\n").filter(Boolean);
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "ralph-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for autonomous PRD execution with Claude Code. Git worktree isolation, progress tracking, auto-merge.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ralph-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "claude-code",
+    "prd",
+    "ai-agent",
+    "autonomous",
+    "git-worktree"
+  ],
+  "author": "G0d2i11a",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/G0d2i11a/ralph-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/G0d2i11a/ralph-mcp/issues"
+  },
+  "homepage": "https://github.com/G0d2i11a/ralph-mcp#readme",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "gray-matter": "^4.0.3",
+    "node-notifier": "^10.0.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@types/node-notifier": "^8.0.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}