ralph-hero-mcp-server 2.5.23 → 2.5.42

package/dist/github-client.js

@@ -166,6 +166,27 @@ export function createGitHubClient(clientConfig, debugLogger) {
             cache.set(cacheKey, login, 60 * 60 * 1000); // Cache for 1 hour
             return login;
         },
+        async restPost(path, body, useProjectToken = true) {
+            const token = useProjectToken
+                ? (clientConfig.projectToken ?? clientConfig.token)
+                : clientConfig.token;
+            const url = `https://api.github.com${path}`;
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    Authorization: `token ${token}`,
+                    Accept: "application/vnd.github+json",
+                    "X-GitHub-Api-Version": "2022-11-28",
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const text = await response.text().catch(() => "");
+                throw new Error(`GitHub REST API error ${response.status} for ${path}: ${text}`);
+            }
+            return response.json();
+        },
     };
 }
 //# sourceMappingURL=github-client.js.map

package/dist/index.js

@@ -22,6 +22,7 @@ import { registerProjectManagementTools } from "./tools/project-management-tools
 import { registerHygieneTools } from "./tools/hygiene-tools.js";
 import { registerDebugTools } from "./tools/debug-tools.js";
 import { registerDecomposeTools } from "./tools/decompose-tools.js";
+import { registerViewTools } from "./tools/view-tools.js";
 /**
  * Initialize the GitHub client from environment variables.
  */
