ralph-mcp 1.0.0

package/dist/index.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { start, startInputSchema } from "./tools/start.js";
+import { status, statusInputSchema } from "./tools/status.js";
+import { get, getInputSchema } from "./tools/get.js";
+import { update, updateInputSchema } from "./tools/update.js";
+import { stop, stopInputSchema } from "./tools/stop.js";
+import { merge, mergeInputSchema, mergeQueueAction, mergeQueueInputSchema } from "./tools/merge.js";
+import { setAgentId, setAgentIdInputSchema } from "./tools/set-agent-id.js";
+const server = new Server({
+    name: "ralph",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "ralph_start",
+                description: "Start PRD execution. Parses PRD file, creates worktree, stores state, and returns agent prompt for auto-start.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        prdPath: {
+                            type: "string",
+                            description: "Path to the PRD markdown file (e.g., tasks/prd-xxx.md)",
+                        },
+                        projectRoot: {
+                            type: "string",
+                            description: "Project root directory (defaults to cwd)",
+                        },
+                        worktree: {
+                            type: "boolean",
+                            description: "Create a worktree for isolation (default: true)",
+                            default: true,
+                        },
+                        autoStart: {
+                            type: "boolean",
+                            description: "Generate agent prompt for auto-start (default: true)",
+                            default: true,
+                        },
+                        autoMerge: {
+                            type: "boolean",
+                            description: "Auto add to merge queue when all stories pass (default: false)",
+                            default: false,
+                        },
+                        notifyOnComplete: {
+                            type: "boolean",
+                            description: "Show Windows notification when all stories complete (default: true)",
+                            default: true,
+                        },
+                        onConflict: {
+                            type: "string",
+                            enum: ["auto_theirs", "auto_ours", "notify", "agent"],
+                            description: "Conflict resolution strategy for merge (default: agent)",
+                            default: "agent",
+                        },
+                    },
+                    required: ["prdPath"],
+                },
+            },
+            {
+                name: "ralph_status",
+                description: "View all PRD execution status. Replaces manual TaskOutput queries. Shows progress, status, and summary.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project: {
+                            type: "string",
+                            description: "Filter by project name",
+                        },
+                        status: {
+                            type: "string",
+                            enum: ["pending", "running", "completed", "failed", "stopped", "merging"],
+                            description: "Filter by status",
+                        },
+                    },
+                },
+            },
+            {
+                name: "ralph_get",
+                description: "Get detailed status of a single PRD execution including all user stories.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        branch: {
+                            type: "string",
+                            description: "Branch name (e.g., ralph/task1-agent)",
+                        },
+                    },
+                    required: ["branch"],
+                },
+            },
+            {
+                name: "ralph_update",
+                description: "Update User Story status. Called by subagent after completing a story.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        branch: {
+                            type: "string",
+                            description: "Branch name (e.g., ralph/task1-agent)",
+                        },
+                        storyId: {
+                            type: "string",
+                            description: "Story ID (e.g., US-001)",
+                        },
+                        passes: {
+                            type: "boolean",
+                            description: "Whether the story passes",
+                        },
+                        notes: {
+                            type: "string",
+                            description: "Implementation notes",
+                        },
+                    },
+                    required: ["branch", "storyId", "passes"],
+                },
+            },
+            {
+                name: "ralph_stop",
+                description: "Stop PRD execution. Optionally clean up worktree.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        branch: {
+                            type: "string",
+                            description: "Branch name to stop",
+                        },
+                        cleanup: {
+                            type: "boolean",
+                            description: "Also remove the worktree (default: false)",
+                            default: false,
+                        },
+                        deleteRecord: {
+                            type: "boolean",
+                            description: "Delete the execution record from database (default: false)",
+                            default: false,
+                        },
+                    },
+                    required: ["branch"],
+                },
+            },
+            {
+                name: "ralph_merge",
+                description: "Merge completed PRD to main and clean up worktree. MCP executes directly without Claude context.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        branch: {
+                            type: "string",
+                            description: "Branch name to merge",
+                        },
+                        force: {
+                            type: "boolean",
+                            description: "Skip verification checks (default: false)",
+                            default: false,
+                        },
+                        onConflict: {
+                            type: "string",
+                            enum: ["auto_theirs", "auto_ours", "notify", "agent"],
+                            description: "Override conflict resolution strategy",
+                        },
+                    },
+                    required: ["branch"],
+                },
+            },
+            {
+                name: "ralph_merge_queue",
+                description: "Manage merge queue. Default serial merge to avoid conflicts.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        action: {
+                            type: "string",
+                            enum: ["list", "add", "remove", "process"],
+                            description: "Queue action (default: list)",
+                            default: "list",
+                        },
+                        branch: {
+                            type: "string",
+                            description: "Branch for add/remove actions",
+                        },
+                    },
+                },
+            },
+            {
+                name: "ralph_set_agent_id",
+                description: "Record the Claude Task agent ID for an execution. Called after starting a Task agent.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        branch: {
+                            type: "string",
+                            description: "Branch name",
+                        },
+                        agentTaskId: {
+                            type: "string",
+                            description: "Claude Task agent ID",
+                        },
+                    },
+                    required: ["branch", "agentTaskId"],
+                },
+            },
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let result;
+        switch (name) {
+            case "ralph_start":
+                result = await start(startInputSchema.parse(args));
+                break;
+            case "ralph_status":
+                result = await status(statusInputSchema.parse(args || {}));
+                break;
+            case "ralph_get":
+                result = await get(getInputSchema.parse(args));
+                break;
+            case "ralph_update":
+                result = await update(updateInputSchema.parse(args));
+                break;
+            case "ralph_stop":
+                result = await stop(stopInputSchema.parse(args));
+                break;
+            case "ralph_merge":
+                result = await merge(mergeInputSchema.parse(args));
+                break;
+            case "ralph_merge_queue":
+                result = await mergeQueueAction(mergeQueueInputSchema.parse(args || {}));
+                break;
+            case "ralph_set_agent_id":
+                result = await setAgentId(setAgentIdInputSchema.parse(args));
+                break;
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: message }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Ralph MCP Server started");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/store/state.d.ts

