ralph-hero-mcp-server 2.4.8 → 2.4.10

package/dist/index.js

@@ -18,6 +18,7 @@ import { registerRelationshipTools } from "./tools/relationship-tools.js";
 import { registerDashboardTools } from "./tools/dashboard-tools.js";
 import { registerBatchTools } from "./tools/batch-tools.js";
 import { registerProjectManagementTools } from "./tools/project-management-tools.js";
+import { registerHygieneTools } from "./tools/hygiene-tools.js";
 /**
  * Initialize the GitHub client from environment variables.
  */
@@ -245,6 +246,8 @@ async function main() {
     registerBatchTools(server, client, fieldCache);
     // Project management tools (archive, remove, add, link repo, clear field)
     registerProjectManagementTools(server, client, fieldCache);
+    // Hygiene reporting tools
+    registerHygieneTools(server, client, fieldCache);
     // Connect via stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/lib/hygiene.js

@@ -0,0 +1,238 @@
+/**
+ * Project hygiene report — pure functions.
+ *
+ * All functions are side-effect-free: DashboardItems in, report data out.
+ * I/O (GraphQL fetching) lives in tools/hygiene-tools.ts.
+ */
+import { TERMINAL_STATES } from "./workflow-states.js";
+export const DEFAULT_HYGIENE_CONFIG = {
+    archiveDays: 14,
+    staleDays: 7,
+    orphanDays: 14,
+    wipLimits: {},
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function ageDays(timestamp, now) {
+    return Math.max(0, (now - new Date(timestamp).getTime()) / (1000 * 60 * 60 * 24));
+}
+function toHygieneItem(item, now) {
+    return {
+        number: item.number,
+        title: item.title,
+        workflowState: item.workflowState,
+        ageDays: Math.round(ageDays(item.updatedAt, now) * 10) / 10,
+    };
+}
+// ---------------------------------------------------------------------------
+// Section functions
+// ---------------------------------------------------------------------------
+/**
+ * Items in terminal states (Done/Canceled) older than archiveDays.
+ */
+export function findArchiveCandidates(items, now, archiveDays) {
+    return items
+        .filter((item) => {
+        const ws = item.workflowState;
+        if (!ws || !TERMINAL_STATES.includes(ws))
+            return false;
+        const ts = item.closedAt ?? item.updatedAt;
+        return ageDays(ts, now) > archiveDays;
+    })
+        .map((item) => toHygieneItem(item, now));
+}
+/**
+ * Non-terminal items not updated for more than staleDays.
+ */
+export function findStaleItems(items, now, staleDays) {
+    return items
+        .filter((item) => {
+        const ws = item.workflowState;
+        if (ws && TERMINAL_STATES.includes(ws))
+            return false;
+        return ageDays(item.updatedAt, now) > staleDays;
+    })
+        .map((item) => toHygieneItem(item, now));
+}
+/**
+ * Backlog items with no assignee older than orphanDays.
+ */
+export function findOrphanedItems(items, now, orphanDays) {
+    return items
+        .filter((item) => {
+        if (item.workflowState !== "Backlog")
+            return false;
+        if (item.assignees.length > 0)
+            return false;
+        return ageDays(item.updatedAt, now) > orphanDays;
+    })
+        .map((item) => toHygieneItem(item, now));
+}
+/**
+ * Non-terminal items missing estimate or priority.
+ */
+export function findFieldGaps(items, now) {
+    const nonTerminal = items.filter((item) => {
+        const ws = item.workflowState;
+        return !ws || !TERMINAL_STATES.includes(ws);
+    });
+    return {
+        missingEstimate: nonTerminal
+            .filter((item) => item.estimate === null)
+            .map((item) => toHygieneItem(item, now)),
+        missingPriority: nonTerminal
+            .filter((item) => item.priority === null)
+            .map((item) => toHygieneItem(item, now)),
+    };
+}
+/**
+ * States where item count exceeds configured WIP limit.
+ */
+export function findWipViolations(items, now, wipLimits) {
+    const violations = [];
+    for (const [state, limit] of Object.entries(wipLimits)) {
+        const stateItems = items.filter((item) => item.workflowState === state);
+        if (stateItems.length > limit) {
+            violations.push({
+                state,
+                count: stateItems.length,
+                limit,
+                items: stateItems.map((item) => toHygieneItem(item, now)),
+            });
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+/**
+ * Build a complete hygiene report from project items.
+ */
+export function buildHygieneReport(items, config = DEFAULT_HYGIENE_CONFIG, now = Date.now()) {
+    const archiveCandidates = findArchiveCandidates(items, now, config.archiveDays);
+    const staleItems = findStaleItems(items, now, config.staleDays);
+    const orphanedItems = findOrphanedItems(items, now, config.orphanDays);
+    const fieldGaps = findFieldGaps(items, now);
+    const wipViolations = findWipViolations(items, now, config.wipLimits);
+    // Field coverage: % of non-terminal items with both estimate AND priority
+    const nonTerminal = items.filter((item) => {
+        const ws = item.workflowState;
+        return !ws || !TERMINAL_STATES.includes(ws);
+    });
+    const withBothFields = nonTerminal.filter((item) => item.estimate !== null && item.priority !== null);
+    const fieldCoveragePercent = nonTerminal.length > 0
+        ? Math.round((withBothFields.length / nonTerminal.length) * 100)
+        : 100;
+    return {
+        generatedAt: new Date(now).toISOString(),
+        totalItems: items.length,
+        archiveCandidates,
+        staleItems,
+        orphanedItems,
+        fieldGaps,
+        wipViolations,
+        summary: {
+            archiveCandidateCount: archiveCandidates.length,
+            staleCount: staleItems.length,
+            orphanCount: orphanedItems.length,
+            fieldCoveragePercent,
+            wipViolationCount: wipViolations.length,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Formatters
+// ---------------------------------------------------------------------------
+function formatItemRow(item) {
+    return `| #${item.number} | ${item.title} | ${item.workflowState ?? "\u2014"} | ${item.ageDays}d |`;
+}
+/**
+ * Render hygiene report as markdown.
+ */
+export function formatHygieneMarkdown(report) {
+    const lines = [];
+    lines.push("# Project Hygiene Report");
+    lines.push(`_Generated: ${report.generatedAt}_`);
+    lines.push("");
+    lines.push(`**Total items**: ${report.totalItems}`);
+    lines.push("");
+    // Summary
+    lines.push("## Summary");
+    lines.push(`- Archive candidates: ${report.summary.archiveCandidateCount}`);
+    lines.push(`- Stale items: ${report.summary.staleCount}`);
+    lines.push(`- Orphaned items: ${report.summary.orphanCount}`);
+    lines.push(`- Field coverage: ${report.summary.fieldCoveragePercent}%`);
+    lines.push(`- WIP violations: ${report.summary.wipViolationCount}`);
+    lines.push("");
+    // Archive candidates
+    if (report.archiveCandidates.length > 0) {
+        lines.push("## Archive Candidates");
+        lines.push("| Issue | Title | State | Age |");
+        lines.push("|-------|-------|-------|-----|");
+        for (const item of report.archiveCandidates) {
+            lines.push(formatItemRow(item));
+        }
+        lines.push("");
+    }
+    // Stale items
+    if (report.staleItems.length > 0) {
+        lines.push("## Stale Items");
+        lines.push("| Issue | Title | State | Age |");
+        lines.push("|-------|-------|-------|-----|");
+        for (const item of report.staleItems) {
+            lines.push(formatItemRow(item));
+        }
+        lines.push("");
+    }
+    // Orphaned items
+    if (report.orphanedItems.length > 0) {
+        lines.push("## Orphaned Items");
+        lines.push("| Issue | Title | State | Age |");
+        lines.push("|-------|-------|-------|-----|");
+        for (const item of report.orphanedItems) {
+            lines.push(formatItemRow(item));
+        }
+        lines.push("");
+    }
+    // Field gaps
+    const totalGaps = report.fieldGaps.missingEstimate.length +
+        report.fieldGaps.missingPriority.length;
+    if (totalGaps > 0) {
+        lines.push("## Field Gaps");
+        if (report.fieldGaps.missingEstimate.length > 0) {
+            lines.push("### Missing Estimate");
+            lines.push("| Issue | Title | State | Age |");
+            lines.push("|-------|-------|-------|-----|");
+            for (const item of report.fieldGaps.missingEstimate) {
+                lines.push(formatItemRow(item));
+            }
+            lines.push("");
+        }
+        if (report.fieldGaps.missingPriority.length > 0) {
+            lines.push("### Missing Priority");
+            lines.push("| Issue | Title | State | Age |");
+            lines.push("|-------|-------|-------|-----|");
+            for (const item of report.fieldGaps.missingPriority) {
+                lines.push(formatItemRow(item));
+            }
+            lines.push("");
+        }
+    }
+    // WIP violations
+    if (report.wipViolations.length > 0) {
+        lines.push("## WIP Violations");
+        for (const v of report.wipViolations) {
+            lines.push(`### ${v.state}: ${v.count} items (limit: ${v.limit})`);
+            lines.push("| Issue | Title | State | Age |");
+            lines.push("|-------|-------|-------|-----|");
+            for (const item of v.items) {
+                lines.push(formatItemRow(item));
+            }
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=hygiene.js.map

package/dist/tools/batch-tools.js

@@ -101,6 +101,28 @@ export function buildBatchFieldValueQuery(projectItemIds) {
     const queryString = `query(${varDecls.join(", ")}) {\n  ${aliases.join("\n  ")}\n}`;
     return { queryString, variables };
 }
+/**
+ * Build an aliased mutation to archive multiple project items
+ * in a single GraphQL call.
+ */
+export function buildBatchArchiveMutation(projectId, itemIds) {
+    const variables = { projectId };
+    const varDecls = ["$projectId: ID!"];
+    const aliases = [];
+    for (let i = 0; i < itemIds.length; i++) {
+        const itemVar = `item_a${i}`;
+        varDecls.push(`$${itemVar}: ID!`);
+        variables[itemVar] = itemIds[i];
+        aliases.push(`a${i}: archiveProjectV2Item(input: {
+        projectId: $projectId,
+        itemId: $${itemVar}
+      }) {
+        item { id }
+      }`);
+    }
+    const mutationString = `mutation(${varDecls.join(", ")}) {\n  ${aliases.join("\n  ")}\n}`;
+    return { mutationString, variables };
+}
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------

package/dist/tools/dashboard-tools.js

@@ -69,7 +69,7 @@ function getFieldValue(item, fieldName) {
 /**
  * Convert raw GraphQL project items to DashboardItem[].
  */
-function toDashboardItems(raw) {
+export function toDashboardItems(raw) {
     const items = [];
     for (const r of raw) {
         // Only include issues (not PRs or drafts)
@@ -94,7 +94,7 @@ function toDashboardItems(raw) {
 // ---------------------------------------------------------------------------
 // GraphQL query for dashboard items
 // ---------------------------------------------------------------------------
-const DASHBOARD_ITEMS_QUERY = `query($projectId: ID!, $cursor: String, $first: Int!) {
+export const DASHBOARD_ITEMS_QUERY = `query($projectId: ID!, $cursor: String, $first: Int!) {
   node(id: $projectId) {
     ... on ProjectV2 {
       items(first: $first, after: $cursor) {

package/dist/tools/hygiene-tools.js

@@ -0,0 +1,92 @@
+/**
+ * MCP tool for project board hygiene reporting.
+ *
+ * Provides a single `ralph_hero__project_hygiene` tool that
+ * identifies archive candidates, stale items, orphaned entries,
+ * field gaps, and WIP violations.
+ */
+import { z } from "zod";
+import { paginateConnection } from "../lib/pagination.js";
+import { ensureFieldCache } from "../lib/helpers.js";
+import { buildHygieneReport, formatHygieneMarkdown, DEFAULT_HYGIENE_CONFIG, } from "../lib/hygiene.js";
+import { DASHBOARD_ITEMS_QUERY, toDashboardItems, } from "./dashboard-tools.js";
+import { toolSuccess, toolError, resolveProjectOwner } from "../types.js";
+// ---------------------------------------------------------------------------
+// Register hygiene tools
+// ---------------------------------------------------------------------------
+export function registerHygieneTools(server, client, fieldCache) {
+    server.tool("ralph_hero__project_hygiene", "Generate a project board hygiene report. Identifies archive candidates, stale items, orphaned backlog entries, missing fields, and WIP violations. Returns: report with 6 sections + summary stats.", {
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner. Defaults to env var"),
+        archiveDays: z
+            .number()
+            .optional()
+            .default(14)
+            .describe("Days before Done/Canceled items become archive candidates (default: 14)"),
+        staleDays: z
+            .number()
+            .optional()
+            .default(7)
+            .describe("Days before non-terminal items are flagged as stale (default: 7)"),
+        orphanDays: z
+            .number()
+            .optional()
+            .default(14)
+            .describe("Days before unassigned Backlog items are flagged as orphaned (default: 14)"),
+        wipLimits: z
+            .record(z.number())
+            .optional()
+            .describe('Per-state WIP limits, e.g. { "In Progress": 3 }'),
+        format: z
+            .enum(["json", "markdown"])
+            .optional()
+            .default("json")
+            .describe("Output format (default: json)"),
+    }, 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");
+            }
+            // Ensure field cache
+            await ensureFieldCache(client, fieldCache, owner, projectNumber);
+            const projectId = fieldCache.getProjectId();
+            if (!projectId) {
+                return toolError("Could not resolve project ID");
+            }
+            // Fetch all project items (reuse dashboard query)
+            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 hygiene config
+            const hygieneConfig = {
+                ...DEFAULT_HYGIENE_CONFIG,
+                archiveDays: args.archiveDays ?? 14,
+                staleDays: args.staleDays ?? 7,
+                orphanDays: args.orphanDays ?? 14,
+                wipLimits: args.wipLimits ?? {},
+            };
+            // Build report
+            const report = buildHygieneReport(dashboardItems, hygieneConfig);
+            // Format output
+            if (args.format === "markdown") {
+                return toolSuccess({
+                    ...report,
+                    formatted: formatHygieneMarkdown(report),
+                });
+            }
+            return toolSuccess(report);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to generate hygiene report: ${message}`);
+        }
+    });
+}
+//# sourceMappingURL=hygiene-tools.js.map

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

@@ -7,6 +7,8 @@
  */
 import { z } from "zod";
 import { toolSuccess, toolError } from "../types.js";
+import { paginateConnection } from "../lib/pagination.js";
+import { buildBatchArchiveMutation } from "./batch-tools.js";
 import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, resolveFullConfig, updateProjectItemField, } from "../lib/helpers.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -752,5 +754,117 @@ export function registerProjectManagementTools(server, client, fieldCache) {
             return toolError(`Failed to delete status update: ${message}`);
         }
     });
+    // -------------------------------------------------------------------------
+    // ralph_hero__bulk_archive
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__bulk_archive", "Archive multiple project items matching workflow state filter. Uses aliased GraphQL mutations for efficiency (chunked at 50). Archived items are hidden from views but not deleted. Returns: archivedCount, items, errors.", {
+        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
+        repo: z.string().optional().describe("Repository name. Defaults to env var"),
+        workflowStates: z
+            .array(z.string())
+            .min(1)
+            .describe('Workflow states to archive (e.g., ["Done", "Canceled"])'),
+        maxItems: z
+            .number()
+            .optional()
+            .default(50)
+            .describe("Max items to archive per invocation (default 50, cap 200)"),
+    }, async (args) => {
+        try {
+            const { projectNumber, projectOwner } = resolveFullConfig(client, args);
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            const projectId = fieldCache.getProjectId();
+            if (!projectId) {
+                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
+                      }
+                      ... on PullRequest {
+                        number
+                        title
+                      }
+                    }
+                    fieldValues(first: 20) {
+                      nodes {
+                        ... on ProjectV2ItemFieldSingleSelectValue {
+                          __typename
+                          name
+                          field { ... on ProjectV2FieldCommon { name } }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }`, { projectId, first: 100 }, "node.items", { maxItems: effectiveMax * 3 });
+            // Filter by workflow state
+            const matched = itemsResult.nodes
+                .filter((item) => {
+                const ws = getBulkArchiveFieldValue(item, "Workflow State");
+                return ws && args.workflowStates.includes(ws);
+            })
+                .slice(0, effectiveMax);
+            if (matched.length === 0) {
+                return toolSuccess({
+                    archivedCount: 0,
+                    items: [],
+                    errors: [],
+                });
+            }
+            // Chunk and execute archive mutations
+            const ARCHIVE_CHUNK_SIZE = 50;
+            const itemIds = matched.map((m) => m.id);
+            const archived = [];
+            const errors = [];
+            for (let i = 0; i < itemIds.length; i += ARCHIVE_CHUNK_SIZE) {
+                const chunk = itemIds.slice(i, i + ARCHIVE_CHUNK_SIZE);
+                const chunkItems = matched.slice(i, i + ARCHIVE_CHUNK_SIZE);
+                try {
+                    const { mutationString, variables } = buildBatchArchiveMutation(projectId, chunk);
+                    await client.projectMutate(mutationString, variables);
+                    for (const item of chunkItems) {
+                        archived.push({
+                            number: item.content?.number,
+                            title: item.content?.title,
+                            itemId: item.id,
+                        });
+                    }
+                }
+                catch (error) {
+                    const msg = error instanceof Error ? error.message : String(error);
+                    errors.push(`Chunk ${Math.floor(i / ARCHIVE_CHUNK_SIZE) + 1} failed: ${msg}`);
+                }
+            }
+            return toolSuccess({
+                archivedCount: archived.length,
+                items: archived,
+                errors,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to bulk archive: ${message}`);
+        }
+    });
+}
+function getBulkArchiveFieldValue(item, fieldName) {
+    const fieldValue = item.fieldValues.nodes.find((fv) => fv.field?.name === fieldName &&
+        fv.__typename === "ProjectV2ItemFieldSingleSelectValue");
+    return fieldValue?.name;
 }
 //# sourceMappingURL=project-management-tools.js.map

package/package.json

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