@@ -301,6 +302,8 @@ async function main() {
     registerHygieneTools(server, client, fieldCache);
     // Decompose feature tool (cross-repo decomposition via .ralph-repos.yml)
     registerDecomposeTools(server, client, fieldCache);
+    // View management tools (REST API view creation)
+    registerViewTools(server, client, fieldCache);
     // Debug tools (only when RALPH_DEBUG=true)
     if (process.env.RALPH_DEBUG === 'true') {
         registerDebugTools(server, client);

package/dist/lib/cache.js

@@ -87,10 +87,12 @@ export class FieldOptionCache {
     defaultProjectNumber;
     /**
      * Populate the cache from project field data.
+     * Handles both single-select fields (options) and iteration fields (configuration.iterations).
      */
     populate(projectNumber, projectId, fields) {
         const fieldMap = new Map();
         const fieldIdMap = new Map();
+        const iterationMap = new Map();
         for (const field of fields) {
             fieldIdMap.set(field.name, field.id);
             if (field.options) {
@@ -100,11 +102,28 @@ export class FieldOptionCache {
                 }
                 fieldMap.set(field.name, optionMap);
             }
+            if (field.configuration?.iterations) {
+                // Store iteration title -> ID in the options map for resolveOptionId compatibility
+                const iterOptionMap = new Map();
+                for (const iter of field.configuration.iterations) {
+                    iterOptionMap.set(iter.title, iter.id);
+                }
+                for (const iter of field.configuration.completedIterations ?? []) {
+                    iterOptionMap.set(iter.title, iter.id);
+                }
+                fieldMap.set(field.name, iterOptionMap);
+                // Store full iteration metadata for @current/@next resolution
+                iterationMap.set(field.name, [
+                    ...field.configuration.iterations,
+                    ...(field.configuration.completedIterations ?? []),
+                ]);
+            }
         }
         this.projects.set(projectNumber, {
             projectId,
             fields: fieldMap,
             fieldIds: fieldIdMap,
+            iterations: iterationMap,
         });
         if (this.defaultProjectNumber === undefined) {
             this.defaultProjectNumber = projectNumber;
@@ -158,6 +177,15 @@ export class FieldOptionCache {
         const entry = this.resolveEntry(projectNumber);
         return entry ? Array.from(entry.fieldIds.keys()) : [];
     }
+    /**
+     * Get iteration data for a given field name.
+     * Returns all iterations (active + completed) with full metadata
+     * for @current/@next token resolution.
+     */
+    getIterations(fieldName, projectNumber) {
+        const entry = this.resolveEntry(projectNumber);
+        return entry?.iterations.get(fieldName);
+    }
     /**
      * Clear the cache (all projects).
      */

package/dist/lib/dashboard.js

@@ -369,6 +369,65 @@ export function computeStreamSection(streams, items) {
     return { streams: summaries };
 }
 // ---------------------------------------------------------------------------
+// Iteration section
+// ---------------------------------------------------------------------------
+/**
+ * Build per-iteration breakdown: group items by iteration, count phases
+ * per iteration. Only includes items that have an iteration assignment.
+ * Returns undefined if no items have iteration data.
+ */
+export function buildIterationSection(items) {
+    const iterItems = items.filter((i) => i.iterationId && i.iterationTitle);
+    if (iterItems.length === 0)
+        return undefined;
+    // Group by iteration title
+    const groups = new Map();
+    for (const item of iterItems) {
+        const title = item.iterationTitle;
+        const existing = groups.get(title);
+        if (existing) {
+            existing.items.push(item);
+        }
+        else {
+            groups.set(title, {
+                items: [item],
+                startDate: item.iterationStartDate ?? "",
+                duration: item.iterationDuration ?? 0,
+            });
+        }
+    }
+    // Build breakdowns sorted by start date
+    const breakdowns = [];
+    for (const [title, group] of groups) {
+        // Count items per workflow state
+        const stateCounts = new Map();
+        for (const item of group.items) {
+            const state = item.workflowState ?? "Unknown";
+            stateCounts.set(state, (stateCounts.get(state) ?? 0) + 1);
+        }
+        const phaseCounts = [];
+        for (const [state, count] of stateCounts) {
+            phaseCounts.push({ state, count });
+        }
+        // Sort by STATE_ORDER position
+        const stateIdx = (s) => {
+            const idx = STATE_ORDER.indexOf(s);
+            return idx >= 0 ? idx : STATE_ORDER.length;
+        };
+        phaseCounts.sort((a, b) => stateIdx(a.state) - stateIdx(b.state));
+        breakdowns.push({
+            iterationTitle: title,
+            startDate: group.startDate,
+            duration: group.duration,
+            phaseCounts,
+            totalIssues: group.items.length,
+        });
+    }
+    // Sort by start date
+    breakdowns.sort((a, b) => a.startDate.localeCompare(b.startDate));
+    return { iterations: breakdowns };
+}
+// ---------------------------------------------------------------------------
 // buildDashboard
 // ---------------------------------------------------------------------------
 /**
@@ -449,6 +508,8 @@ export function buildDashboard(items, config = DEFAULT_HEALTH_CONFIG, now = Date
     if (streams && streams.length > 0) {
         streamSection = computeStreamSection(streams, items);
     }
+    // Iteration section (only when items have iteration assignments)
+    const iterationSection = buildIterationSection(items);
     return {
         generatedAt: new Date(now).toISOString(),
         totalIssues: items.length,
@@ -461,6 +522,7 @@ export function buildDashboard(items, config = DEFAULT_HEALTH_CONFIG, now = Date
         ...(projectBreakdowns ? { projectBreakdowns } : {}),
         ...(repoBreakdowns ? { repoBreakdowns } : {}),
         ...(streamSection ? { streams: streamSection } : {}),
+        ...(iterationSection ? { iterations: iterationSection } : {}),
     };
 }
 // ---------------------------------------------------------------------------
@@ -605,6 +667,27 @@ export function formatMarkdown(data, issuesPerPhase = 10) {
             }
         }
     }
+    // Iteration section
+    if (data.iterations && data.iterations.iterations.length > 0) {
+        lines.push("");
+        lines.push("## Iterations");
+        for (const iter of data.iterations.iterations) {
+            const endDate = iter.startDate && iter.duration
+                ? new Date(new Date(iter.startDate).getTime() + iter.duration * 86400000)
+                    .toISOString().split("T")[0]
+                : "";
+            const dateRange = iter.startDate && endDate
+                ? ` (${iter.startDate} to ${endDate}, ${iter.duration}d)`
+                : "";
+            lines.push("");
+            lines.push(`### ${iter.iterationTitle}${dateRange}`);
+            lines.push("");
+            const phaseLine = iter.phaseCounts
+                .map((p) => `${p.state}: ${p.count}`)
+                .join(" | ");
+            lines.push(`${phaseLine} (${iter.totalIssues} total)`);
+        }
+    }
     // Stream section
     if (data.streams && data.streams.streams.length > 0) {
         lines.push("");
@@ -705,6 +788,17 @@ export function formatAscii(data) {
             }
         }
     }
+    // Iteration section
+    if (data.iterations && data.iterations.iterations.length > 0) {
+        lines.push("");
+        lines.push("--- Iterations ---");
+        for (const iter of data.iterations.iterations) {
+            const phaseLine = iter.phaseCounts
+                .map((p) => `${p.state}: ${p.count}`)
+                .join(", ");
+            lines.push(`${iter.iterationTitle}: ${phaseLine} (${iter.totalIssues} total)`);
+        }
+    }
     // Stream section
     if (data.streams && data.streams.streams.length > 0) {
         lines.push("");

package/dist/lib/helpers.js

@@ -29,6 +29,15 @@ async function fetchProjectForCache(client, owner, number) {
               dataType
               options { id name }
             }
+            ... on ProjectV2IterationField {
+              id
+              name
+              dataType
+              configuration {
+                iterations { id title startDate duration }
+                completedIterations { id title startDate duration }
+              }
+            }
           }
         }
       }
@@ -62,9 +71,45 @@ export async function ensureFieldCache(client, fieldCache, owner, projectNumber)
         id: f.id,
         name: f.name,
         options: f.options,
+        configuration: f.configuration,
     })));
 }
 // ---------------------------------------------------------------------------
+// Helper: Resolve iteration title or @current/@next token to iteration ID
+// ---------------------------------------------------------------------------
+/**
+ * Resolve an iteration title string or special token (@current, @next)
+ * to its short iteration ID using cached iteration metadata.
+ *
+ * @param fieldCache - The populated FieldOptionCache
+ * @param projectNumber - The project number to look up
+ * @param fieldName - The iteration field name (e.g., "Sprint")
+ * @param titleOrToken - Iteration title, "@current", or "@next"
+ * @param now - Optional Date override for testing
+ * @returns The short iteration ID, or null if not found
+ */
+export function resolveIterationId(fieldCache, projectNumber, fieldName, titleOrToken, now) {
+    const today = now ?? new Date();
+    const iterations = fieldCache.getIterations(fieldName, projectNumber);
+    if (!iterations)
+        return null;
+    if (titleOrToken === "@current") {
+        return iterations.find((it) => {
+            const start = new Date(it.startDate);
+            const end = new Date(start.getTime() + it.duration * 86400000);
+            return start <= today && today < end;
+        })?.id ?? null;
+    }
+    if (titleOrToken === "@next") {
+        const upcoming = iterations
+            .filter((it) => new Date(it.startDate) > today)
+            .sort((a, b) => a.startDate.localeCompare(b.startDate));
+        return upcoming[0]?.id ?? null;
+    }
+    // Direct title lookup
+    return iterations.find((it) => it.title === titleOrToken)?.id ?? null;
+}
+// ---------------------------------------------------------------------------
 // Helper: Resolve issue number to node ID (with caching)
 // ---------------------------------------------------------------------------
 export async function resolveIssueNodeId(client, owner, repo, number) {

package/dist/tools/batch-tools.js

@@ -56,6 +56,7 @@ export function buildBatchMutationQuery(projectId, updates) {
         const itemVar = `item_${update.alias}`;
         const fieldVar = `field_${update.alias}`;
         const optVar = `opt_${update.alias}`;
+        const valueKey = update.valueType ?? "singleSelectOptionId";
         varDecls.push(`$${itemVar}: ID!`, `$${fieldVar}: ID!`, `$${optVar}: String!`);
         variables[itemVar] = update.itemId;
         variables[fieldVar] = update.fieldId;
@@ -64,7 +65,7 @@ export function buildBatchMutationQuery(projectId, updates) {
         projectId: $projectId,
         itemId: $${itemVar},
         fieldId: $${fieldVar},
-        value: { singleSelectOptionId: $${optVar} }
+        value: { ${valueKey}: $${optVar} }
       }) {
         projectV2Item { id }
       }`);

package/dist/tools/dashboard-tools.js

@@ -82,6 +82,8 @@ export function toDashboardItems(raw, projectNumber, projectTitle) {
             continue;
         if (r.content.number === undefined)
             continue;
+        // Extract iteration value (if any)
+        const iterFv = r.fieldValues.nodes.find((n) => n.__typename === "ProjectV2ItemFieldIterationValue");
         items.push({
             number: r.content.number,
             title: r.content.title ?? "(untitled)",
@@ -96,6 +98,12 @@ export function toDashboardItems(raw, projectNumber, projectTitle) {
             ...(projectNumber !== undefined ? { projectNumber } : {}),
             ...(projectTitle !== undefined ? { projectTitle } : {}),
             ...(r.content.repository ? { repository: r.content.repository.nameWithOwner } : {}),
+            ...(iterFv?.iterationId ? {
+                iterationId: iterFv.iterationId,
+                iterationTitle: iterFv.title ?? undefined,
+                iterationStartDate: iterFv.startDate ?? undefined,
+                iterationDuration: iterFv.duration ?? undefined,
+            } : {}),
         });
     }
     return items;
@@ -142,6 +150,14 @@ export const DASHBOARD_ITEMS_QUERY = `query($projectId: ID!, $cursor: String, $f
                 name
                 field { ... on ProjectV2FieldCommon { name } }
               }
+              ... on ProjectV2ItemFieldIterationValue {
+                __typename
+                iterationId
+                title
+                startDate
+                duration
+                field { ... on ProjectV2FieldCommon { name } }
+              }
             }
           }
         }

package/dist/tools/issue-tools.js

@@ -14,7 +14,7 @@ import { resolveState } from "../lib/state-resolution.js";
 import { parseDateMath } from "../lib/date-math.js";
 import { expandProfile } from "../lib/filter-profiles.js";
 import { toolSuccess, toolError } from "../types.js";
-import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, resolveConfig, resolveFullConfig, resolveFullConfigOptionalRepo, syncStatusField, autoAdvanceParent, } from "../lib/helpers.js";
+import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, resolveConfig, resolveFullConfig, resolveFullConfigOptionalRepo, syncStatusField, autoAdvanceParent, resolveIterationId, } from "../lib/helpers.js";
 import { lookupRepo, mergeDefaults } from "../lib/repo-registry.js";
 // ---------------------------------------------------------------------------
 // Register issue tools
@@ -23,7 +23,7 @@ export function registerIssueTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__list_issues
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__list_issues", "List issues from a GitHub repository with optional filters. Returns: number, title, state, workflowState, estimate, priority, labels, assignees. Use workflowState filter to find issues in a specific phase. Recovery: if no results, broaden filters or check that issues exist in the project.", {
+    server.tool("ralph_hero__list_issues", "List issues from a GitHub repository with optional filters. Returns: number, title, state, workflowState, estimate, priority, iteration, labels, assignees. Use workflowState filter to find issues in a specific phase. Use iteration filter with @current/@next or sprint title. Recovery: if no results, broaden filters or check that issues exist in the project.", {
         owner: z
             .string()
             .optional()
@@ -51,6 +51,11 @@ export function registerIssueTools(server, client, fieldCache) {
             .string()
             .optional()
             .describe("Filter by Priority (P0, P1, P2, P3)"),
+        iteration: z
+            .string()
+            .optional()
+            .describe("Filter by iteration/sprint. Accepts iteration title (e.g., 'Sprint 1'), " +
+            "@current (active sprint), or @next (upcoming sprint)."),
         label: z.string().optional().describe("Filter by label name"),
         repoFilter: z
             .string()
@@ -166,6 +171,14 @@ export function registerIssueTools(server, client, fieldCache) {
                           optionId
                           field { ... on ProjectV2FieldCommon { name } }
                         }
+                        ... on ProjectV2ItemFieldIterationValue {
+                          __typename
+                          iterationId
+                          title
+                          startDate
+                          duration
+                          field { ... on ProjectV2FieldCommon { name } }
+                        }
                       }
                     }
                   }
@@ -202,6 +215,33 @@ export function registerIssueTools(server, client, fieldCache) {
             if (args.priority) {
                 items = items.filter((item) => getFieldValue(item, "Priority") === args.priority);
             }
+            // Filter by iteration
+            if (args.iteration) {
+                // Discover the iteration field name from cache
+                const fieldNames = fieldCache.getFieldNames(projectNumber);
+                const iterFieldName = fieldNames.find((name) => {
+                    const iters = fieldCache.getIterations(name, projectNumber);
+                    return iters !== undefined && iters.length > 0;
+                });
+                if (iterFieldName) {
+                    // Resolve the target iteration ID from title or token
+                    const targetIterationId = resolveIterationId(fieldCache, projectNumber, iterFieldName, args.iteration);
+                    if (targetIterationId) {
+                        items = items.filter((item) => {
+                            const iterVal = getIterationValue(item);
+                            return iterVal?.iterationId === targetIterationId;
+                        });
+                    }
+                    else {
+                        // Token/title did not resolve - no items can match
+                        items = [];
+                    }
+                }
+                else {
+                    // No iteration field configured - no items can match
+                    items = [];
+                }
+            }
             // Filter by label
             if (args.label) {
                 items = items.filter((item) => {
@@ -294,6 +334,7 @@ export function registerIssueTools(server, client, fieldCache) {
             // Format response
             const formattedItems = items.map((item) => {
                 const content = item.content;
+                const iterVal = getIterationValue(item);
                 return {
                     number: content?.number,
                     title: content?.title,
@@ -304,6 +345,9 @@ export function registerIssueTools(server, client, fieldCache) {
                     workflowState: getFieldValue(item, "Workflow State"),
                     estimate: getFieldValue(item, "Estimate"),
                     priority: getFieldValue(item, "Priority"),
+                    iteration: iterVal
+                        ? { title: iterVal.title, startDate: iterVal.startDate, duration: iterVal.duration }
+                        : null,
                     labels: content?.labels?.nodes?.map((l) => l.name),
                     assignees: content?.assignees?.nodes?.map((a) => a.login),
                 };
@@ -762,10 +806,10 @@ export function registerIssueTools(server, client, fieldCache) {
     // ralph_hero__save_issue
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__save_issue", "Unified issue mutation: update any combination of issue properties (title, body, labels, assignees, open/close) " +
-        "and project field values (workflow state, estimate, priority) in a single call. " +
+        "and project field values (workflow state, estimate, priority, iteration) in a single call. " +
         "Supports semantic intents (__LOCK__, __COMPLETE__, etc.) for workflowState. " +
         "Auto-closes the GitHub issue when workflowState resolves to a terminal state (Done, Canceled) unless issueState is explicitly set. " +
-        "Set estimate or priority to null to clear the field. " +
+        "Set estimate, priority, or iteration to null to clear the field. Use @current/@next tokens for iteration. " +
         "Returns: number, url, changes.", {
         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"),
@@ -785,6 +829,8 @@ export function registerIssueTools(server, client, fieldCache) {
             .describe("Estimate. Set to null to clear."),
         priority: z.enum(["P0", "P1", "P2", "P3"]).nullable().optional()
             .describe("Priority. Set to null to clear."),
+        iteration: z.string().nullable().optional()
+            .describe("Iteration/sprint title (e.g., 'Sprint 1'), @current, @next, or null to clear."),
         command: z.string().optional()
             .describe("Ralph command for semantic intent resolution (e.g., 'ralph_impl'). Required when workflowState is a semantic intent."),
     }, async (args) => {
@@ -793,7 +839,8 @@ export function registerIssueTools(server, client, fieldCache) {
             const hasIssueFields = args.title !== undefined || args.body !== undefined ||
                 args.labels !== undefined || args.assignees !== undefined || args.issueState !== undefined;
             const hasProjectFields = args.workflowState !== undefined ||
-                args.estimate !== undefined || args.priority !== undefined;
+                args.estimate !== undefined || args.priority !== undefined ||
+                args.iteration !== undefined;
             if (!hasIssueFields && !hasProjectFields) {
                 return toolError("No fields to update. Provide at least one field.");
             }
@@ -1007,12 +1054,45 @@ export function registerIssueTools(server, client, fieldCache) {
                         changes.priority = args.priority;
                     }
                 }
-                // 4d. Execute aliased batch mutation for non-null field updates
+                // 4d. Iteration (set, resolve token, or clear)
+                if (args.iteration !== undefined) {
+                    const fieldNames = fieldCache.getFieldNames(projectNumber);
+                    const iterFieldName = fieldNames.find((name) => {
+                        const iters = fieldCache.getIterations(name, projectNumber);
+                        return iters !== undefined && iters.length > 0;
+                    });
+                    if (iterFieldName) {
+                        const fieldId = fieldCache.getFieldId(iterFieldName, projectNumber);
+                        if (args.iteration === null) {
+                            // Clear the iteration field
+                            if (fieldId) {
+                                fieldsToClear.push({ fieldName: iterFieldName, fieldId });
+                            }
+                            changes.iteration = null;
+                        }
+                        else {
+                            // Set iteration by title or token (@current, @next)
+                            const iterationId = resolveIterationId(fieldCache, projectNumber, iterFieldName, args.iteration);
+                            if (fieldId && iterationId) {
+                                updates.push({
+                                    alias: `iter_${opIdx}`,
+                                    itemId: projectItemId,
+                                    fieldId,
+                                    optionId: iterationId,
+                                    valueType: "iterationId",
+                                });
+                                opIdx++;
+                            }
+                            changes.iteration = args.iteration;
+                        }
+                    }
+                }
+                // 4e. Execute aliased batch mutation for non-null field updates
                 if (updates.length > 0) {
                     const { mutationString, variables } = buildBatchMutationQuery(projectId, updates);
                     await client.projectMutate(mutationString, variables);
                 }
-                // 4e. Execute clear mutations for null fields (separate calls)
+                // 4f. Execute clear mutations for null fields (separate calls)
                 for (const { fieldId } of fieldsToClear) {
                     await client.projectMutate(`mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!) {
                 clearProjectV2ItemFieldValue(input: {
@@ -1024,7 +1104,7 @@ export function registerIssueTools(server, client, fieldCache) {
                 }
               }`, { projectId, itemId: projectItemId, fieldId });
                 }
-                // 4f. Auto-advance parent if we just moved to a gate state
+                // 4g. Auto-advance parent if we just moved to a gate state
                 if (resolvedWorkflowState && isParentGateState(resolvedWorkflowState)) {
                     try {
                         const advanceResult = await autoAdvanceParent(client, fieldCache, owner, repo, args.number, resolvedWorkflowState, projectNumber);
@@ -1283,6 +1363,19 @@ function getFieldValue(item, fieldName) {
         fv.__typename === "ProjectV2ItemFieldSingleSelectValue");
     return fieldValue?.name;
 }
+function getIterationValue(item) {
+    const fv = item.fieldValues.nodes.find((fv) => fv.__typename === "ProjectV2ItemFieldIterationValue");
+    if (fv?.iterationId && fv.title && fv.startDate != null && fv.duration != null && fv.field?.name) {
+        return {
+            iterationId: fv.iterationId,
+            title: fv.title,
+            startDate: fv.startDate,
+            duration: fv.duration,
+            fieldName: fv.field.name,
+        };
+    }
+    return undefined;
+}
 function hasField(item, field) {
     switch (field) {
         case "workflowState":

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

@@ -8,7 +8,6 @@
  */
 import { z } from "zod";
 import { toolSuccess, toolError } from "../types.js";
-import { paginateConnection } from "../lib/pagination.js";
 import { buildBatchArchiveMutation } from "./batch-tools.js";
 import { ensureFieldCache, resolveProjectItemId, resolveFullConfig, updateProjectItemField, } from "../lib/helpers.js";
 // ---------------------------------------------------------------------------
@@ -489,64 +488,79 @@ export function registerProjectManagementTools(server, client, fieldCache) {
                 return toolError("Could not resolve project ID");
             }
             const effectiveMax = Math.min(args.maxItems || 50, 200);
-            // Query project items with field values
-            const itemsResult = await paginateConnection((q, v) => client.projectQuery(q, v), `query($projectId: ID!, $cursor: String, $first: Int!) {
-            node(id: $projectId) {
-              ... on ProjectV2 {
-                items(first: $first, after: $cursor) {
-                  totalCount
-                  pageInfo { hasNextPage endCursor }
-                  nodes {
-                    id
-                    type
-                    content {
-                      ... on Issue {
-                        number
-                        title
-                        updatedAt
-                      }
-                      ... on PullRequest {
-                        number
-                        title
-                        updatedAt
+            const SCAN_CAP = 2000; // Hard limit to prevent runaway pagination
+            // Validate updatedBefore early (before scan loop)
+            let updatedBeforeCutoff;
+            if (args.updatedBefore) {
+                updatedBeforeCutoff = new Date(args.updatedBefore).getTime();
+                if (isNaN(updatedBeforeCutoff)) {
+                    return toolError("Invalid updatedBefore date. Use ISO 8601 format (e.g., 2026-02-01T00:00:00Z)");
+                }
+            }
+            // Scan-until-full: fetch pages and filter until we have enough matches or exhaust items
+            const matched = [];
+            let cursor = null;
+            let totalScanned = 0;
+            let hasMorePages = true;
+            while (matched.length < effectiveMax && hasMorePages && totalScanned < SCAN_CAP) {
+                const pageSize = Math.min(100, SCAN_CAP - totalScanned);
+                const page = await client.projectQuery(`query($projectId: ID!, $cursor: String, $first: Int!) {
+              node(id: $projectId) {
+                ... on ProjectV2 {
+                  items(first: $first, after: $cursor) {
+                    totalCount
+                    pageInfo { hasNextPage endCursor }
+                    nodes {
+                      id
+                      type
+                      content {
+                        ... on Issue {
+                          number
+                          title
+                          updatedAt
+                        }
+                        ... on PullRequest {
+                          number
+                          title
+                          updatedAt
+                        }
                       }
-                    }
-                    fieldValues(first: 20) {
-                      nodes {
-                        ... on ProjectV2ItemFieldSingleSelectValue {
-                          __typename
-                          name
-                          field { ... on ProjectV2FieldCommon { name } }
+                      fieldValues(first: 20) {
+                        nodes {
+                          ... on ProjectV2ItemFieldSingleSelectValue {
+                            __typename
+                            name
+                            field { ... on ProjectV2FieldCommon { name } }
+                          }
                         }
                       }
                     }
                   }
                 }
               }
-            }
-          }`, { projectId, first: 100 }, "node.items", { maxItems: effectiveMax * 3 });
-            // Validate updatedBefore if provided
-            let updatedBeforeCutoff;
-            if (args.updatedBefore) {
-                updatedBeforeCutoff = new Date(args.updatedBefore).getTime();
-                if (isNaN(updatedBeforeCutoff)) {
-                    return toolError("Invalid updatedBefore date. Use ISO 8601 format (e.g., 2026-02-01T00:00:00Z)");
+            }`, { projectId, first: pageSize, cursor });
+                const connection = page.node;
+                const items = connection.items;
+                totalScanned += items.nodes.length;
+                for (const item of items.nodes) {
+                    if (matched.length >= effectiveMax)
+                        break;
+                    const ws = getBulkArchiveFieldValue(item, "Workflow State");
+                    if (!ws || !args.workflowStates.includes(ws))
+                        continue;
+                    if (updatedBeforeCutoff) {
+                        if (!item.content?.updatedAt)
+                            continue;
+                        if (new Date(item.content.updatedAt).getTime() >= updatedBeforeCutoff)
+                            continue;
+                    }
+                    matched.push(item);
                 }
+                hasMorePages = items.pageInfo.hasNextPage && !!items.pageInfo.endCursor;
+                cursor = items.pageInfo.endCursor;
             }
-            // Filter by workflow state and optional date
-            const matched = itemsResult.nodes
-                .filter((item) => {
-                const ws = getBulkArchiveFieldValue(item, "Workflow State");
-                return ws && args.workflowStates.includes(ws);
-            })
-                .filter((item) => {
-                if (!updatedBeforeCutoff)
-                    return true;
-                if (!item.content?.updatedAt)
-                    return false;
-                return new Date(item.content.updatedAt).getTime() < updatedBeforeCutoff;
-            })
-                .slice(0, effectiveMax);
+            // Determine if more eligible items may exist beyond what we collected
+            const hasMore = matched.length >= effectiveMax && hasMorePages;
             if (matched.length === 0) {
                 return toolSuccess({
                     dryRun: args.dryRun,
@@ -554,6 +568,8 @@ export function registerProjectManagementTools(server, client, fieldCache) {
                     wouldArchive: 0,
                     items: [],
                     errors: [],
+                    hasMore: false,
+                    totalScanned,
                 });
             }
             // Dry run: return matched items without archiving
@@ -567,6 +583,8 @@ export function registerProjectManagementTools(server, client, fieldCache) {
                         itemId: m.id,
                     })),
                     errors: [],
+                    hasMore,
+                    totalScanned,
                 });
             }
             // Chunk and execute archive mutations
@@ -598,6 +616,8 @@ export function registerProjectManagementTools(server, client, fieldCache) {
                 archivedCount: archived.length,
                 items: archived,
                 errors,
+                hasMore,
+                totalScanned,
             });
         }
         catch (error) {

package/dist/tools/project-tools.js

@@ -99,7 +99,7 @@ export function registerProjectTools(server, client, fieldCache) {
     // -------------------------------------------------------------------------
     // ralph_hero__setup_project
     // -------------------------------------------------------------------------
-    server.tool("ralph_hero__setup_project", "Create a new GitHub Project V2 with Workflow State, Priority, and Estimate custom fields", {
+    server.tool("ralph_hero__setup_project", "Create a new GitHub Project V2 with Workflow State, Priority, Estimate, and optional Sprint iteration fields", {
         owner: z.string().describe("GitHub owner (user or org)"),
         title: z.string().describe("Project title").default("Ralph Workflow"),
         templateProjectNumber: z
@@ -107,6 +107,12 @@ export function registerProjectTools(server, client, fieldCache) {
             .optional()
             .describe("Template project number to copy from. Overrides RALPH_GH_TEMPLATE_PROJECT env var. " +
             "When set, copies the template project (views, fields, automations) instead of creating blank."),
+        createIterationField: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('When true, creates a "Sprint" iteration field with 2-week duration starting next Monday. ' +
+            "Only applies to blank project creation (ignored when using template)."),
     }, async (args) => {
         try {
             const owner = args.owner || resolveProjectOwner(client.config);
@@ -203,6 +209,14 @@ export function registerProjectTools(server, client, fieldCache) {
                 // Estimate field
                 const estField = await createSingleSelectField(client, project.id, "Estimate", ESTIMATE_OPTIONS);
                 fieldResults["Estimate"] = estField;
+                // Optional: Sprint iteration field
+                if (args.createIterationField) {
+                    const iterField = await createIterationField(client, project.id, "Sprint", 14);
+                    fieldResults["Sprint"] = {
+                        id: iterField.id,
+                        options: [`Sprint 1 (${iterField.startDate}, ${iterField.durationDays}d)`],
+                    };
+                }
             }
             // Shared: cache hydration (both paths)
             await ensureFieldCacheForNewProject(client, fieldCache, owner, project.number);
@@ -372,6 +386,52 @@ async function fetchProject(client, owner, number) {
     }
     return null;
 }
+const VIEWS_QUERY_USER = `
+  query($login: String!, $number: Int!) {
+    user(login: $login) {
+      projectV2(number: $number) {
+        views(first: 50) {
+          nodes { id name number layout filter }
+        }
+      }
+    }
+  }
+`;
+const VIEWS_QUERY_ORG = `
+  query($login: String!, $number: Int!) {
+    organization(login: $login) {
+      projectV2(number: $number) {
+        views(first: 50) {
+          nodes { id name number layout filter }
+        }
+      }
+    }
+  }
+`;
+/**
+ * Fetch project views via GraphQL with user→org fallback.
+ * Returns views AND the resolved ownerType so callers can construct
+ * the correct REST API path without a separate round-trip.
+ */
+export async function fetchProjectViews(client, owner, projectNumber) {
+    // Try user first
+    try {
+        const result = await client.projectQuery(VIEWS_QUERY_USER, { login: owner, number: projectNumber });
+        const nodes = result.user?.projectV2?.views?.nodes;
+        if (nodes)
+            return { views: nodes, ownerType: "users" };
+    }
+    catch {
+        // fall through to org
+    }
+    // Try org
+    const result = await client.projectQuery(VIEWS_QUERY_ORG, { login: owner, number: projectNumber });
+    const nodes = result.organization?.projectV2?.views?.nodes;
+    if (!nodes) {
+        throw new Error(`Project #${projectNumber} not found for owner "${owner}"`);
+    }
+    return { views: nodes, ownerType: "orgs" };
+}
 async function createSingleSelectField(client, projectId, fieldName, options) {
     const result = await client.projectMutate(`mutation($projectId: ID!, $name: String!, $dataType: ProjectV2CustomFieldType!, $singleSelectOptions: [ProjectV2SingleSelectFieldOptionInput!]) {
       createProjectV2Field(input: {
@@ -410,6 +470,57 @@ async function ensureFieldCacheForNewProject(client, fieldCache, owner, number)
     client.getCache().invalidatePrefix("query:");
     await ensureFieldCache(client, fieldCache, owner, number);
 }
+/**
+ * Compute the next Monday on or after a given date.
+ * Used to set a sensible default start date for new iteration fields.
+ */
+function getNextMonday(from = new Date()) {
+    const d = new Date(from);
+    const day = d.getDay(); // 0=Sun, 1=Mon, ...
+    const daysUntilMonday = day === 0 ? 1 : day === 1 ? 0 : 8 - day;
+    d.setDate(d.getDate() + daysUntilMonday);
+    return d.toISOString().slice(0, 10); // YYYY-MM-DD
+}
+async function createIterationField(client, projectId, name = "Sprint", durationDays = 14, startDate) {
+    const start = startDate || getNextMonday();
+    const result = await client.projectMutate(`mutation($projectId: ID!, $name: String!, $dataType: ProjectV2CustomFieldType!, $config: ProjectV2IterationFieldConfigurationInput!) {
+      createProjectV2Field(input: {
+        projectId: $projectId,
+        dataType: $dataType,
+        name: $name,
+        iterationConfiguration: $config
+      }) {
+        projectV2Field {
+          ... on ProjectV2IterationField {
+            id
+            name
+            configuration {
+              iterations { startDate duration }
+            }
+          }
+        }
+      }
+    }`, {
+        projectId,
+        name,
+        dataType: "ITERATION",
+        config: {
+            duration: durationDays,
+            startDate: start,
+            iterations: [
+                { startDate: start, duration: durationDays },
+            ],
+        },
+    });
+    const field = result.createProjectV2Field.projectV2Field;
+    const firstIter = field.configuration?.iterations?.[0];
+    return {
+        id: field.id,
+        name: field.name || name,
+        startDate: firstIter?.startDate ?? start,
+        durationDays: firstIter?.duration ?? durationDays,
+    };
+}
 async function linkRepoAfterSetup(client, projectId, repoOwner, repoName) {
     const repoResult = await client.query(`query($repoOwner: String!, $repoName: String!) {
       repository(owner: $repoOwner, name: $repoName) { id }

package/dist/tools/view-tools.js

@@ -0,0 +1,102 @@
+/**
+ * MCP tools for GitHub Projects V2 view management.
+ *
+ * Copies views from a source project (read via GraphQL) to a target
+ * project using the REST API POST endpoint.
+ */
+import { z } from "zod";
+import { toolError, toolSuccess } from "../types.js";
+import { fetchProjectViews } from "./project-tools.js";
+/**
+ * Convert GraphQL layout enum to REST API layout value.
+ * All three variants are handled exhaustively — TypeScript will error
+ * at build time if a new layout variant is added and not handled here.
+ */
+export function toRestLayout(layout) {
+    switch (layout) {
+        case "TABLE_LAYOUT":
+            return "table";
+        case "BOARD_LAYOUT":
+            return "board";
+        case "ROADMAP_LAYOUT":
+            return "roadmap";
+    }
+}
+export function registerViewTools(server, client, _fieldCache) {
+    server.tool("ralph_hero__create_views", "Copy views from a source GitHub Project V2 to a target project using the REST API. Reads view names, layouts, and filter strings from the source project via GraphQL, then creates matching views in the target. Note: sort/group configuration is not available via API and must be set manually after creation.", {
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner (user or org). Defaults to RALPH_GH_OWNER env var"),
+        sourceProjectNumber: z.coerce
+            .number()
+            .describe("Project number to copy views FROM"),
+        targetProjectNumber: z.coerce
+            .number()
+            .describe("Project number to copy views INTO"),
+    }, async (args) => {
+        const owner = args.owner ?? client.config.projectOwner ?? client.config.owner;
+        if (!owner) {
+            return toolError("owner is required — set RALPH_GH_OWNER or pass owner param");
+        }
+        // Read views from source project; ownerType drives REST path selection
+        let sourceViews;
+        let ownerType;
+        try {
+            const result = await fetchProjectViews(client, owner, args.sourceProjectNumber);
+            sourceViews = result.views;
+            ownerType = result.ownerType;
+        }
+        catch (err) {
+            return toolError(`Failed to read views from project #${args.sourceProjectNumber}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (sourceViews.length === 0) {
+            return toolSuccess({
+                created: [],
+                failed: [],
+                count: 0,
+                sourceProject: args.sourceProjectNumber,
+                targetProject: args.targetProjectNumber,
+                message: "Source project has no views",
+            });
+        }
+        // REST path uses owner login (not numeric ID).
+        // filter is a plain top-level string matching the GraphQL field value.
+        const basePath = ownerType === "users"
+            ? `/users/${owner}/projectsV2/${args.targetProjectNumber}/views`
+            : `/orgs/${owner}/projectsV2/${args.targetProjectNumber}/views`;
+        const created = [];
+        const failed = [];
+        for (const view of sourceViews) {
+            const body = {
+                name: view.name,
+                layout: toRestLayout(view.layout),
+            };
+            if (view.filter) {
+                body.filter = view.filter;
+            }
+            try {
+                const createdView = await client.restPost(basePath, body);
+                created.push({
+                    name: createdView.name,
+                    layout: createdView.layout,
+                    id: createdView.id,
+                });
+            }
+            catch (err) {
+                failed.push({
+                    name: view.name,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return toolSuccess({
+            created,
+            failed,
+            count: created.length,
+            sourceProject: args.sourceProjectNumber,
+            targetProject: args.targetProjectNumber,
+        });
+    });
+}
+//# sourceMappingURL=view-tools.js.map

package/package.json

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