@@ -0,0 +1,55 @@
+export declare const RALPH_DATA_DIR: string;
+export type ExecutionStatus = "pending" | "running" | "completed" | "failed" | "stopped" | "merging";
+export type ConflictStrategy = "auto_theirs" | "auto_ours" | "notify" | "agent";
+export interface ExecutionRecord {
+    id: string;
+    project: string;
+    branch: string;
+    description: string;
+    prdPath: string;
+    projectRoot: string;
+    worktreePath: string | null;
+    status: ExecutionStatus;
+    agentTaskId: string | null;
+    onConflict: ConflictStrategy | null;
+    autoMerge: boolean;
+    notifyOnComplete: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface UserStoryRecord {
+    id: string;
+    executionId: string;
+    storyId: string;
+    title: string;
+    description: string;
+    acceptanceCriteria: string[];
+    priority: number;
+    passes: boolean;
+    notes: string;
+}
+export type MergeQueueStatus = "pending" | "merging" | "completed" | "failed";
+export interface MergeQueueItem {
+    id: number;
+    executionId: string;
+    position: number;
+    status: MergeQueueStatus;
+    createdAt: Date;
+}
+export declare function listExecutions(): Promise<ExecutionRecord[]>;
+export declare function findExecutionByBranch(branch: string): Promise<ExecutionRecord | null>;
+export declare function findExecutionById(executionId: string): Promise<ExecutionRecord | null>;
+export declare function insertExecution(execution: ExecutionRecord): Promise<void>;
+export declare function updateExecution(executionId: string, patch: Partial<Omit<ExecutionRecord, "id" | "createdAt">> & {
+    updatedAt?: Date;
+}): Promise<void>;
+export declare function deleteExecution(executionId: string): Promise<void>;
+export declare function listUserStoriesByExecutionId(executionId: string): Promise<UserStoryRecord[]>;
+export declare function findUserStoryById(storyKey: string): Promise<UserStoryRecord | null>;
+export declare function insertUserStories(stories: UserStoryRecord[]): Promise<void>;
+export declare function updateUserStory(storyKey: string, patch: Partial<Omit<UserStoryRecord, "id" | "executionId" | "storyId">>): Promise<void>;
+export declare function listMergeQueue(): Promise<MergeQueueItem[]>;
+export declare function findMergeQueueItemByExecutionId(executionId: string): Promise<MergeQueueItem | null>;
+export declare function insertMergeQueueItem(item: Omit<MergeQueueItem, "id">): Promise<MergeQueueItem>;
+export declare function updateMergeQueueItem(id: number, patch: Partial<Omit<MergeQueueItem, "id" | "executionId" | "createdAt">>): Promise<void>;
+export declare function deleteMergeQueueByExecutionId(executionId: string): Promise<void>;

package/dist/store/state.js

@@ -0,0 +1,205 @@
+import { existsSync, mkdirSync } from "fs";
+import { readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+export const RALPH_DATA_DIR = process.env.RALPH_DATA_DIR?.replace("~", homedir()) ||
+    join(homedir(), ".ralph");
+const STATE_PATH = join(RALPH_DATA_DIR, "state.json");
+if (!existsSync(RALPH_DATA_DIR)) {
+    mkdirSync(RALPH_DATA_DIR, { recursive: true });
+}
+function parseDate(value, fieldName) {
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new Error(`Invalid date in ${fieldName}: ${value}`);
+    }
+    return date;
+}
+function toIso(date) {
+    return date.toISOString();
+}
+function defaultState() {
+    return { executions: [], userStories: [], mergeQueue: [] };
+}
+function normalizeState(raw) {
+    const base = {
+        version: 1,
+        executions: [],
+        userStories: [],
+        mergeQueue: [],
+    };
+    if (!raw || typeof raw !== "object")
+        return base;
+    const obj = raw;
+    if (obj.version === 1)
+        base.version = 1;
+    if (Array.isArray(obj.executions))
+        base.executions = obj.executions;
+    if (Array.isArray(obj.userStories))
+        base.userStories = obj.userStories;
+    if (Array.isArray(obj.mergeQueue))
+        base.mergeQueue = obj.mergeQueue;
+    return base;
+}
+function deserializeState(file) {
+    return {
+        executions: file.executions.map((e) => ({
+            ...e,
+            createdAt: parseDate(e.createdAt, "executions.createdAt"),
+            updatedAt: parseDate(e.updatedAt, "executions.updatedAt"),
+        })),
+        userStories: file.userStories.map((s) => ({
+            ...s,
+            acceptanceCriteria: Array.isArray(s.acceptanceCriteria)
+                ? s.acceptanceCriteria
+                : [],
+            notes: typeof s.notes === "string" ? s.notes : "",
+        })),
+        mergeQueue: file.mergeQueue.map((q) => ({
+            ...q,
+            createdAt: parseDate(q.createdAt, "mergeQueue.createdAt"),
+        })),
+    };
+}
+function serializeState(state) {
+    return {
+        version: 1,
+        executions: state.executions.map((e) => ({
+            ...e,
+            createdAt: toIso(e.createdAt),
+            updatedAt: toIso(e.updatedAt),
+        })),
+        userStories: state.userStories,
+        mergeQueue: state.mergeQueue.map((q) => ({
+            ...q,
+            createdAt: toIso(q.createdAt),
+        })),
+    };
+}
+let lock = Promise.resolve();
+async function withLock(fn) {
+    const previous = lock;
+    let release;
+    lock = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous;
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+    }
+}
+async function readStateUnlocked() {
+    if (!existsSync(STATE_PATH))
+        return defaultState();
+    const rawText = await readFile(STATE_PATH, "utf-8");
+    const rawJson = JSON.parse(rawText);
+    const normalized = normalizeState(rawJson);
+    return deserializeState(normalized);
+}
+async function writeStateUnlocked(state) {
+    const file = serializeState(state);
+    await writeFile(STATE_PATH, JSON.stringify(file, null, 2) + "\n", "utf-8");
+}
+async function mutateState(mutator) {
+    return withLock(async () => {
+        const state = await readStateUnlocked();
+        const result = await mutator(state);
+        await writeStateUnlocked(state);
+        return result;
+    });
+}
+async function readState(reader) {
+    return withLock(async () => {
+        const state = await readStateUnlocked();
+        return await reader(state);
+    });
+}
+export async function listExecutions() {
+    return readState((s) => s.executions.slice());
+}
+export async function findExecutionByBranch(branch) {
+    return readState((s) => s.executions.find((e) => e.branch === branch) ?? null);
+}
+export async function findExecutionById(executionId) {
+    return readState((s) => s.executions.find((e) => e.id === executionId) ?? null);
+}
+export async function insertExecution(execution) {
+    return mutateState((s) => {
+        const existing = s.executions.find((e) => e.branch === execution.branch);
+        if (existing) {
+            throw new Error(`Execution already exists for branch ${execution.branch}`);
+        }
+        s.executions.push(execution);
+    });
+}
+export async function updateExecution(executionId, patch) {
+    return mutateState((s) => {
+        const exec = s.executions.find((e) => e.id === executionId);
+        if (!exec)
+            throw new Error(`No execution found with id: ${executionId}`);
+        Object.assign(exec, patch);
+    });
+}
+export async function deleteExecution(executionId) {
+    return mutateState((s) => {
+        s.executions = s.executions.filter((e) => e.id !== executionId);
+        s.userStories = s.userStories.filter((st) => st.executionId !== executionId);
+        s.mergeQueue = s.mergeQueue.filter((q) => q.executionId !== executionId);
+    });
+}
+export async function listUserStoriesByExecutionId(executionId) {
+    return readState((s) => s.userStories.filter((st) => st.executionId === executionId));
+}
+export async function findUserStoryById(storyKey) {
+    return readState((s) => s.userStories.find((st) => st.id === storyKey) ?? null);
+}
+export async function insertUserStories(stories) {
+    return mutateState((s) => {
+        for (const story of stories) {
+            const existingIndex = s.userStories.findIndex((st) => st.id === story.id);
+            if (existingIndex >= 0)
+                s.userStories.splice(existingIndex, 1);
+            s.userStories.push(story);
+        }
+    });
+}
+export async function updateUserStory(storyKey, patch) {
+    return mutateState((s) => {
+        const story = s.userStories.find((st) => st.id === storyKey);
+        if (!story)
+            throw new Error(`No story found with id: ${storyKey}`);
+        Object.assign(story, patch);
+    });
+}
+export async function listMergeQueue() {
+    return readState((s) => s.mergeQueue
+        .slice()
+        .sort((a, b) => a.position - b.position || a.id - b.id));
+}
+export async function findMergeQueueItemByExecutionId(executionId) {
+    return readState((s) => s.mergeQueue.find((q) => q.executionId === executionId) ?? null);
+}
+export async function insertMergeQueueItem(item) {
+    return mutateState((s) => {
+        const nextId = s.mergeQueue.reduce((maxId, q) => Math.max(maxId, q.id), 0) + 1;
+        const created = { ...item, id: nextId };
+        s.mergeQueue.push(created);
+        return created;
+    });
+}
+export async function updateMergeQueueItem(id, patch) {
+    return mutateState((s) => {
+        const item = s.mergeQueue.find((q) => q.id === id);
+        if (!item)
+            throw new Error(`No merge queue item found with id: ${id}`);
+        Object.assign(item, patch);
+    });
+}
+export async function deleteMergeQueueByExecutionId(executionId) {
+    return mutateState((s) => {
+        s.mergeQueue = s.mergeQueue.filter((q) => q.executionId !== executionId);
+    });
+}

