@aaronsb/jira-cloud-mcp 0.5.10 → 0.5.11

package/build/client/jira-client.js

@@ -104,6 +104,7 @@ export class JiraClient {
             people.push({ displayName: fields.reporter.displayName, accountId: fields.reporter.accountId, role: 'reporter' });
         }
         return {
+            id: issue.id,
             key: issue.key,
             summary: fields?.summary,
             description: fields?.description
@@ -410,6 +411,38 @@ export class JiraClient {
             url: attachment.content || '',
         }));
     }
+    async getBulkChangelogs(issueKeys, fieldIds = ['status']) {
+        const result = new Map();
+        let nextPageToken;
+        do {
+            const response = await this.client.issues.getBulkChangelogs({
+                issueIdsOrKeys: issueKeys,
+                fieldIds,
+                maxResults: 1000,
+                nextPageToken,
+            });
+            for (const issueLog of response.issueChangeLogs || []) {
+                const issueId = issueLog.issueId;
+                if (!issueId)
+                    continue;
+                const transitions = result.get(issueId) || [];
+                for (const history of issueLog.changeHistories || []) {
+                    for (const item of history.items || []) {
+                        if (item.field === 'status') {
+                            transitions.push({
+                                date: history.created || '',
+                                from: item.fromString || '',
+                                to: item.toString || '',
+                            });
+                        }
+                    }
+                }
+                result.set(issueId, transitions);
+            }
+            nextPageToken = response.nextPageToken ?? undefined;
+        } while (nextPageToken);
+        return result;
+    }
     async getFilter(filterId) {
         return await this.client.filters.getFilter({
             id: parseInt(filterId, 10),

package/build/docs/tool-documentation.js

@@ -528,6 +528,14 @@ function generateAnalysisToolDocumentation(schema) {
                     { description: "Summary only", code: { jql: "project = AA", metrics: ["summary"] } },
                 ],
             },
+            {
+                title: "Flow analysis — where do issues get stuck?",
+                description: "Analyze status transitions, time in status, and bounce patterns:",
+                steps: [
+                    { description: "Flow metrics", code: { jql: "project = AA AND resolution = Unresolved", metrics: ["flow"] } },
+                    { description: "Combined with summary", code: { jql: "project = AA", metrics: ["summary", "flow"], groupBy: "issuetype" } },
+                ],
+            },
             {
                 title: "Data cube — discover then compute",
                 description: "Two-phase analysis with computed columns:",

package/build/handlers/analysis-handler.js

@@ -3,6 +3,7 @@ import { evaluateRow, extractColumnRefs, parseComputeList } from '../utils/cube-
 import { analysisNextSteps } from '../utils/next-steps.js';
 import { normalizeArgs } from '../utils/normalize-args.js';
 const ALL_METRICS = ['points', 'time', 'schedule', 'cycle', 'distribution'];
+// flow is opt-in only — requires extra bulk changelog API call
 const VALID_GROUP_BY = ['project', 'assignee', 'priority', 'issuetype'];
 const MAX_ISSUES_HARD = 500; // absolute ceiling for detail metrics — beyond this, context explodes
 const MAX_ISSUES_DEFAULT = 100;
@@ -271,6 +272,100 @@ export function renderDistribution(issues, groupLimit = DEFAULT_GROUP_LIMIT) {
     lines.push(`**By type:** ${mapToString(byType, ' | ', groupLimit)}`);
     return lines.join('\n');
 }
+export async function renderFlow(jiraClient, issues) {
+    if (issues.length === 0)
+        return '## Flow\n\nNo issues to analyze.';
+    const issueKeys = issues.map(i => i.key);
+    // Build a map of issue key → issue ID for matching bulk response
+    const keyToId = new Map();
+    const idToKey = new Map();
+    for (const issue of issues) {
+        if (issue.id) {
+            keyToId.set(issue.key, issue.id);
+            idToKey.set(issue.id, issue.key);
+        }
+    }
+    const changelogs = await jiraClient.getBulkChangelogs(issueKeys);
+    // Aggregate per-status stats
+    const statusStats = new Map();
+    const issueBounceCounts = new Map(); // issueId → status → entry count
+    let totalTransitions = 0;
+    for (const [issueId, transitions] of changelogs) {
+        if (transitions.length === 0)
+            continue;
+        totalTransitions += transitions.length;
+        // Sort transitions by date
+        const sorted = [...transitions].sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
+        // Track entries per status for this issue
+        const issueStatusEntries = new Map();
+        for (let i = 0; i < sorted.length; i++) {
+            const t = sorted[i];
+            const toStatus = t.to;
+            // Count entries into the target status
+            issueStatusEntries.set(toStatus, (issueStatusEntries.get(toStatus) || 0) + 1);
+            // Calculate time spent in the target status
+            const enteredAt = new Date(t.date).getTime();
+            const exitedAt = i + 1 < sorted.length
+                ? new Date(sorted[i + 1].date).getTime()
+                : Date.now();
+            const daysIn = (exitedAt - enteredAt) / (1000 * 60 * 60 * 24);
+            const stats = statusStats.get(toStatus) || { status: toStatus, entries: 0, totalDaysIn: 0, issueCount: 0, bounces: 0 };
+            stats.entries++;
+            stats.totalDaysIn += daysIn;
+            statusStats.set(toStatus, stats);
+        }
+        issueBounceCounts.set(issueId, issueStatusEntries);
+    }
+    // Count distinct issues and bounces per status
+    const issuesPerStatus = new Map();
+    for (const [issueId, statusEntries] of issueBounceCounts) {
+        for (const [status, count] of statusEntries) {
+            if (!issuesPerStatus.has(status))
+                issuesPerStatus.set(status, new Set());
+            issuesPerStatus.get(status).add(issueId);
+            const stats = statusStats.get(status);
+            if (stats && count > 1) {
+                stats.bounces += count - 1;
+            }
+        }
+    }
+    for (const [status, issueSet] of issuesPerStatus) {
+        const stats = statusStats.get(status);
+        if (stats)
+            stats.issueCount = issueSet.size;
+    }
+    if (statusStats.size === 0) {
+        return '## Flow\n\nNo status transitions found in these issues.';
+    }
+    // Render table
+    const lines = ['## Flow (Status Transitions)', ''];
+    lines.push(`${totalTransitions} transitions across ${changelogs.size} issues`);
+    lines.push('');
+    lines.push('| Status | Entries | Avg days in | Bounce rate | Issues |');
+    lines.push('|--------|--------:|------------:|------------:|-------:|');
+    const sorted = [...statusStats.values()].sort((a, b) => b.entries - a.entries);
+    for (const s of sorted) {
+        const avgDays = s.entries > 0 ? (s.totalDaysIn / s.entries).toFixed(1) : '—';
+        const bounceRate = s.issueCount > 0 ? Math.round((s.bounces / s.issueCount) * 100) : 0;
+        lines.push(`| ${s.status} | ${s.entries} | ${avgDays} | ${bounceRate}% | ${s.issueCount} |`);
+    }
+    // Top bouncers — issues with most re-entries to any status
+    const bouncerScores = [];
+    for (const [issueId, statusEntries] of issueBounceCounts) {
+        const totalBounces = [...statusEntries.values()].reduce((sum, count) => sum + Math.max(0, count - 1), 0);
+        if (totalBounces > 0) {
+            const key = idToKey.get(issueId) || issueId;
+            bouncerScores.push({ key, bounces: totalBounces });
+        }
+    }
+    if (bouncerScores.length > 0) {
+        bouncerScores.sort((a, b) => b.bounces - a.bounces);
+        const top = bouncerScores.slice(0, 5);
+        lines.push('');
+        lines.push(`**Top bouncers:** ${top.map(b => `${b.key} (${b.bounces}×)`).join(', ')}`);
+    }
+    return lines.join('\n');
+}
 /** Extract project keys from JQL like "project in (AA, GC, GD)" or "project = AA" */
 export function extractProjectKeys(jql) {
     // project in (AA, GC, GD)
@@ -622,9 +717,12 @@ export async function handleAnalysisRequest(jiraClient, request) {
         : [];
     const hasSummary = requested.includes('summary');
     const hasCubeSetup = requested.includes('cube_setup');
+    const hasFlow = requested.includes('flow');
     const fetchMetrics = requested.length > 0
         ? requested.filter(m => ALL_METRICS.includes(m))
         : ALL_METRICS;
+    // flow needs issue fetching but isn't in ALL_METRICS (opt-in only)
+    const needsIssueFetch = fetchMetrics.length > 0 || hasFlow;
     // Parse groupBy
     const groupBy = (typeof args.groupBy === 'string' && VALID_GROUP_BY.includes(args.groupBy))
         ? args.groupBy
@@ -649,8 +747,8 @@ export async function handleAnalysisRequest(jiraClient, request) {
                 }],
         };
     }
-    // If only summary requested, skip issue fetching entirely
-    if (hasSummary && fetchMetrics.length === 0) {
+    // If only summary requested (no flow or detail metrics), skip issue fetching entirely
+    if (hasSummary && !needsIssueFetch) {
         const summaryText = await handleSummary(jiraClient, jql, groupBy, compute, groupLimit);
         const nextSteps = analysisNextSteps(jql, [], false, groupBy, filterSource);
         const banner = filterSource ? `*Using saved filter: ${filterSource}*\n\n` : '';
@@ -708,7 +806,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
         lines.push(summaryText);
     }
     // Header for fetch-based metrics
-    if (fetchMetrics.length > 0 && allIssues.length > 0) {
+    if ((fetchMetrics.length > 0 || hasFlow) && allIssues.length > 0) {
         if (hasSummary)
             lines.push('');
         lines.push(`# Detail: ${jql}`);
@@ -729,6 +827,11 @@ export async function handleAnalysisRequest(jiraClient, request) {
             lines.push(renderers[metric]());
         }
     }
+    // Flow is opt-in and requires async bulk changelog fetch
+    if (hasFlow && allIssues.length > 0) {
+        lines.push('');
+        lines.push(await renderFlow(jiraClient, allIssues));
+    }
     // Next steps
     const nextSteps = analysisNextSteps(jql, allIssues.slice(0, 3).map(i => i.key), truncated, groupBy, filterSource);
     lines.push(nextSteps);

package/build/prompts/prompt-messages.js

@@ -19,8 +19,8 @@ Operation 0 — Save the query as a reusable filter:
 Operation 1 — Summary with data quality signals (uses $0.filterId):
 {"tool":"analyze_jira_issues","args":{"filterId":"$0.filterId","metrics":["summary"],"groupBy":"priority","compute":["rot_pct = backlog_rot / open * 100","stale_pct = stale / open * 100","gap_pct = no_estimate / open * 100"]}}
 
-Operation 2 — Cycle metrics for staleness distribution:
-{"tool":"analyze_jira_issues","args":{"filterId":"$0.filterId","metrics":["cycle"],"maxResults":100}}
+Operation 2 — Flow analysis for transition patterns and bottlenecks:
+{"tool":"analyze_jira_issues","args":{"filterId":"$0.filterId","metrics":["flow"],"maxResults":100}}
 
 After the pipeline completes, summarize findings:
 - What percentage of the backlog is rotting (no owner, no dates, untouched)?

package/build/schemas/tool-schemas.js

@@ -326,7 +326,7 @@ export const toolSchemas = {
     },
     analyze_jira_issues: {
         name: 'analyze_jira_issues',
-        description: 'Compute project metrics over issues selected by JQL or a saved filter. For counting and breakdown questions ("how many by status/assignee/priority"), use metrics: ["summary"] with groupBy — this gives exact counts with no issue cap. Use detail metrics (points, time, schedule, cycle, distribution) only when you need per-issue analysis; these are capped at maxResults issues. Always prefer this tool over manage_jira_filter or manage_jira_project for quantitative questions. Tip: save complex JQL as a filter with manage_jira_filter, then reuse the filterId here for repeated analysis. Read jira://analysis/recipes for composition patterns.',
+        description: 'Compute project metrics over issues selected by JQL or a saved filter. For counting and breakdown questions ("how many by status/assignee/priority"), use metrics: ["summary"] with groupBy — this gives exact counts with no issue cap. Use detail metrics (points, time, schedule, cycle, distribution) for per-issue analysis (capped at maxResults). Use flow for status transition patterns — how issues move through statuses, where they bounce, and how long they stay. Tip: save complex JQL as a filter with manage_jira_filter, then reuse the filterId here for repeated analysis. Read jira://analysis/recipes for composition patterns.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -342,9 +342,9 @@ export const toolSchemas = {
                     type: 'array',
                     items: {
                         type: 'string',
-                        enum: ['summary', 'points', 'time', 'schedule', 'cycle', 'distribution', 'cube_setup'],
+                        enum: ['summary', 'points', 'time', 'schedule', 'cycle', 'distribution', 'flow', 'cube_setup'],
                     },
-                    description: 'Which metric groups to compute. summary = exact counts via count API (no issue cap, fastest) — use with groupBy for "how many by assignee/status/priority" questions. distribution = approximate counts from fetched issues (capped by maxResults — use summary + groupBy instead when you need exact counts). cube_setup = discover dimensions before cube queries. points = earned value/SPI. time = effort estimates. schedule = overdue/risk. cycle = lead time/throughput. Default: all detail metrics. For counting/breakdown questions, always prefer summary + groupBy over distribution.',
+                    description: 'Which metric groups to compute. summary = exact counts via count API (no issue cap, fastest) — use with groupBy for "how many by assignee/status/priority" questions. distribution = approximate counts from fetched issues (capped by maxResults — use summary + groupBy instead when you need exact counts). flow = status transition analysis from bulk changelogs — entries per status, avg time in each, bounce rates, top bouncers. cube_setup = discover dimensions before cube queries. points = earned value/SPI. time = effort estimates. schedule = overdue/risk. cycle = lead time/throughput. Default: all detail metrics (excluding flow — request flow explicitly). For counting/breakdown questions, always prefer summary + groupBy over distribution.',
                 },
                 groupBy: {
                     type: 'string',

package/package.json

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