@aaronsb/jira-cloud-mcp 0.5.6 → 0.5.8

package/build/client/jira-client.js

@@ -134,7 +134,7 @@ export class JiraClient {
             people: people.length > 0 ? people : undefined,
         };
     }
-    async getIssue(issueKey, includeComments = false, includeAttachments = false, customFieldMeta) {
+    async getIssue(issueKey, includeComments = false, includeAttachments = false, customFieldMeta, includeHistory = false) {
         const fields = [...this.issueFields];
         if (includeAttachments) {
             fields.push('attachment');
@@ -147,13 +147,32 @@ export class JiraClient {
                 }
             }
         }
+        const expands = [];
+        if (includeComments)
+            expands.push('comments');
+        if (includeHistory)
+            expands.push('changelog');
         const params = {
             issueIdOrKey: issueKey,
             fields,
-            expand: includeComments ? 'comments' : undefined
+            expand: expands.length > 0 ? expands.join(',') : undefined,
         };
         const issue = await this.client.issues.getIssue(params);
         const issueDetails = this.mapIssueFields(issue);
+        // Extract status transitions from changelog
+        if (includeHistory && issue.changelog?.histories) {
+            const histories = issue.changelog.histories;
+            issueDetails.statusHistory = histories
+                .flatMap(h => h.items
+                .filter(item => item.field === 'status')
+                .map(item => ({
+                date: h.created,
+                from: item.fromString || '',
+                to: item.toString || '',
+                author: h.author?.displayName || 'Unknown',
+            })))
+                .sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
+        }
         // Extract custom field values using catalog metadata
         if (customFieldMeta) {
             const rawFields = issue.fields;

package/build/handlers/analysis-handler.js

@@ -422,11 +422,9 @@ async function handleSummary(jiraClient, jql, groupBy, compute, groupLimit = DEF
     const groupBudget = maxGroupsForBudget(neededImplicits.length);
     // Effective group cap: user's preference vs API query budget (whichever is smaller)
     const effectiveGroupCap = Math.min(groupLimit, groupBudget);
-    if (groupBy === 'project') {
+    if (groupBy === 'project' && extractProjectKeys(jql).length > 0) {
+        // Fast path: project keys are explicit in JQL — no sampling needed
         let keys = extractProjectKeys(jql);
-        if (keys.length === 0) {
-            throw new McpError(ErrorCode.InvalidParams, 'groupBy "project" requires project keys in JQL (e.g., project in (AA, GC))');
-        }
         const capped = keys.length > effectiveGroupCap;
         if (capped)
             keys = keys.slice(0, effectiveGroupCap);
@@ -479,6 +477,11 @@ async function handleSummary(jiraClient, jql, groupBy, compute, groupLimit = DEF
         lines.push('');
         lines.push(renderSummaryTable([row], compute));
     }
+    // Workload interpretation hint — steer LLMs to decompose before reporting raw numbers
+    if (groupBy === 'assignee') {
+        lines.push('');
+        lines.push('*Interpretation tip: High open counts per person may include backlog, review, and future-planned work — not just active tasks. Before reporting workload, break down by status: `metrics: ["summary"], groupBy: "issuetype"` scoped to one assignee to distinguish active work from queued/backlog items.*');
+    }
     return lines.join('\n');
 }
 /** Detect which implicit measures are referenced by compute expressions */
@@ -628,7 +631,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
     // If only summary requested, skip issue fetching entirely
     if (hasSummary && fetchMetrics.length === 0) {
         const summaryText = await handleSummary(jiraClient, jql, groupBy, compute, groupLimit);
-        const nextSteps = analysisNextSteps(jql, []);
+        const nextSteps = analysisNextSteps(jql, [], false, groupBy);
         return {
             content: [{
                     type: 'text',
@@ -701,7 +704,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
         }
     }
     // Next steps
-    const nextSteps = analysisNextSteps(jql, allIssues.slice(0, 3).map(i => i.key), truncated);
+    const nextSteps = analysisNextSteps(jql, allIssues.slice(0, 3).map(i => i.key), truncated, groupBy);
     lines.push(nextSteps);
     return {
         content: [{

package/build/handlers/issue-handlers.js

@@ -187,7 +187,8 @@ async function handleGetIssue(jiraClient, args) {
     // Get issue with requested expansions and catalog custom fields
     const includeComments = expansionOptions.comments || false;
     const includeAttachments = expansionOptions.attachments || false;
-    const issue = await jiraClient.getIssue(args.issueKey, includeComments, includeAttachments, getCatalogFieldMeta());
+    const includeHistory = expansionOptions.history || false;
+    const issue = await jiraClient.getIssue(args.issueKey, includeComments, includeAttachments, getCatalogFieldMeta(), includeHistory);
     // Get transitions if requested
     let transitions = undefined;
     if (expansionOptions.transitions) {

package/build/mcp/markdown-renderer.js

@@ -165,6 +165,20 @@ export function renderIssue(issue, transitions) {
             lines.push(`${cf.name} (${cf.type}): ${displayValue}`);
         }
     }
+    // Status history (if requested via expand: ["history"])
+    if (issue.statusHistory && issue.statusHistory.length > 0) {
+        lines.push('');
+        lines.push('Status History:');
+        for (const h of issue.statusHistory) {
+            lines.push(`${formatDate(h.date)}: ${h.from} → ${h.to} (by ${h.author})`);
+        }
+        // Show time in current status
+        const last = issue.statusHistory[issue.statusHistory.length - 1];
+        const daysSince = Math.floor((Date.now() - new Date(last.date).getTime()) / (1000 * 60 * 60 * 24));
+        if (daysSince > 0) {
+            lines.push(`*In "${last.to}" for ${daysSince} days*`);
+        }
+    }
     // Available transitions
     if (transitions && transitions.length > 0) {
         lines.push('');

package/build/utils/next-steps.js

@@ -125,11 +125,21 @@ export function boardNextSteps(operation, boardId) {
     }
     return steps.length > 0 ? formatSteps(steps) : '';
 }
-export function analysisNextSteps(jql, issueKeys, truncated = false) {
+export function analysisNextSteps(jql, issueKeys, truncated = false, groupBy) {
     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] } });
     }
+    // Contextual cross-dimension suggestions based on groupBy
+    if (groupBy === 'assignee') {
+        steps.push({ description: 'Break down a person\'s workload by status (active vs backlog vs review)', tool: 'analyze_jira_issues', example: { jql: `${jql} AND assignee = "<name>"`, metrics: ['summary'], groupBy: 'issuetype' } }, { description: 'Compare workload health with computed metrics', tool: 'analyze_jira_issues', example: { jql, metrics: ['summary'], groupBy: 'assignee', compute: ['overdue_pct = overdue / open * 100', 'stale_pct = stale / open * 100'] } });
+    }
+    else if (groupBy === 'issuetype' || groupBy === 'priority') {
+        steps.push({ description: 'See who owns these issues', tool: 'analyze_jira_issues', example: { jql, metrics: ['summary'], groupBy: 'assignee' } });
+    }
+    else if (groupBy === 'project') {
+        steps.push({ description: 'Drill into a project by assignee', tool: 'analyze_jira_issues', example: { jql: `${jql} AND project = <KEY>`, metrics: ['summary'], groupBy: 'assignee' } });
+    }
     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: 'Distribution counts above are approximate (issue cap hit). For exact breakdowns use summary + groupBy', tool: 'analyze_jira_issues', example: { jql, metrics: ['summary'], groupBy: 'assignee' } }, { description: 'Or narrow JQL for precise detail metrics', tool: 'analyze_jira_issues', example: { jql: `${jql} AND assignee = currentUser()`, metrics: ['cycle'] } });

package/package.json

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