package/dist/tools/get.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+export declare const getInputSchema: z.ZodObject<{
+    branch: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    branch: string;
+}, {
+    branch: string;
+}>;
+export type GetInput = z.infer<typeof getInputSchema>;
+export interface GetResult {
+    execution: {
+        id: string;
+        project: string;
+        branch: string;
+        description: string;
+        prdPath: string;
+        projectRoot: string;
+        worktreePath: string | null;
+        status: string;
+        agentTaskId: string | null;
+        onConflict: string | null;
+        createdAt: string;
+        updatedAt: string;
+    };
+    stories: Array<{
+        storyId: string;
+        title: string;
+        description: string;
+        acceptanceCriteria: string[];
+        priority: number;
+        passes: boolean;
+        notes: string | null;
+    }>;
+    progress: {
+        completed: number;
+        total: number;
+        percentage: number;
+    };
+}
+export declare function get(input: GetInput): Promise<GetResult>;

package/dist/tools/get.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { findExecutionByBranch, listUserStoriesByExecutionId, } from "../store/state.js";
+export const getInputSchema = z.object({
+    branch: z.string().describe("Branch name (e.g., ralph/task1-agent)"),
+});
+export async function get(input) {
+    // Find execution by branch
+    const exec = await findExecutionByBranch(input.branch);
+    if (!exec) {
+        throw new Error(`No execution found for branch: ${input.branch}`);
+    }
+    // Get stories
+    const stories = await listUserStoriesByExecutionId(exec.id);
+    // Sort by priority
+    stories.sort((a, b) => a.priority - b.priority);
+    const completed = stories.filter((s) => s.passes).length;
+    const total = stories.length;
+    return {
+        execution: {
+            id: exec.id,
+            project: exec.project,
+            branch: exec.branch,
+            description: exec.description,
+            prdPath: exec.prdPath,
+            projectRoot: exec.projectRoot,
+            worktreePath: exec.worktreePath,
+            status: exec.status,
+            agentTaskId: exec.agentTaskId,
+            onConflict: exec.onConflict,
+            createdAt: exec.createdAt.toISOString(),
+            updatedAt: exec.updatedAt.toISOString(),
+        },
+        stories: stories.map((s) => ({
+            storyId: s.storyId,
+            title: s.title,
+            description: s.description,
+            acceptanceCriteria: s.acceptanceCriteria,
+            priority: s.priority,
+            passes: s.passes,
+            notes: s.notes,
+        })),
+        progress: {
+            completed,
+            total,
+            percentage: total > 0 ? Math.round((completed / total) * 100) : 0,
+        },
+    };
+}

