ralph-hero-mcp-server 2.4.7 → 2.4.8

package/dist/lib/date-math.js

@@ -0,0 +1,57 @@
+/**
+ * Date-math expression parser for filtering by relative dates.
+ *
+ * Supports expressions like:
+ *   @today       - midnight UTC of current day
+ *   @now         - current instant
+ *   @today-7d    - 7 days before midnight UTC
+ *   @now-24h     - 24 hours ago
+ *   @today+3d    - 3 days in the future
+ *
+ * Offset units: h (hours), d (days), w (weeks), m (months)
+ * Also accepts absolute ISO dates as fallback (e.g., "2026-01-15").
+ */
+const DATE_MATH_RE = /^@(today|now)(?:([+-])(\d+)([hdwm]))?$/i;
+export function parseDateMath(expr, now = new Date()) {
+    const match = expr.match(DATE_MATH_RE);
+    if (match) {
+        const [, anchor, sign, amount, unit] = match;
+        const isToday = anchor.toLowerCase() === "today";
+        // Start from midnight UTC for @today, current instant for @now
+        let base;
+        if (isToday) {
+            base = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+        }
+        else {
+            base = new Date(now.getTime());
+        }
+        // Apply offset if present
+        if (sign && amount && unit) {
+            const n = parseInt(amount, 10);
+            const direction = sign === "+" ? 1 : -1;
+            switch (unit.toLowerCase()) {
+                case "h":
+                    base.setTime(base.getTime() + direction * n * 60 * 60 * 1000);
+                    break;
+                case "d":
+                    base.setTime(base.getTime() + direction * n * 24 * 60 * 60 * 1000);
+                    break;
+                case "w":
+                    base.setTime(base.getTime() + direction * n * 7 * 24 * 60 * 60 * 1000);
+                    break;
+                case "m":
+                    base.setUTCMonth(base.getUTCMonth() + direction * n);
+                    break;
+            }
+        }
+        return base;
+    }
+    // Fallback: try parsing as absolute date
+    const parsed = new Date(expr);
+    if (isNaN(parsed.getTime())) {
+        throw new Error(`Invalid date expression: "${expr}". ` +
+            `Use @today-7d, @now-24h, or an ISO date (YYYY-MM-DD).`);
+    }
+    return parsed;
+}
+//# sourceMappingURL=date-math.js.map

package/dist/tools/issue-tools.js

@@ -10,6 +10,7 @@ import { detectGroup } from "../lib/group-detection.js";
 import { detectPipelinePosition, } from "../lib/pipeline-detection.js";
 import { isValidState, VALID_STATES, LOCK_STATES, } from "../lib/workflow-states.js";
 import { resolveState } from "../lib/state-resolution.js";
+import { parseDateMath } from "../lib/date-math.js";
 import { toolSuccess, toolError } from "../types.js";
 import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, getCurrentFieldValue, resolveConfig, resolveFullConfig, syncStatusField, } from "../lib/helpers.js";
 // ---------------------------------------------------------------------------
@@ -47,6 +48,18 @@ export function registerIssueTools(server, client, fieldCache) {
             .optional()
             .default("OPEN")
             .describe("Issue state filter (default: OPEN)"),
+        reason: z
+            .enum(["completed", "not_planned", "reopened"])
+            .optional()
+            .describe("Filter by close reason: completed, not_planned, reopened"),
+        updatedSince: z
+            .string()
+            .optional()
+            .describe("Include items updated on or after this date. Supports date-math (@today-7d, @now-24h) or ISO dates (YYYY-MM-DD)."),
+        updatedBefore: z
+            .string()
+            .optional()
+            .describe("Include items updated before this date. Supports date-math (@today-7d, @now-24h) or ISO dates (YYYY-MM-DD)."),
         orderBy: z
             .enum(["CREATED_AT", "UPDATED_AT", "COMMENTS"])
             .optional()
@@ -82,6 +95,7 @@ export function registerIssueTools(server, client, fieldCache) {
                         title
                         body
                         state
+                        stateReason
                         url
                         createdAt
                         updatedAt
@@ -113,6 +127,14 @@ export function registerIssueTools(server, client, fieldCache) {
                     return content?.state === args.state;
                 });
             }
+            // Filter by close reason (stateReason)
+            if (args.reason) {
+                const reasonUpper = args.reason.toUpperCase();
+                items = items.filter((item) => {
+                    const content = item.content;
+                    return content?.stateReason === reasonUpper;
+                });
+            }
             // Filter by workflow state
             if (args.workflowState) {
                 items = items.filter((item) => getFieldValue(item, "Workflow State") === args.workflowState);
@@ -144,6 +166,24 @@ export function registerIssueTools(server, client, fieldCache) {
                     return title.includes(q) || body.includes(q);
                 });
             }
