ralph-hero-mcp-server 2.4.34 → 2.4.35

package/dist/tools/relationship-tools.js

@@ -325,7 +325,7 @@ export function registerRelationshipTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__advance_children
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__advance_children", "Advance all child/sub-issues of a parent to match the parent's new state. Only advances children that are in earlier workflow states. Returns what changed, what was skipped, and any errors.", {
+    server.tool("ralph_hero__advance_children", "Advance issues to a target workflow state. Provide either 'number' (parent issue, advances sub-issues) or 'issues' (explicit list of issue numbers). Only advances issues in earlier workflow states. Returns what changed, what was skipped, and any errors.", {
         owner: z
             .string()
             .optional()
@@ -334,12 +334,24 @@ export function registerRelationshipTools(server, client, fieldCache) {
             .string()
             .optional()
             .describe("Repository name. Defaults to GITHUB_REPO env var"),
-        number: z.coerce.number().describe("Parent issue number"),
+        number: z
+            .coerce.number()
+            .optional()
+            .describe("Parent issue number (resolves sub-issues automatically)"),
+        issues: z
+            .array(z.coerce.number())
+            .optional()
+            .describe("Explicit list of issue numbers to advance (alternative to parent number)"),
         targetState: z
             .string()
-            .describe("State to advance children to (e.g., 'Research Needed', 'Ready for Plan')"),
+            .describe("State to advance issues to (e.g., 'Research Needed', 'Ready for Plan')"),
     }, async (args) => {
         try {
+            // Validate: at least one of number or issues must be provided
+            if (args.number === undefined && (!args.issues || args.issues.length === 0)) {
+                return toolError("Either 'number' (parent issue) or 'issues' (explicit list) is required. " +
+                    "Recovery: provide one of these parameters.");
+            }
             // Validate target state
             if (!isValidState(args.targetState)) {
                 return toolError(`Unknown target state '${args.targetState}'. ` +
@@ -358,24 +370,32 @@ export function registerRelationshipTools(server, client, fieldCache) {
             }
             // Ensure field cache is populated
             await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
-            // Fetch sub-issues
-            const result = await client.query(`query($owner: String!, $repo: String!, $number: Int!) {
-            repository(owner: $owner, name: $repo) {
-              issue(number: $number) {
-                number
-                title
-                subIssues(first: 50) {
-                  nodes { id number title state }
+            // Build issue list: from explicit `issues` param or from parent's sub-issues
+            let issueNumbers;
+            if (args.issues && args.issues.length > 0) {
+                // Explicit issue list takes precedence
+                issueNumbers = args.issues;
+            }
+            else {
+                // Fetch sub-issues from parent
+                const result = await client.query(`query($owner: String!, $repo: String!, $number: Int!) {
+              repository(owner: $owner, name: $repo) {
+                issue(number: $number) {
+                  number
+                  title
+                  subIssues(first: 50) {
+                    nodes { id number title state }
+                  }
                 }
               }
+            }`, { owner, repo, number: args.number });
+                const parentIssue = result.repository?.issue;
+                if (!parentIssue) {
+                    return toolError(`Issue #${args.number} not found in ${owner}/${repo}`);
+                }
+                issueNumbers = parentIssue.subIssues.nodes.map((si) => si.number);
             }
-          }`, { owner, repo, number: args.number });
-            const parentIssue = result.repository?.issue;
-            if (!parentIssue) {
-                return toolError(`Issue #${args.number} not found in ${owner}/${repo}`);
-            }
-            const subIssues = parentIssue.subIssues.nodes;
-            if (subIssues.length === 0) {
+            if (issueNumbers.length === 0) {
                 return toolSuccess({
                     advanced: [],
                     skipped: [],
@@ -385,22 +405,22 @@ export function registerRelationshipTools(server, client, fieldCache) {
             const advanced = [];
             const skipped = [];
             const errors = [];
-            for (const child of subIssues) {
+            for (const issueNum of issueNumbers) {
                 try {
                     // Get current workflow state
-                    const currentState = await getCurrentFieldValue(client, fieldCache, owner, repo, child.number, "Workflow State");
+                    const currentState = await getCurrentFieldValue(client, fieldCache, owner, repo, issueNum, "Workflow State");
                     if (!currentState) {
                         skipped.push({
-                            number: child.number,
+                            number: issueNum,
                             currentState: "unknown",
                             reason: "No workflow state set on issue",
                         });
                         continue;
                     }
-                    // Only advance if child is in an earlier state
+                    // Only advance if issue is in an earlier state
                     if (!isEarlierState(currentState, args.targetState)) {
                         skipped.push({
-                            number: child.number,
+                            number: issueNum,
                             currentState,
                             reason: currentState === args.targetState
                                 ? "Already at target state"
@@ -408,13 +428,13 @@ export function registerRelationshipTools(server, client, fieldCache) {
                         });
                         continue;
                     }
-                    // Advance the child
-                    const projectItemId = await resolveProjectItemId(client, fieldCache, owner, repo, child.number);
+                    // Advance the issue
+                    const projectItemId = await resolveProjectItemId(client, fieldCache, owner, repo, issueNum);
                     await updateProjectItemField(client, fieldCache, projectItemId, "Workflow State", args.targetState);
                     // Sync default Status field (best-effort, one-way)
                     await syncStatusField(client, fieldCache, projectItemId, args.targetState);
                     advanced.push({
-                        number: child.number,
+                        number: issueNum,
                         fromState: currentState,
                         toState: args.targetState,
                     });
@@ -422,8 +442,8 @@ export function registerRelationshipTools(server, client, fieldCache) {
                 catch (error) {
                     const message = error instanceof Error ? error.message : String(error);
                     errors.push({
-                        number: child.number,
-                        error: `Failed to update: ${message}. Recovery: retry advance_children or update this child manually via update_workflow_state.`,
+                        number: issueNum,
+                        error: `Failed to update: ${message}. Recovery: retry advance_children or update this issue manually.`,
                     });
                 }
             }

package/package.json

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