ralph-hero-mcp-server 1.3.3 → 2.4.6

package/dist/lib/workflow-states.js

@@ -38,6 +38,21 @@ export const HUMAN_STATES = [
     "Human Needed",
     "Plan in Review",
 ];
+/**
+ * Gate states that trigger parent advancement when ALL children reach them.
+ * Intermediate "in progress" states should NOT advance the parent.
+ */
+export const PARENT_GATE_STATES = [
+    "Ready for Plan",
+    "In Review",
+    "Done",
+];
+/**
+ * Check if a state is a parent advancement gate.
+ */
+export function isParentGateState(state) {
+    return PARENT_GATE_STATES.includes(state);
+}
 /**
  * Valid workflow states for the project (all known states).
  */

package/dist/tools/project-management-tools.js

@@ -6,7 +6,12 @@
  */
 import { z } from "zod";
 import { toolSuccess, toolError } from "../types.js";
-import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, resolveFullConfig, } from "../lib/helpers.js";
+import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, resolveFullConfig, updateProjectItemField, } from "../lib/helpers.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Fields that Ralph depends on — delete_field refuses to remove these. */
+export const PROTECTED_FIELDS = ["Workflow State", "Priority", "Estimate", "Status"];
 // ---------------------------------------------------------------------------
 // Register project management tools
 // ---------------------------------------------------------------------------
@@ -244,5 +249,352 @@ export function registerProjectManagementTools(server, client, fieldCache) {
             return toolError(`Failed to clear field: ${message}`);
         }
     });
