@aaronsb/jira-cloud-mcp 0.5.3 → 0.5.4

package/build/client/jira-client.js

@@ -84,6 +84,7 @@ export class JiraClient {
             'created',
             'updated',
             'resolutiondate',
+            'statuscategorychangedate',
             'duedate',
             this.customFields.startDate,
             this.customFields.storyPoints,
@@ -110,6 +111,7 @@ export class JiraClient {
             created: fields?.created || '',
             updated: fields?.updated || '',
             resolutionDate: fields?.resolutiondate || null,
+            statusCategoryChanged: fields?.statuscategorychangedate ?? fields?.statuscategorychangeddate ?? null,
             dueDate: fields?.duedate || null,
             startDate: fields?.[this.customFields.startDate] || null,
             storyPoints: fields?.[this.customFields.storyPoints] ?? null,
@@ -431,7 +433,7 @@ export class JiraClient {
             const leanFields = [
                 'summary', 'issuetype', 'priority', 'assignee', 'reporter',
                 'status', 'resolution', 'labels', 'created', 'updated',
-                'resolutiondate', 'duedate', 'timeestimate',
+                'resolutiondate', 'statuscategorychangedate', 'duedate', 'timeestimate',
                 this.customFields.startDate, this.customFields.storyPoints,
             ];
             const params = {

package/build/docs/tool-documentation.js

@@ -483,7 +483,7 @@ function generateAnalysisToolDocumentation(schema) {
             },
             compute: {
                 type: "array of strings",
-                description: "Computed columns for summary tables. Each: 'name = expr'. Arithmetic, comparisons, column refs. Implicit measures: bugs, unassigned, no_due_date, no_estimate, no_start_date, no_labels, blocked.",
+                description: "Computed columns for summary tables. Each: 'name = expr'. Arithmetic, comparisons, column refs. Implicit measures: bugs, unassigned, no_due_date, no_estimate, no_start_date, no_labels, blocked, stale, stale_status, backlog_rot.",
             },
             maxResults: {
                 type: "integer",

package/build/handlers/analysis-handler.js

@@ -210,6 +210,48 @@ export function renderCycle(issues, now) {
             .slice(0, 5);
         const oldestStr = oldest.map(o => `${o.key} (${o.age}d)`).join(', ');
         lines.push(`**Oldest open:** ${oldestStr}`);
+        // Staleness — how long since last update
+        const staleness = open.map(i => ({
+            key: i.key,
+            days: daysBetween(parseDate(i.updated), now),
+        }));
+        const buckets = { fresh: 0, aging: 0, stale: 0, abandoned: 0 };
+        for (const s of staleness) {
+            if (s.days < 7)
+                buckets.fresh++;
+            else if (s.days < 30)
+                buckets.aging++;
+            else if (s.days < 90)
+                buckets.stale++;
+            else
+                buckets.abandoned++;
+        }
+        lines.push(`**Staleness:** <7d: ${buckets.fresh} | 7-30d: ${buckets.aging} | 30-90d: ${buckets.stale} | 90d+: ${buckets.abandoned}`);
+        // Most stale open issues
+        const mostStale = staleness
+            .sort((a, b) => b.days - a.days)
+            .slice(0, 5);
+        if (mostStale.length > 0 && mostStale[0].days >= 30) {
+            const staleStr = mostStale.map(s => `${s.key} (${s.days}d)`).join(', ');
+            lines.push(`**Most stale:** ${staleStr}`);
+        }
+        // Status age — how long in current status
+        const withStatusAge = open.filter(i => i.statusCategoryChanged);
+        if (withStatusAge.length > 0) {
+            const statusAges = withStatusAge.map(i => daysBetween(parseDate(i.statusCategoryChanged), now));
+            const med = median(statusAges);
+            const avg = mean(statusAges);
+            lines.push(`**Status age:** median ${med.toFixed(1)} days, mean ${avg.toFixed(1)} days in current status (${withStatusAge.length} issues)`);
+            const stuck = withStatusAge
+                .map(i => ({ key: i.key, status: i.status, days: daysBetween(parseDate(i.statusCategoryChanged), now) }))
+                .filter(s => s.days >= 30)
+                .sort((a, b) => b.days - a.days)
+                .slice(0, 5);
+            if (stuck.length > 0) {
+                const stuckStr = stuck.map(s => `${s.key} ${s.status} (${s.days}d)`).join(', ');
+                lines.push(`**Stuck:** ${stuckStr}`);
+            }
+        }
     }
     return lines.join('\n');
 }
@@ -271,6 +313,9 @@ function buildImplicitMeasures(customFieldIds) {
         no_due_date: 'dueDate is EMPTY AND resolution = Unresolved',
         blocked: 'status = Blocked',
         no_labels: 'labels is EMPTY AND resolution = Unresolved',
+        stale: 'resolution = Unresolved AND updated <= -60d',
+        stale_status: 'resolution = Unresolved AND statusCategoryChangedDate <= -30d',
+        backlog_rot: 'resolution = Unresolved AND dueDate is EMPTY AND assignee is EMPTY AND updated <= -60d',
     };
     if (customFieldIds) {
         measures.no_estimate = `${customFieldIds.storyPoints} is EMPTY AND resolution = Unresolved`;
@@ -471,7 +516,7 @@ export function renderCubeSetup(jql, sampleSize, dimensions) {
     lines.push('- total, open, overdue, high+, created_7d, resolved_7d');
     lines.push('');
     lines.push('Implicit measures (lazily resolved if referenced in `compute`):');
-    lines.push('- bugs, unassigned, no_due_date, no_estimate, no_start_date, no_labels, blocked');
+    lines.push('- bugs, unassigned, no_due_date, no_estimate, no_start_date, no_labels, blocked, stale, stale_status, backlog_rot');
     // Suggested cubes with cost estimates
     lines.push('');
     lines.push(`## Suggested Cubes (budget: ${MAX_COUNT_QUERIES} queries)`);
@@ -639,7 +684,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
         }
     }
     // Next steps
-    const nextSteps = analysisNextSteps(jql, allIssues.slice(0, 3).map(i => i.key));
+    const nextSteps = analysisNextSteps(jql, allIssues.slice(0, 3).map(i => i.key), truncated);
     lines.push(nextSteps);
     return {
         content: [{

package/build/handlers/resource-handlers.js

@@ -430,6 +430,13 @@ Use \`manage_jira_filter\` with \`execute_jql\` for this one:
 \`\`\`
 Blocked lists tend to be small but each one is a potential cascade. Oldest first surfaces the longest-stuck items for escalation.
 
+### Data Quality / Backlog Rot
+**Question:** How much of this backlog is noise?
+\`\`\`json
+{ "jql": "project in (...) AND resolution = Unresolved", "metrics": ["summary"], "groupBy": "project", "compute": ["stale_pct = stale / open * 100", "rot_pct = backlog_rot / open * 100"] }
+\`\`\`
+\`stale\` = untouched 60+ days. \`backlog_rot\` = undated + unassigned + untouched 60+ days. High rot_pct means overdue counts are misleading — the backlog is full of phantom work.
+
 ## Data Cube
 
 For multi-dimensional analysis, use the two-phase cube pattern:
@@ -449,7 +456,7 @@ Returns available dimensions, their values, cost estimates, and query budget.
 - Arithmetic: \`+\`, \`-\`, \`*\`, \`/\` (division by zero = 0)
 - Comparisons: \`>\`, \`<\`, \`>=\`, \`<=\`, \`==\`, \`!=\` (produce Yes/No — cannot be summed or averaged)
 - Standard columns: total, open, overdue, high, created_7d, resolved_7d
-- Implicit measures (lazily resolved via count API): bugs, unassigned, no_due_date, no_estimate, no_start_date, no_labels, blocked
+- Implicit measures (lazily resolved via count API): bugs, unassigned, no_due_date, no_estimate, no_start_date, no_labels, blocked, stale (untouched 60d+), stale_status (stuck in status 30d+), backlog_rot (undated+unassigned+untouched 60d+)
 - Max 5 expressions per query, 150-query budget per execution
 - Expressions evaluate linearly — later expressions can reference earlier ones
 

package/build/index.js

@@ -2,7 +2,7 @@
 import { createRequire } from 'module';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { fieldDiscovery } from './client/field-discovery.js';
 import { JiraClient } from './client/jira-client.js';
 import { handleAnalysisRequest } from './handlers/analysis-handler.js';
@@ -13,6 +13,8 @@ import { handleProjectRequest } from './handlers/project-handlers.js';
 import { createQueueHandler } from './handlers/queue-handler.js';
 import { setupResourceHandlers } from './handlers/resource-handlers.js';
 import { handleSprintRequest } from './handlers/sprint-handlers.js';
+import { promptDefinitions } from './prompts/prompt-definitions.js';
+import { getPrompt } from './prompts/prompt-messages.js';
 import { toolSchemas } from './schemas/tool-schemas.js';
 // Jira credentials from environment variables
 const JIRA_EMAIL = process.env.JIRA_EMAIL;
@@ -43,6 +45,7 @@ class JiraServer {
             capabilities: {
                 tools: {},
                 resources: {},
+                prompts: {},
             },
         });
         this.jiraClient = new JiraClient({
@@ -80,6 +83,18 @@ class JiraServer {
         this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             return resourceHandlers.readResource(request.params.uri);
         });
+        // Set up prompt handlers
+        this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+            prompts: promptDefinitions.map(p => ({
+                name: p.name,
+                description: p.description,
+                arguments: p.arguments,
+            })),
+        }));
+        this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            return getPrompt(name, args);
+        });
         // Set up tool handlers
         this.server.setRequestHandler(CallToolRequestSchema, async (request, _extra) => {
             console.error('Received request:', JSON.stringify(request, null, 2));

package/build/prompts/prompt-definitions.js

@@ -0,0 +1,34 @@
+/**
+ * MCP Prompt definitions for Jira analysis workflows.
+ * Prompts are user-controlled templates surfaced by clients as slash commands or menu items.
+ */
+export const promptDefinitions = [
+    {
+        name: 'backlog_health',
+        description: 'Run a data quality health check on a project backlog — surfaces rot, staleness, and planning gaps',
+        arguments: [
+            { name: 'project', description: 'Jira project key (e.g. PROJ, ENG)', required: true },
+        ],
+    },
+    {
+        name: 'contributor_workload',
+        description: 'Per-contributor workload breakdown with staleness and risk — scopes detail queries to fit within sample cap',
+        arguments: [
+            { name: 'project', description: 'Jira project key (e.g. PROJ, ENG)', required: true },
+        ],
+    },
+    {
+        name: 'sprint_review',
+        description: 'Sprint review preparation — velocity, scope changes, at-risk items, and completion forecast',
+        arguments: [
+            { name: 'board_id', description: 'Jira board ID (find via manage_jira_board list)', required: true },
+        ],
+    },
+    {
+        name: 'narrow_analysis',
+        description: 'Refine a capped analysis query — guides you to narrow JQL for precise detail metrics',
+        arguments: [
+            { name: 'jql', description: 'The JQL query to refine (from a previous capped analysis)', required: true },
+        ],
+    },
+];

package/build/prompts/prompt-messages.js

@@ -0,0 +1,111 @@
+/**
+ * Builds PromptMessage arrays for each prompt, substituting user-provided arguments.
+ */
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { promptDefinitions } from './prompt-definitions.js';
+function msg(text) {
+    return { role: 'user', content: { type: 'text', text } };
+}
+const builders = {
+    backlog_health({ project }) {
+        return {
+            description: `Backlog health check for ${project}`,
+            messages: [msg(`Analyze backlog health for project ${project}. Use the analyze_jira_issues and manage_jira_filter tools.
+
+Step 1 — Summary with data quality signals:
+{"jql":"project = ${project} AND resolution = Unresolved","metrics":["summary"],"groupBy":"priority","compute":["rot_pct = backlog_rot / open * 100","stale_pct = stale / open * 100","gap_pct = no_estimate / open * 100"]}
+
+Step 2 — Cycle metrics for staleness distribution and status age:
+{"jql":"project = ${project} AND resolution = Unresolved","metrics":["cycle"],"maxResults":100}
+
+Step 3 — Summarize findings:
+- What percentage of the backlog is rotting (no owner, no dates, untouched)?
+- What's stuck in the same status for 30+ days?
+- What's missing estimates or start dates?
+- Flag the worst offenders by issue key.
+- Recommend specific triage actions.`)],
+        };
+    },
+    contributor_workload({ project }) {
+        return {
+            description: `Contributor workload for ${project}`,
+            messages: [msg(`Analyze contributor workload for project ${project}. Use the analyze_jira_issues tool.
+
+Step 1 — Assignee distribution with quality signals:
+{"jql":"project = ${project} AND resolution = Unresolved","metrics":["summary"],"groupBy":"assignee","compute":["stale_pct = stale / open * 100","blocked_pct = blocked / open * 100"]}
+
+Step 2 — For the top 3 assignees by open issue count, run scoped detail metrics:
+{"jql":"project = ${project} AND resolution = Unresolved AND assignee = '{name}'","metrics":["cycle","schedule"]}
+
+This pattern keeps each detail query within the sample cap for precise results.
+
+Step 3 — Summarize:
+- Who has the most open work?
+- Who has the most stale or at-risk issues?
+- Are there load imbalances?
+- What needs reassignment or triage?`)],
+        };
+    },
+    sprint_review({ board_id }) {
+        return {
+            description: `Sprint review prep for board ${board_id}`,
+            messages: [msg(`Prepare a sprint review for board ${board_id}. Use manage_jira_sprint and analyze_jira_issues tools.
+
+Step 1 — Find the active sprint:
+{"operation":"list","boardId":${board_id},"state":"active"}
+
+Step 2 — Analyze sprint issues (use the sprint ID from step 1):
+{"jql":"sprint = {sprintId}","metrics":["summary","points","schedule"],"compute":["done_pct = resolved_7d / total * 100"]}
+
+Step 3 — Summarize:
+- Current velocity vs planned
+- Scope changes (items added/removed mid-sprint)
+- At-risk items (overdue, blocked, stale)
+- Completion forecast — will the sprint goal be met?`)],
+        };
+    },
+    narrow_analysis({ jql }) {
+        return {
+            description: 'Refine a capped analysis query',
+            messages: [msg(`The previous analysis was sampled — detail metrics didn't cover all matching issues.
+
+Original query: ${jql}
+
+To get precise results, help me narrow the query. Here are useful approaches:
+
+By assignee (each person's list usually fits within the cap):
+{"jql":"${jql} AND assignee = currentUser()","metrics":["cycle","schedule"]}
+
+By priority (focus on what matters):
+{"jql":"${jql} AND priority in (High, Highest)","metrics":["cycle","schedule"]}
+
+By issue type:
+{"jql":"${jql} AND issuetype = Bug","metrics":["cycle"]}
+
+By recency:
+{"jql":"${jql} AND created >= -30d","metrics":["cycle"]}
+
+Or use summary metrics for the full population (count API, no cap):
+{"jql":"${jql}","metrics":["summary"],"groupBy":"assignee","compute":["stale_pct = stale / open * 100"]}
+
+Ask me which dimension I'd like to drill into, or suggest the most useful one based on the original query.`)],
+        };
+    },
+};
+export function getPrompt(name, args) {
+    const def = promptDefinitions.find(p => p.name === name);
+    if (!def) {
+        throw new McpError(ErrorCode.InvalidParams, `Unknown prompt: ${name}`);
+    }
+    const resolvedArgs = args ?? {};
+    for (const arg of def.arguments) {
+        if (arg.required && !resolvedArgs[arg.name]) {
+            throw new McpError(ErrorCode.InvalidParams, `Missing required argument: ${arg.name}`);
+        }
+    }
+    const builder = builders[name];
+    if (!builder) {
+        throw new Error(`No message builder for prompt: ${name}`);
+    }
+    return builder(resolvedArgs);
+}

package/build/schemas/tool-schemas.js

@@ -350,7 +350,7 @@ export const toolSchemas = {
                 compute: {
                     type: 'array',
                     items: { type: 'string' },
-                    description: 'Computed columns for cube execute. Each entry: "name = expr". Arithmetic (+,-,*,/), comparisons (>,<,>=,<=,==,!=). Column refs: total, open, overdue, high, created_7d, resolved_7d. Implicit measures resolved lazily: bugs, unassigned, no_due_date, no_estimate, no_start_date, no_labels, blocked. Max 5 expressions. Example: ["bug_pct = bugs / total * 100", "planning_gap = no_estimate / open * 100"].',
+                    description: 'Computed columns for cube execute. Each entry: "name = expr". Arithmetic (+,-,*,/), comparisons (>,<,>=,<=,==,!=). Column refs: total, open, overdue, high, created_7d, resolved_7d. Implicit measures resolved lazily: bugs, unassigned, no_due_date, no_estimate, no_start_date, no_labels, blocked, stale (untouched 60d+), stale_status (stuck in status 30d+), backlog_rot (undated+unassigned+untouched 60d+). Max 5 expressions. Example: ["bug_pct = bugs / total * 100", "rot_pct = backlog_rot / open * 100"].',
                     maxItems: 5,
                 },
                 maxResults: {

package/build/utils/next-steps.js

@@ -125,11 +125,14 @@ export function boardNextSteps(operation, boardId) {
     }
     return steps.length > 0 ? formatSteps(steps) : '';
 }
-export function analysisNextSteps(jql, issueKeys) {
+export function analysisNextSteps(jql, issueKeys, truncated = false) {
     const steps = [];
     if (issueKeys.length > 0) {
         steps.push({ description: 'Get details on a specific issue', tool: 'manage_jira_issue', example: { operation: 'get', issueKey: issueKeys[0] } });
     }
     steps.push({ description: 'Discover dimensions for cube analysis', tool: 'analyze_jira_issues', example: { jql, metrics: ['cube_setup'] } }, { description: 'Add computed columns', tool: 'analyze_jira_issues', example: { jql, metrics: ['summary'], groupBy: 'project', compute: ['bug_pct = bugs / total * 100'] } }, { description: 'Narrow the analysis with refined JQL', tool: 'analyze_jira_issues', example: { jql: `${jql} AND priority = High` } }, { description: 'View the full issue list', tool: 'manage_jira_filter', example: { operation: 'execute_jql', jql } });
+    if (truncated) {
+        steps.push({ description: 'Detail metrics are sampled — narrow JQL by assignee, priority, or type for precise results. Use summary metrics (count API) for whole-project totals', tool: 'analyze_jira_issues', example: { jql: `${jql} AND assignee = currentUser()`, metrics: ['cycle'] } });
+    }
     return formatSteps(steps) + '\n- Read `jira://analysis/recipes` for data cube patterns and compute DSL examples';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaronsb/jira-cloud-mcp",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "mcpName": "io.github.aaronsb/jira-cloud",
   "description": "Model Context Protocol (MCP) server for Jira Cloud - enables AI assistants to interact with Jira",
   "type": "module",