ralph-hero-mcp-server 2.5.74 → 2.5.75

package/dist/index.js

@@ -20,6 +20,7 @@ import { registerProjectTools } from "./tools/project-tools.js";
 import { registerIssueTools } from "./tools/issue-tools.js";
 import { registerRelationshipTools } from "./tools/relationship-tools.js";
 import { registerDashboardTools } from "./tools/dashboard-tools.js";
+import { registerDirectionsTools } from "./tools/directions-tools.js";
 import { registerBatchTools } from "./tools/batch-tools.js";
 import { registerProjectManagementTools } from "./tools/project-management-tools.js";
 import { registerHygieneTools } from "./tools/hygiene-tools.js";
@@ -386,6 +387,8 @@ async function main() {
     registerRelationshipTools(server, client, fieldCache);
     // Dashboard and pipeline visualization tools
     registerDashboardTools(server, client, fieldCache);
+    // Hello directions tool — deterministic ranked action items
+    registerDirectionsTools(server, client, fieldCache);
     // Phase 5: Batch operations
     registerBatchTools(server, client, fieldCache);
     // Project management tools (archive, remove, add, link repo, clear field)

package/dist/tools/directions-tools.js

@@ -0,0 +1,159 @@
+/**
+ * MCP tool wrapping the pure ranker at `lib/directions.ts`.
+ *
+ * Exposes `ralph_hero__hello_directions`: a single-tool, fixed-shape,
+ * deterministic surface that returns up to N ranked "directions" for the
+ * `hello` skill's session briefing. The skill is responsible for fetching
+ * open PRs (via `gh pr list`) and passing them in as a parameter — the
+ * MCP server does not itself open an Octokit-style PR API surface.
+ *
+ * Behaviour:
+ *   1. Resolve owner + project numbers from args or client config.
+ *   2. For each project, ensure the field cache is populated, then
+ *      paginate `DASHBOARD_ITEMS_QUERY` to gather up to 500 items.
+ *   3. Convert raw items to `DashboardItem[]` via `toDashboardItems`.
+ *   4. Build a `RankConfig` from the args + defaults (with injected `now`).
+ *   5. Compute each PR's `ageHours` at the boundary and call
+ *      `rankDirections(allItems, enrichedPRs, config)`.
+ *   6. Return `{ directions, fetchedAt, totalCandidates }`.
+ *
+ * Determinism: `fetchedAt` is the only time-varying field. Two consecutive
+ * calls on the same board state produce byte-identical `directions[]`
+ * (after stripping `fetchedAt`).
+ */
+import { z } from "zod";
+import { ensureFieldCache } from "../lib/helpers.js";
+import { paginateConnection } from "../lib/pagination.js";
+import { DASHBOARD_ITEMS_QUERY, toDashboardItems, } from "./dashboard-tools.js";
+import { rankDirections, DEFAULT_RANK_CONFIG, } from "../lib/directions.js";
+import { toolSuccess, toolError, resolveProjectOwner, resolveProjectNumbers, } from "../types.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const HOUR_MS = 60 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Register
+// ---------------------------------------------------------------------------
+export function registerDirectionsTools(server, client, fieldCache) {
+    server.tool("ralph_hero__hello_directions", "Compute up to N deterministic 'directions' for the hello skill's session briefing. Single tool call returns a fixed-shape JSON payload with ranked issue/PR action items. Open PRs must be passed in as a parameter (the MCP server does not fetch them itself).", {
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner. Defaults to RALPH_GH_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."),
+        limit: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .default(3)
+            .describe("Max directions to return (default: 3)."),
+        stuckThresholdHours: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(48)
+            .describe("Hours before a non-lock issue is considered stale (default: 48)."),
+        lockStaleHours: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(24)
+            .describe("Hours before a lock-state issue is considered stalled (default: 24)."),
+        treeRecentDoneDays: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(7)
+            .describe("Days within which a sibling Done event still pulls a tree forward (default: 7)."),
+        prStaleHours: z
+            .number()
+            .nonnegative()
+            .optional()
+            .default(24)
+            .describe("Hours before an open PR is considered stale (default: 24)."),
+        openPRs: z
+            .array(z.object({
+            number: z.number(),
+            title: z.string(),
+            url: z.string(),
+            isDraft: z.boolean(),
+            reviewDecision: z
+                .string()
+                .nullable()
+                .describe("REVIEW_REQUIRED | APPROVED | CHANGES_REQUESTED | null"),
+            headRefName: z.string(),
+            createdAt: z
+                .string()
+                .describe("ISO timestamp from gh pr list"),
+        }))
+            .optional()
+            .default([])
+            .describe("Open PRs gathered by the caller (e.g. via `gh pr list`). Drafts and APPROVED PRs are filtered internally."),
+    }, async (args) => {
+        try {
+            const owner = args.owner || resolveProjectOwner(client.config);
+            if (!owner) {
+                return toolError("owner is required");
+            }
+            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.");
+            }
+            // Inject `now` at the boundary so the lib remains deterministic.
+            const now = new Date();
+            const allItems = [];
+            for (const pn of projectNumbers) {
+                await ensureFieldCache(client, fieldCache, owner, pn);
+                const projectId = fieldCache.getProjectId(pn);
+                if (!projectId) {
+                    // Defensive: ensureFieldCache succeeded but no projectId.
+                    // Skip this project rather than blowing up the whole call.
+                    continue;
+                }
+                const result = await paginateConnection((q, v) => client.projectQuery(q, v), DASHBOARD_ITEMS_QUERY, { projectId, first: 100 }, "node.items", { maxItems: 500 });
+                allItems.push(...toDashboardItems(result.nodes, pn));
+            }
+            // Build the RankConfig from args + defaults + injected `now`.
+            const config = {
+                limit: args.limit ?? DEFAULT_RANK_CONFIG.limit,
+                stuckThresholdHours: args.stuckThresholdHours ?? DEFAULT_RANK_CONFIG.stuckThresholdHours,
+                lockStaleHours: args.lockStaleHours ?? DEFAULT_RANK_CONFIG.lockStaleHours,
+                treeRecentDoneDays: args.treeRecentDoneDays ?? DEFAULT_RANK_CONFIG.treeRecentDoneDays,
+                prStaleHours: args.prStaleHours ?? DEFAULT_RANK_CONFIG.prStaleHours,
+                now,
+            };
+            // Compute PR ageHours at the boundary so the lib never reads the wall clock.
+            const enrichedPRs = (args.openPRs ?? []).map((pr) => {
+                const t = new Date(pr.createdAt).getTime();
+                const ageHours = Number.isNaN(t)
+                    ? 0
+                    : Math.max(0, (now.getTime() - t) / HOUR_MS);
+                return {
+                    number: pr.number,
+                    title: pr.title,
+                    url: pr.url,
+                    isDraft: pr.isDraft,
+                    reviewDecision: pr.reviewDecision,
+                    headRefName: pr.headRefName,
+                    createdAt: pr.createdAt,
+                    ageHours,
+                };
+            });
+            const directions = rankDirections(allItems, enrichedPRs, config);
+            return toolSuccess({
+                directions,
+                fetchedAt: now.toISOString(),
+                totalCandidates: allItems.length,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to compute hello directions: ${message}`);
+        }
+    });
+}
+//# sourceMappingURL=directions-tools.js.map

package/package.json

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