+            // Filter by updatedSince
+            if (args.updatedSince) {
+                const since = parseDateMath(args.updatedSince).getTime();
+                items = items.filter((item) => {
+                    const content = item.content;
+                    const updatedAt = content?.updatedAt;
+                    return updatedAt ? new Date(updatedAt).getTime() >= since : false;
+                });
+            }
+            // Filter by updatedBefore
+            if (args.updatedBefore) {
+                const before = parseDateMath(args.updatedBefore).getTime();
+                items = items.filter((item) => {
+                    const content = item.content;
+                    const updatedAt = content?.updatedAt;
+                    return updatedAt ? new Date(updatedAt).getTime() < before : false;
+                });
+            }
             // Sort
             items.sort((a, b) => {
                 const ac = a.content;
@@ -162,7 +202,9 @@ export function registerIssueTools(server, client, fieldCache) {
                     number: content?.number,
                     title: content?.title,
                     state: content?.state,
+                    stateReason: content?.stateReason ?? null,
                     url: content?.url,
+                    updatedAt: content?.updatedAt ?? null,
                     workflowState: getFieldValue(item, "Workflow State"),
                     estimate: getFieldValue(item, "Estimate"),
                     priority: getFieldValue(item, "Priority"),

package/dist/tools/project-tools.js

@@ -6,6 +6,7 @@
  */
 import { z } from "zod";
 import { paginateConnection } from "../lib/pagination.js";
+import { parseDateMath } from "../lib/date-math.js";
 import { toolSuccess, toolError } from "../types.js";
 import { resolveProjectOwner } from "../types.js";
 const WORKFLOW_STATE_OPTIONS = [
@@ -251,6 +252,18 @@ export function registerProjectTools(server, client, fieldCache) {
             .string()
             .optional()
             .describe("Filter by Priority name (P0, P1, P2, P3)"),
+        itemType: z
+            .enum(["ISSUE", "PULL_REQUEST", "DRAFT_ISSUE"])
+            .optional()
+            .describe("Filter by item type (ISSUE, PULL_REQUEST, DRAFT_ISSUE). Omit to include all types."),
+        updatedSince: z
+            .string()
+            .optional()
+            .describe("Include items updated on or after this date. Supports date-math (@today-7d, @now-24h) or ISO dates."),
+        updatedBefore: z
+            .string()
+            .optional()
+            .describe("Include items updated before this date. Supports date-math (@today-7d, @now-24h) or ISO dates."),
         limit: z
             .number()
             .optional()
@@ -272,6 +285,9 @@ export function registerProjectTools(server, client, fieldCache) {
             if (!projectId) {
                 return toolError("Could not resolve project ID");
             }
+            // When filters are active, fetch more items to ensure adequate results after filtering
+            const hasFilters = args.updatedSince || args.updatedBefore || args.itemType;
+            const maxItems = hasFilters ? 500 : (args.limit || 50);
             // Fetch all 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) {
@@ -288,6 +304,7 @@ export function registerProjectTools(server, client, fieldCache) {
                         title
                         state
                         url
+                        updatedAt
                         labels(first: 10) { nodes { name } }
                         assignees(first: 5) { nodes { login } }
                       }
@@ -326,9 +343,13 @@ export function registerProjectTools(server, client, fieldCache) {
                 }
               }
             }
-          }`, { projectId, first: Math.min(args.limit || 50, 100) }, "node.items", { maxItems: args.limit || 50 });
+          }`, { projectId, first: Math.min(maxItems, 100) }, "node.items", { maxItems });
             // Filter items by field values
             let items = itemsResult.nodes;
+            // Filter by item type (broadest filter first to reduce working set)
+            if (args.itemType) {
+                items = items.filter((item) => item.type === args.itemType);
+            }
             if (args.workflowState) {
                 items = items.filter((item) => getFieldValue(item, "Workflow State") === args.workflowState);
             }
@@ -338,6 +359,26 @@ export function registerProjectTools(server, client, fieldCache) {
             if (args.priority) {
                 items = items.filter((item) => getFieldValue(item, "Priority") === args.priority);
             }
+            // Filter by updatedSince
+            if (args.updatedSince) {
+                const since = parseDateMath(args.updatedSince).getTime();
+                items = items.filter((item) => {
+                    const content = item.content;
+                    const updatedAt = content?.updatedAt;
+                    return updatedAt ? new Date(updatedAt).getTime() >= since : false;
+                });
+            }
+            // Filter by updatedBefore
+            if (args.updatedBefore) {
+                const before = parseDateMath(args.updatedBefore).getTime();
+                items = items.filter((item) => {
+                    const content = item.content;
+                    const updatedAt = content?.updatedAt;
+                    return updatedAt ? new Date(updatedAt).getTime() < before : false;
+                });
+            }
+            // Apply limit after filtering
+            items = items.slice(0, args.limit || 50);
             // Format response
             const formattedItems = items.map((item) => {
                 const content = item.content;
@@ -348,6 +389,7 @@ export function registerProjectTools(server, client, fieldCache) {
                     title: content?.title,
                     state: content?.state,
                     url: content?.url,
+                    updatedAt: content?.updatedAt ?? null,
                     workflowState: getFieldValue(item, "Workflow State"),
                     estimate: getFieldValue(item, "Estimate"),
                     priority: getFieldValue(item, "Priority"),

package/package.json

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