package/dist/tools/merge.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+export declare const mergeInputSchema: z.ZodObject<{
+    branch: z.ZodString;
+    force: z.ZodDefault<z.ZodBoolean>;
+    skipQualityChecks: z.ZodDefault<z.ZodBoolean>;
+    onConflict: z.ZodOptional<z.ZodEnum<["auto_theirs", "auto_ours", "notify", "agent"]>>;
+}, "strip", z.ZodTypeAny, {
+    branch: string;
+    force: boolean;
+    skipQualityChecks: boolean;
+    onConflict?: "auto_theirs" | "auto_ours" | "notify" | "agent" | undefined;
+}, {
+    branch: string;
+    onConflict?: "auto_theirs" | "auto_ours" | "notify" | "agent" | undefined;
+    force?: boolean | undefined;
+    skipQualityChecks?: boolean | undefined;
+}>;
+export type MergeInput = z.infer<typeof mergeInputSchema>;
+export interface MergeResult {
+    success: boolean;
+    branch: string;
+    commitHash?: string;
+    cleanedUp: boolean;
+    conflictResolution?: "auto" | "agent" | "pending";
+    qualityChecks?: {
+        typeCheck: boolean;
+        build: boolean;
+    };
+    docsUpdated?: string[];
+    mergedStories?: string[];
+    message: string;
+}
+export declare function merge(input: MergeInput): Promise<MergeResult>;
+export declare const mergeQueueInputSchema: z.ZodObject<{
+    action: z.ZodDefault<z.ZodEnum<["list", "add", "remove", "process"]>>;
+    branch: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    action: "list" | "add" | "remove" | "process";
+    branch?: string | undefined;
+}, {
+    branch?: string | undefined;
+    action?: "list" | "add" | "remove" | "process" | undefined;
+}>;
+export type MergeQueueInput = z.infer<typeof mergeQueueInputSchema>;
+export interface MergeQueueResult {
+    queue: string[];
+    current?: string;
+    message: string;
+}
+export declare function mergeQueueAction(input: MergeQueueInput): Promise<MergeQueueResult>;