ralph-hero-mcp-server 2.4.34 → 2.4.36

package/dist/index.js

@@ -63,6 +63,12 @@ function initGitHubClient() {
     const projectNumber = resolveEnv("RALPH_GH_PROJECT_NUMBER")
         ? parseInt(resolveEnv("RALPH_GH_PROJECT_NUMBER"), 10)
         : undefined;
+    const projectNumbers = resolveEnv("RALPH_GH_PROJECT_NUMBERS")
+        ? resolveEnv("RALPH_GH_PROJECT_NUMBERS")
+            .split(",")
+            .map((s) => parseInt(s.trim(), 10))
+            .filter((n) => !isNaN(n))
+        : undefined;
     if (!owner) {
         console.error("[ralph-hero] Warning: RALPH_GH_OWNER not set.\n" +
             "Most tools require this. Set in your environment or .claude/ralph-hero.local.md");
@@ -85,6 +91,7 @@ function initGitHubClient() {
         owner: owner || undefined,
         repo: repo || undefined,
         projectNumber,
+        projectNumbers,
         projectOwner: projectOwner || undefined,
     });
 }

package/dist/lib/cache.js

@@ -72,84 +72,111 @@ export class SessionCache {
         return `query:${normalized}:${varsKey}`;
     }
 }
-// ---------------------------------------------------------------------------
-// Field Option Cache
-// ---------------------------------------------------------------------------
 /**
  * Maps field names to option names to option IDs for Projects V2
  * single-select fields. Populated by get_project, consumed by tools
  * that need to resolve human-readable names to GraphQL node IDs.
+ *
+ * Supports multiple projects keyed by project number. When projectNumber
+ * is omitted from method calls, the first populated project is used
+ * (backward compatible with single-project callers).
  */
 export class FieldOptionCache {
-    /** fieldName -> optionName -> optionId */
-    fields = new Map();
-    /** fieldName -> fieldId */
-    fieldIds = new Map();
-    /** projectId for the cached fields */
-    projectId;
+    projects = new Map();
+    /** Track the first populated project number for backward compat */
+    defaultProjectNumber;
     /**
      * Populate the cache from project field data.
      */
-    populate(projectId, fields) {
-        this.projectId = projectId;
-        this.fields.clear();
-        this.fieldIds.clear();
+    populate(projectNumber, projectId, fields) {
+        const fieldMap = new Map();
+        const fieldIdMap = new Map();
         for (const field of fields) {
-            this.fieldIds.set(field.name, field.id);
+            fieldIdMap.set(field.name, field.id);
             if (field.options) {
                 const optionMap = new Map();
                 for (const option of field.options) {
                     optionMap.set(option.name, option.id);
                 }
-                this.fields.set(field.name, optionMap);
+                fieldMap.set(field.name, optionMap);
             }
         }
+        this.projects.set(projectNumber, {
+            projectId,
+            fields: fieldMap,
+            fieldIds: fieldIdMap,
+        });
+        if (this.defaultProjectNumber === undefined) {
+            this.defaultProjectNumber = projectNumber;
+        }
     }
     /**
      * Resolve an option name to its ID for a given field.
      * Returns undefined if field or option not found.
      */
-    resolveOptionId(fieldName, optionName) {
-        return this.fields.get(fieldName)?.get(optionName);
+    resolveOptionId(fieldName, optionName, projectNumber) {
+        const entry = this.resolveEntry(projectNumber);
+        return entry?.fields.get(fieldName)?.get(optionName);
     }
     /**
      * Get the field ID for a field name.
      */
-    getFieldId(fieldName) {
-        return this.fieldIds.get(fieldName);
+    getFieldId(fieldName, projectNumber) {
+        const entry = this.resolveEntry(projectNumber);
+        return entry?.fieldIds.get(fieldName);
     }
     /**
      * Get the project ID for the cached fields.
      */
-    getProjectId() {
-        return this.projectId;
+    getProjectId(projectNumber) {
+        const entry = this.resolveEntry(projectNumber);
+        return entry?.projectId;
     }
     /**
      * Check if the cache has been populated.
+     * When projectNumber is provided, checks that specific project.
+     * When omitted, checks if any project is populated.
      */
-    isPopulated() {
-        return this.fields.size > 0;
+    isPopulated(projectNumber) {
+        if (projectNumber !== undefined) {
+            return this.projects.has(projectNumber);
+        }
+        return this.projects.size > 0;
     }
     /**
      * Get all option names for a field.
      */
-    getOptionNames(fieldName) {
-        const optionMap = this.fields.get(fieldName);
+    getOptionNames(fieldName, projectNumber) {
+        const entry = this.resolveEntry(projectNumber);
+        const optionMap = entry?.fields.get(fieldName);
         return optionMap ? Array.from(optionMap.keys()) : [];
     }
     /**
      * Get all field names.
      */
-    getFieldNames() {
-        return Array.from(this.fieldIds.keys());
+    getFieldNames(projectNumber) {
+        const entry = this.resolveEntry(projectNumber);
+        return entry ? Array.from(entry.fieldIds.keys()) : [];
     }
     /**
-     * Clear the cache.
+     * Clear the cache (all projects).
      */
     clear() {
-        this.fields.clear();
-        this.fieldIds.clear();
-        this.projectId = undefined;
+        this.projects.clear();
+        this.defaultProjectNumber = undefined;
+    }
+    /**
+     * Resolve the cache entry for a project number.
+     * Falls back to the first populated project when projectNumber is omitted.
+     */
+    resolveEntry(projectNumber) {
+        if (projectNumber !== undefined) {
+            return this.projects.get(projectNumber);
+        }
+        if (this.defaultProjectNumber !== undefined) {
+            return this.projects.get(this.defaultProjectNumber);
+        }
+        return undefined;
     }
 }
 //# sourceMappingURL=cache.js.map

package/dist/lib/helpers.js

@@ -50,14 +50,14 @@ async function fetchProjectForCache(client, owner, number) {
 // Helper: Ensure field option cache is populated
 // ---------------------------------------------------------------------------
 export async function ensureFieldCache(client, fieldCache, owner, projectNumber) {
-    if (fieldCache.isPopulated())
+    if (fieldCache.isPopulated(projectNumber))
         return;
     // Fetch project to populate cache - try user first, then org
     const project = await fetchProjectForCache(client, owner, projectNumber);
     if (!project) {
         throw new Error(`Project #${projectNumber} not found for owner "${owner}"`);
     }
-    fieldCache.populate(project.id, project.fields.nodes.map((f) => ({
+    fieldCache.populate(projectNumber, project.id, project.fields.nodes.map((f) => ({
         id: f.id,
         name: f.name,
         options: f.options,
@@ -269,9 +269,9 @@ export function resolveConfig(client, args) {
 // ---------------------------------------------------------------------------
 export function resolveFullConfig(client, args) {
     const { owner, repo } = resolveConfig(client, args);
-    const projectNumber = client.config.projectNumber;
+    const projectNumber = args.projectNumber ?? client.config.projectNumber;
     if (!projectNumber) {
-        throw new Error("projectNumber is required (set RALPH_GH_PROJECT_NUMBER env var)");
+        throw new Error("projectNumber is required (set RALPH_GH_PROJECT_NUMBER env var or pass explicitly)");
     }
     const projectOwner = resolveProjectOwner(client.config);
     if (!projectOwner) {

package/dist/tools/dashboard-tools.js

@@ -8,19 +8,19 @@
 import { z } from "zod";
 import { paginateConnection } from "../lib/pagination.js";
 import { buildDashboard, formatMarkdown, formatAscii, DEFAULT_HEALTH_CONFIG, } from "../lib/dashboard.js";
-import { toolSuccess, toolError, resolveProjectOwner } from "../types.js";
+import { toolSuccess, toolError, resolveProjectOwner, resolveProjectNumbers } from "../types.js";
 import { calculateMetrics, DEFAULT_METRICS_CONFIG, } from "../lib/metrics.js";
 // ---------------------------------------------------------------------------
 // Helper: Ensure field option cache is populated
 // ---------------------------------------------------------------------------
 async function ensureFieldCache(client, fieldCache, owner, projectNumber) {
-    if (fieldCache.isPopulated())
+    if (fieldCache.isPopulated(projectNumber))
         return;
     const project = await fetchProjectForCache(client, owner, projectNumber);
     if (!project) {
         throw new Error(`Project #${projectNumber} not found for owner "${owner}"`);
     }
-    fieldCache.populate(project.id, project.fields.nodes.map((f) => ({
+    fieldCache.populate(projectNumber, project.id, project.fields.nodes.map((f) => ({
         id: f.id,
         name: f.name,
         options: f.options,
@@ -69,8 +69,10 @@ function getFieldValue(item, fieldName) {
 }
 /**
  * Convert raw GraphQL project items to DashboardItem[].
+ * When projectNumber/projectTitle are provided, they are set on each item
+ * for multi-project dashboard support.
  */
-export function toDashboardItems(raw) {
+export function toDashboardItems(raw, projectNumber, projectTitle) {
     const items = [];
     for (const r of raw) {
         // Only include issues (not PRs or drafts)
@@ -88,6 +90,8 @@ export function toDashboardItems(raw) {
             estimate: getFieldValue(r, "Estimate"),
             assignees: r.content.assignees?.nodes?.map((a) => a.login) ?? [],
             blockedBy: [], // blockedBy requires separate queries; omit for now
+            ...(projectNumber !== undefined ? { projectNumber } : {}),
+            ...(projectTitle !== undefined ? { projectTitle } : {}),
         });
     }
     return items;
@@ -148,6 +152,10 @@ export function registerDashboardTools(server, client, fieldCache) {
             .string()
             .optional()
             .describe("GitHub owner. Defaults to GITHUB_OWNER env var"),
+        projectNumbers: z
+            .array(z.coerce.number())
+            .optional()
+            .describe("Project numbers to include. Defaults to RALPH_GH_PROJECT_NUMBERS or single configured project."),
         format: z
             .enum(["json", "markdown", "ascii"])
             .optional()
@@ -205,23 +213,45 @@ export function registerDashboardTools(server, client, fieldCache) {
     }, async (args) => {
         try {
             const owner = args.owner || resolveProjectOwner(client.config);
-            const projectNumber = client.config.projectNumber;
             if (!owner) {
                 return toolError("owner is required");
             }
-            if (!projectNumber) {
-                return toolError("project number is required");
+            // Resolve project numbers
+            const projectNumbers = args.projectNumbers
+                ?? resolveProjectNumbers(client.config);
+            if (projectNumbers.length === 0) {
+                return toolError("No project numbers configured. Set RALPH_GH_PROJECT_NUMBER or RALPH_GH_PROJECT_NUMBERS.");
             }
-            // Ensure field cache
-            await ensureFieldCache(client, fieldCache, owner, projectNumber);
-            const projectId = fieldCache.getProjectId();
-            if (!projectId) {
-                return toolError("Could not resolve project ID");
+            // Fetch items from all projects
+            const allItems = [];
+            const fetchWarnings = [];
+            for (const pn of projectNumbers) {
+                try {
+                    await ensureFieldCache(client, fieldCache, owner, pn);
+                }
+                catch (e) {
+                    fetchWarnings.push(`Project #${pn}: ${e instanceof Error ? e.message : String(e)}, skipping`);
+                    continue;
+                }
+                const projectId = fieldCache.getProjectId(pn);
+                if (!projectId) {
+                    fetchWarnings.push(`Project #${pn}: could not resolve project ID, skipping`);
+                    continue;
+                }
+                // Fetch project title
+                let projectTitle;
+                try {
+                    const titleResult = await client.projectQuery(`query($projectId: ID!) { node(id: $projectId) { ... on ProjectV2 { title } } }`, { projectId });
+                    projectTitle = titleResult.node?.title;
+                }
+                catch {
+                    // Non-fatal -- proceed without title
+                }
+                // Fetch items
+                const result = await paginateConnection((q, v) => client.projectQuery(q, v), DASHBOARD_ITEMS_QUERY, { projectId, first: 100 }, "node.items", { maxItems: 500 });
+                const items = toDashboardItems(result.nodes, pn, projectTitle);
+                allItems.push(...items);
             }
-            // Fetch all project items
-            const result = await paginateConnection((q, v) => client.projectQuery(q, v), DASHBOARD_ITEMS_QUERY, { projectId, first: 100 }, "node.items", { maxItems: 500 });
-            // Convert to dashboard items
-            const dashboardItems = toDashboardItems(result.nodes);
             // Build health config
             const healthConfig = {
                 ...DEFAULT_HEALTH_CONFIG,
@@ -231,8 +261,8 @@ export function registerDashboardTools(server, client, fieldCache) {
                 doneWindowDays: args.doneWindowDays ?? 7,
                 archiveThresholdDays: args.archiveThresholdDays ?? 14,
             };
-            // Build dashboard
-            const dashboard = buildDashboard(dashboardItems, healthConfig);
+            // Build dashboard from merged items
+            const dashboard = buildDashboard(allItems, healthConfig);
             // Strip health if not requested
             if (!args.includeHealth) {
                 dashboard.health = { ok: true, warnings: [] };
@@ -251,7 +281,7 @@ export function registerDashboardTools(server, client, fieldCache) {
                     atRiskThreshold: args.atRiskThreshold ?? 2,
                     offTrackThreshold: args.offTrackThreshold ?? 6,
                 };
-                metrics = calculateMetrics(dashboardItems, dashboard, metricsConfig);
+                metrics = calculateMetrics(allItems, dashboard, metricsConfig);
             }
             // Format output
             const format = args.format ?? "json";
@@ -266,6 +296,7 @@ export function registerDashboardTools(server, client, fieldCache) {
                 ...dashboard,
                 ...(formatted !== undefined ? { formatted } : {}),
                 ...(metrics !== undefined ? { metrics } : {}),
+                ...(fetchWarnings.length > 0 ? { fetchWarnings } : {}),
             });
         }
         catch (error) {

package/dist/tools/project-tools.js

@@ -81,16 +81,16 @@ const ESTIMATE_OPTIONS = [
 // Helper: Ensure field option cache is populated
 // ---------------------------------------------------------------------------
 async function ensureFieldCache(client, fieldCache, owner, projectNumber) {
-    if (fieldCache.isPopulated())
+    if (fieldCache.isPopulated(projectNumber))
         return;
     const project = await fetchProject(client, owner, projectNumber);
     if (!project) {
         throw new Error(`Project #${projectNumber} not found for owner "${owner}"`);
     }
-    populateFieldCache(fieldCache, project);
+    populateFieldCache(fieldCache, project, projectNumber);
 }
-function populateFieldCache(fieldCache, project) {
-    fieldCache.populate(project.id, project.fields.nodes.map((f) => ({
+function populateFieldCache(fieldCache, project, projectNumber) {
+    fieldCache.populate(projectNumber, project.id, project.fields.nodes.map((f) => ({
         id: f.id,
         name: f.name,
         options: f.options,
@@ -205,7 +205,7 @@ export function registerProjectTools(server, client, fieldCache) {
                 return toolError(`Project #${number} not found for owner "${owner}"`);
             }
             // Populate field cache
-            populateFieldCache(fieldCache, result);
+            populateFieldCache(fieldCache, result, number);
             // Format response
             const fields = result.fields.nodes.map((f) => ({
                 id: f.id,

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/dist/tools/view-tools.js

@@ -143,7 +143,7 @@ export function registerViewTools(server, client, fieldCache) {
     });
 }
 async function ensureFieldCache(client, fieldCache, owner, projectNumber) {
-    if (fieldCache.isPopulated())
+    if (fieldCache.isPopulated(projectNumber))
         return;
     const QUERY = `
     query($owner: String!, $number: Int!) {
@@ -171,7 +171,7 @@ async function ensureFieldCache(client, fieldCache, owner, projectNumber) {
             const result = await client.projectQuery(QUERY.replace("OWNER_TYPE", ownerType), { owner, number: projectNumber }, { cache: true });
             const project = result[ownerType]?.projectV2;
             if (project) {
-                fieldCache.populate(project.id, project.fields.nodes.map((f) => ({
+                fieldCache.populate(projectNumber, project.id, project.fields.nodes.map((f) => ({
                     id: f.id,
                     name: f.name,
                     options: f.options,

package/dist/types.js

@@ -18,4 +18,15 @@ export function toolError(message) {
 export function resolveProjectOwner(config) {
     return config.projectOwner || config.owner;
 }
+/**
+ * Return all configured project numbers.
+ * Prefers projectNumbers array; falls back to single projectNumber.
+ */
+export function resolveProjectNumbers(config) {
+    if (config.projectNumbers?.length)
+        return config.projectNumbers;
+    if (config.projectNumber)
+        return [config.projectNumber];
+    return [];
+}
 //# sourceMappingURL=types.js.map

package/package.json

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