+    // -------------------------------------------------------------------------
+    // ralph_hero__create_draft_issue
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__create_draft_issue", "Create a draft issue in the project (no repo required). Optionally set workflow state, priority, and estimate after creation. Returns: projectItemId, title, fieldsSet.", {
+        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
+        repo: z.string().optional().describe("Repository name. Defaults to env var"),
+        title: z.string().describe("Draft issue title"),
+        body: z.string().optional().describe("Draft issue body (markdown)"),
+        workflowState: z.string().optional().describe("Workflow state to set after creation"),
+        priority: z.string().optional().describe("Priority to set after creation"),
+        estimate: z.string().optional().describe("Estimate to set after creation"),
+    }, async (args) => {
+        try {
+            const { projectNumber, projectOwner } = resolveFullConfig(client, args);
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            const projectId = fieldCache.getProjectId();
+            if (!projectId) {
+                return toolError("Could not resolve project ID");
+            }
+            const result = await client.projectMutate(`mutation($projectId: ID!, $title: String!, $body: String) {
+            addProjectV2DraftIssue(input: {
+              projectId: $projectId,
+              title: $title,
+              body: $body
+            }) {
+              projectItem { id }
+            }
+          }`, { projectId, title: args.title, body: args.body });
+            const projectItemId = result.addProjectV2DraftIssue.projectItem.id;
+            const fieldsSet = [];
+            if (args.workflowState) {
+                await updateProjectItemField(client, fieldCache, projectItemId, "Workflow State", args.workflowState);
+                fieldsSet.push("Workflow State");
+            }
+            if (args.priority) {
+                await updateProjectItemField(client, fieldCache, projectItemId, "Priority", args.priority);
+                fieldsSet.push("Priority");
+            }
+            if (args.estimate) {
+                await updateProjectItemField(client, fieldCache, projectItemId, "Estimate", args.estimate);
+                fieldsSet.push("Estimate");
+            }
+            return toolSuccess({
+                projectItemId,
+                title: args.title,
+                fieldsSet,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to create draft issue: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // ralph_hero__update_draft_issue
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__update_draft_issue", "Update title and/or body of an existing draft issue. Requires the draft issue content node ID (DI_...), not the project item ID. Returns: draftIssueId, updated.", {
+        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
+        repo: z.string().optional().describe("Repository name. Defaults to env var"),
+        draftIssueId: z.string().describe("Draft issue content node ID (DI_...)"),
+        title: z.string().optional().describe("New title"),
+        body: z.string().optional().describe("New body (markdown)"),
+    }, async (args) => {
+        try {
+            if (!args.title && args.body === undefined) {
+                return toolError("At least one of title or body must be provided");
+            }
+            const { projectNumber, projectOwner } = resolveFullConfig(client, args);
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            const vars = { draftIssueId: args.draftIssueId };
+            if (args.title !== undefined)
+                vars.title = args.title;
+            if (args.body !== undefined)
+                vars.body = args.body;
+            await client.projectMutate(`mutation($draftIssueId: ID!, $title: String, $body: String) {
+            updateProjectV2DraftIssue(input: {
+              draftIssueId: $draftIssueId,
+              title: $title,
+              body: $body
+            }) {
+              projectItem { id }
+            }
+          }`, vars);
+            return toolSuccess({
+                draftIssueId: args.draftIssueId,
+                updated: true,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to update draft issue: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // ralph_hero__reorder_item
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__reorder_item", "Set item position within project views. Moves an issue before or after another item. Omit afterNumber to move to the top. Returns: number, position.", {
+        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
+        repo: z.string().optional().describe("Repository name. Defaults to env var"),
+        number: z.number().describe("Issue number to reposition"),
+        afterNumber: z.number().optional()
+            .describe("Issue number to place after; omit to move to top"),
+    }, async (args) => {
+        try {
+            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            const projectId = fieldCache.getProjectId();
+            if (!projectId) {
+                return toolError("Could not resolve project ID");
+            }
+            const itemId = await resolveProjectItemId(client, fieldCache, owner, repo, args.number);
+            let afterId;
+            if (args.afterNumber !== undefined) {
+                afterId = await resolveProjectItemId(client, fieldCache, owner, repo, args.afterNumber);
+            }
+            await client.projectMutate(`mutation($projectId: ID!, $itemId: ID!, $afterId: ID) {
+            updateProjectV2ItemPosition(input: {
+              projectId: $projectId,
+              itemId: $itemId,
+              afterId: $afterId
+            }) {
+              items(first: 1) { nodes { id } }
+            }
+          }`, { projectId, itemId, afterId: afterId ?? null });
+            return toolSuccess({
+                number: args.number,
+                position: args.afterNumber ? `after #${args.afterNumber}` : "top",
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to reorder item: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // ralph_hero__update_project
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__update_project", "Update project settings — title, description, README, visibility, open/closed state. At least one field must be provided. Returns: projectId, updated, fields.", {
+        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
+        repo: z.string().optional().describe("Repository name. Defaults to env var"),
+        title: z.string().optional().describe("New project title"),
+        shortDescription: z.string().optional().describe("Short summary for listings"),
+        readme: z.string().optional().describe("Full README in markdown"),
+        public: z.boolean().optional().describe("Visibility (true=public, false=private)"),
+        closed: z.boolean().optional().describe("Close (true) or reopen (false) the project"),
+    }, async (args) => {
+        try {
+            const updatedFields = [];
+            const vars = {};
+            const varDefs = ["$projectId: ID!"];
+            const inputFields = ["projectId: $projectId"];
+            if (args.title !== undefined) {
+                vars.updateTitle = args.title;
+                varDefs.push("$updateTitle: String");
+                inputFields.push("title: $updateTitle");
+                updatedFields.push("title");
+            }
+            if (args.shortDescription !== undefined) {
+                vars.shortDescription = args.shortDescription;
+                varDefs.push("$shortDescription: String");
+                inputFields.push("shortDescription: $shortDescription");
+                updatedFields.push("shortDescription");
+            }
+            if (args.readme !== undefined) {
+                vars.updateReadme = args.readme;
+                varDefs.push("$updateReadme: String");
+                inputFields.push("readme: $updateReadme");
+                updatedFields.push("readme");
+            }
+            if (args.public !== undefined) {
+                vars.publicVisibility = args.public;
+                varDefs.push("$publicVisibility: Boolean");
+                inputFields.push("public: $publicVisibility");
+                updatedFields.push("public");
+            }
+            if (args.closed !== undefined) {
+                vars.closedState = args.closed;
+                varDefs.push("$closedState: Boolean");
+                inputFields.push("closed: $closedState");
+                updatedFields.push("closed");
+            }
+            if (updatedFields.length === 0) {
+                return toolError("At least one field to update must be provided");
+            }
+            const { projectNumber, projectOwner } = resolveFullConfig(client, args);
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            const projectId = fieldCache.getProjectId();
+            if (!projectId) {
+                return toolError("Could not resolve project ID");
+            }
+            vars.projectId = projectId;
+            await client.projectMutate(`mutation(${varDefs.join(", ")}) {
+            updateProjectV2(input: {
+              ${inputFields.join(",\n              ")}
+            }) {
+              projectV2 { id title }
+            }
+          }`, vars);
+            return toolSuccess({
+                projectId,
+                updated: true,
+                fields: updatedFields,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to update project: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // ralph_hero__delete_field
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__delete_field", "Delete a custom field from the project. Refuses to delete Ralph's required fields (Workflow State, Priority, Estimate, Status). Defaults to dry-run; set confirm=true to execute. Returns: field, deleted or action.", {
+        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
+        repo: z.string().optional().describe("Repository name. Defaults to env var"),
+        field: z.string().describe("Name of the field to delete"),
+        confirm: z.boolean().optional().default(false)
+            .describe("Must be true to execute deletion; false for dry-run"),
+    }, async (args) => {
+        try {
+            if (PROTECTED_FIELDS.includes(args.field)) {
+                return toolError(`Cannot delete protected field "${args.field}". ` +
+                    `Protected fields: ${PROTECTED_FIELDS.join(", ")}`);
+            }
+            const { projectNumber, projectOwner } = resolveFullConfig(client, args);
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            const projectId = fieldCache.getProjectId();
+            if (!projectId) {
+                return toolError("Could not resolve project ID");
+            }
+            const fieldId = fieldCache.getFieldId(args.field);
+            if (!fieldId) {
+                const validFields = fieldCache.getFieldNames();
+                return toolError(`Field "${args.field}" not found in project. ` +
+                    `Valid fields: ${validFields.join(", ")}`);
+            }
+            if (!args.confirm) {
+                return toolSuccess({
+                    field: args.field,
+                    fieldId,
+                    action: "would_delete",
+                    confirm: false,
+                    message: "Dry run. Set confirm=true to delete.",
+                });
+            }
+            await client.projectMutate(`mutation($projectId: ID!, $fieldId: ID!) {
+            deleteProjectV2Field(input: {
+              projectId: $projectId,
+              fieldId: $fieldId
+            }) {
+              projectV2Field {
+                ... on ProjectV2SingleSelectField { id name }
+                ... on ProjectV2Field { id name }
+              }
+            }
+          }`, { projectId, fieldId });
+            // Invalidate field cache since a field definition was removed
+            fieldCache.clear();
+            return toolSuccess({
+                field: args.field,
+                deleted: true,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to delete field: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // ralph_hero__update_collaborators
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__update_collaborators", "Manage project collaborator access — add, update, or remove users/teams. Each entry needs exactly one of username or teamSlug. Team collaborators require an org-owned project. Returns: updated, collaboratorCount.", {
+        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
+        repo: z.string().optional().describe("Repository name. Defaults to env var"),
+        collaborators: z.array(z.object({
+            username: z.string().optional().describe("GitHub username"),
+            teamSlug: z.string().optional().describe("Team slug (org projects only)"),
+            role: z.enum(["READER", "WRITER", "ADMIN", "NONE"])
+                .describe("Permission level (NONE removes access)"),
+        })).describe("List of collaborator changes"),
+    }, async (args) => {
+        try {
+            if (args.collaborators.length === 0) {
+                return toolError("At least one collaborator entry must be provided");
+            }
+            const { projectNumber, projectOwner } = resolveFullConfig(client, args);
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            const projectId = fieldCache.getProjectId();
+            if (!projectId) {
+                return toolError("Could not resolve project ID");
+            }
+            const resolvedCollaborators = [];
+            for (const entry of args.collaborators) {
+                if (entry.username && entry.teamSlug) {
+                    return toolError(`Collaborator entry has both username ("${entry.username}") and ` +
+                        `teamSlug ("${entry.teamSlug}"). Provide exactly one.`);
+                }
+                if (!entry.username && !entry.teamSlug) {
+                    return toolError("Collaborator entry must have either username or teamSlug");
+                }
+                if (entry.username) {
+                    const userResult = await client.query(`query($login: String!) { user(login: $login) { id } }`, { login: entry.username }, { cache: true, cacheTtlMs: 60 * 60 * 1000 });
+                    if (!userResult.user) {
+                        return toolError(`User "${entry.username}" not found`);
+                    }
+                    resolvedCollaborators.push({
+                        userId: userResult.user.id,
+                        role: entry.role,
+                    });
+                }
+                else if (entry.teamSlug) {
+                    const teamResult = await client.query(`query($org: String!, $slug: String!) {
+                organization(login: $org) {
+                  team(slug: $slug) { id }
+                }
+              }`, { org: projectOwner, slug: entry.teamSlug }, { cache: true, cacheTtlMs: 60 * 60 * 1000 });
+                    if (!teamResult.organization) {
+                        return toolError(`Team collaborators require an organization-owned project. ` +
+                            `"${projectOwner}" is not an organization.`);
+                    }
+                    if (!teamResult.organization.team) {
+                        return toolError(`Team "${entry.teamSlug}" not found in organization "${projectOwner}"`);
+                    }
+                    resolvedCollaborators.push({
+                        teamId: teamResult.organization.team.id,
+                        role: entry.role,
+                    });
+                }
+            }
+            await client.projectMutate(`mutation($projectId: ID!, $collaborators: [ProjectV2Collaborator!]!) {
+            updateProjectV2Collaborators(input: {
+              projectId: $projectId,
+              collaborators: $collaborators
+            }) {
+              collaborators { totalCount }
+            }
+          }`, { projectId, collaborators: resolvedCollaborators });
+            return toolSuccess({
+                updated: true,
+                collaboratorCount: args.collaborators.length,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to update collaborators: ${message}`);
+        }
+    });
 }
 //# sourceMappingURL=project-management-tools.js.map

package/dist/tools/relationship-tools.js

@@ -9,7 +9,7 @@
  */
 import { z } from "zod";
 import { detectGroup } from "../lib/group-detection.js";
-import { isValidState, isEarlierState, VALID_STATES, } from "../lib/workflow-states.js";
+import { isValidState, isEarlierState, VALID_STATES, PARENT_GATE_STATES, isParentGateState, stateIndex, } from "../lib/workflow-states.js";
 import { toolSuccess, toolError, resolveProjectOwner } from "../types.js";
 import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, getCurrentFieldValue, resolveConfig, syncStatusField, } from "../lib/helpers.js";
 // ---------------------------------------------------------------------------
@@ -438,5 +438,159 @@ export function registerRelationshipTools(server, client, fieldCache) {
             return toolError(`Failed to advance children: ${message}`);
         }
     });
+    // -------------------------------------------------------------------------
+    // ralph_hero__advance_parent
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__advance_parent", "Check if all siblings of a child issue have reached a gate state, and if so, advance the parent issue to match. Gate states: Ready for Plan, In Review, Done. Only applies to parent/child (sub-issue) relationships. Returns what changed or why the parent was not advanced.", {
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner. Defaults to GITHUB_OWNER env var"),
+        repo: z
+            .string()
+            .optional()
+            .describe("Repository name. Defaults to GITHUB_REPO env var"),
+        number: z
+            .number()
+            .describe("Child issue number (any child in the group)"),
+    }, async (args) => {
+        try {
+            const { owner, repo } = resolveConfig(client, args);
+            const projectNumber = client.config.projectNumber;
+            if (!projectNumber) {
+                return toolError("projectNumber is required (set RALPH_GH_PROJECT_NUMBER env var)");
+            }
+            const projectOwner = resolveProjectOwner(client.config);
+            if (!projectOwner) {
+                return toolError("projectOwner is required (set RALPH_GH_PROJECT_OWNER or RALPH_GH_OWNER env var)");
+            }
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            // Fetch child issue to find its parent
+            const childResult = await client.query(`query($owner: String!, $repo: String!, $issueNumber: Int!) {
+            repository(owner: $owner, name: $repo) {
+              issue(number: $issueNumber) {
+                number
+                title
+                parent { number title state }
+              }
+            }
+          }`, { owner, repo, issueNumber: args.number });
+            const childIssue = childResult.repository?.issue;
+            if (!childIssue) {
+                return toolError(`Issue #${args.number} not found in ${owner}/${repo}`);
+            }
+            if (!childIssue.parent) {
+                return toolSuccess({
+                    advanced: false,
+                    reason: "Issue has no parent",
+                    child: { number: childIssue.number, title: childIssue.title },
+                });
+            }
+            const parentNumber = childIssue.parent.number;
+            // Fetch all siblings (sub-issues of the parent)
+            const siblingResult = await client.query(`query($owner: String!, $repo: String!, $parentNum: Int!) {
+            repository(owner: $owner, name: $repo) {
+              issue(number: $parentNum) {
+                number
+                title
+                subIssues(first: 50) {
+                  nodes { id number title state }
+                }
+              }
+            }
+          }`, { owner, repo, parentNum: parentNumber });
+            const parentIssue = siblingResult.repository?.issue;
+            if (!parentIssue) {
+                return toolError(`Parent issue #${parentNumber} not found in ${owner}/${repo}`);
+            }
+            const siblings = parentIssue.subIssues.nodes;
+            if (siblings.length === 0) {
+                return toolSuccess({
+                    advanced: false,
+                    reason: "Parent has no sub-issues",
+                    parent: { number: parentNumber, title: parentIssue.title },
+                });
+            }
+            // Get workflow state for each sibling and find the minimum
+            const childStates = [];
+            let minStateIdx = Infinity;
+            for (const sibling of siblings) {
+                const currentState = await getCurrentFieldValue(client, fieldCache, owner, repo, sibling.number, "Workflow State");
+                const state = currentState || "unknown";
+                childStates.push({
+                    number: sibling.number,
+                    title: sibling.title,
+                    workflowState: state,
+                });
+                const idx = stateIndex(state);
+                // States not in STATE_ORDER (Human Needed, Canceled, unknown) block advancement
+                if (idx === -1) {
+                    return toolSuccess({
+                        advanced: false,
+                        reason: `Child #${sibling.number} is in state "${state}" which is outside the pipeline -- blocks parent advancement`,
+                        parent: { number: parentNumber, title: parentIssue.title },
+                        childStates,
+                    });
+                }
+                if (idx < minStateIdx) {
+                    minStateIdx = idx;
+                }
+            }
+            // Find the minimum state name
+            const minState = siblings.length > 0
+                ? childStates.reduce((min, cs) => {
+                    const idx = stateIndex(cs.workflowState);
+                    const minIdx = stateIndex(min.workflowState);
+                    return idx < minIdx ? cs : min;
+                }).workflowState
+                : "unknown";
+            // Check if the minimum state is a gate state
+            if (!isParentGateState(minState)) {
+                return toolSuccess({
+                    advanced: false,
+                    reason: "Not all children at a gate state",
+                    minimumChildState: minState,
+                    gateStates: [...PARENT_GATE_STATES],
+                    parent: { number: parentNumber, title: parentIssue.title },
+                    childStates,
+                });
+            }
+            // Get parent's current workflow state
+            const parentState = await getCurrentFieldValue(client, fieldCache, owner, repo, parentNumber, "Workflow State");
+            // Check if parent is already at or past the target state
+            const parentIdx = stateIndex(parentState || "");
+            if (parentIdx >= minStateIdx) {
+                return toolSuccess({
+                    advanced: false,
+                    reason: "Parent already at or past target state",
+                    parent: {
+                        number: parentNumber,
+                        title: parentIssue.title,
+                        currentState: parentState,
+                    },
+                    targetState: minState,
+                    childStates,
+                });
+            }
+            // Advance the parent
+            const projectItemId = await resolveProjectItemId(client, fieldCache, owner, repo, parentNumber);
+            await updateProjectItemField(client, fieldCache, projectItemId, "Workflow State", minState);
+            await syncStatusField(client, fieldCache, projectItemId, minState);
+            return toolSuccess({
+                advanced: true,
+                parent: {
+                    number: parentNumber,
+                    title: parentIssue.title,
+                    fromState: parentState || "unknown",
+                    toState: minState,
+                },
+                childStates,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to advance parent: ${message}`);
+        }
+    });
 }
 //# sourceMappingURL=relationship-tools.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-mcp-server",
-  "version": "1.3.3",
+  "version": "2.4.6",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",