@aaronsb/jira-cloud-mcp 0.5.5 → 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

@@ -4,11 +4,12 @@ import { analysisNextSteps } from '../utils/next-steps.js';
 import { normalizeArgs } from '../utils/normalize-args.js';
 const ALL_METRICS = ['points', 'time', 'schedule', 'cycle', 'distribution'];
 const VALID_GROUP_BY = ['project', 'assignee', 'priority', 'issuetype'];
-const MAX_ISSUES = 500;
+const MAX_ISSUES_HARD = 500; // absolute ceiling for detail metrics — beyond this, context explodes
+const MAX_ISSUES_DEFAULT = 100;
 const CUBE_SAMPLE_PCT = 0.2; // 20% of total issues
 const CUBE_SAMPLE_MIN = 50; // floor — enough for rare dimension values
 const CUBE_SAMPLE_MAX = 500; // ceiling — proven fast with lean search
-const MAX_CUBE_GROUPS = 20;
+const DEFAULT_GROUP_LIMIT = 20;
 const MAX_COUNT_QUERIES = 150; // ADR-206 budget: max count API calls per execution
 const STANDARD_MEASURES = 6; // total, open, overdue, high+, created_7d, resolved_7d
 // ── Helpers ────────────────────────────────────────────────────────────
@@ -58,11 +59,14 @@ function countBy(items, keyFn) {
 function sumBy(items, valueFn) {
     return items.reduce((sum, item) => sum + (valueFn(item) || 0), 0);
 }
-function mapToString(map, separator = ' | ') {
-    return [...map.entries()]
-        .sort((a, b) => b[1] - a[1])
-        .map(([k, v]) => `${k}: ${v}`)
-        .join(separator);
+function mapToString(map, separator = ' | ', limit) {
+    const sorted = [...map.entries()].sort((a, b) => b[1] - a[1]);
+    const capped = limit ? sorted.slice(0, limit) : sorted;
+    const result = capped.map(([k, v]) => `${k}: ${v}`).join(separator);
+    if (limit && sorted.length > limit) {
+        return `${result} | (+${sorted.length - limit} more — use groupLimit to see all)`;
+    }
+    return result;
 }
 function median(values) {
     if (values.length === 0)
@@ -255,16 +259,16 @@ export function renderCycle(issues, now) {
     }
     return lines.join('\n');
 }
-export function renderDistribution(issues) {
+export function renderDistribution(issues, groupLimit = DEFAULT_GROUP_LIMIT) {
     const lines = ['## Distribution', ''];
     const byStatus = countBy(issues, i => i.status);
-    lines.push(`**By status:** ${mapToString(byStatus)}`);
+    lines.push(`**By status:** ${mapToString(byStatus, ' | ', groupLimit)}`);
     const byAssignee = countBy(issues, i => i.assignee || 'Unassigned');
-    lines.push(`**By assignee:** ${mapToString(byAssignee)}`);
+    lines.push(`**By assignee:** ${mapToString(byAssignee, ' | ', groupLimit)}`);
     const byPriority = countBy(issues, i => i.priority || 'None');
-    lines.push(`**By priority:** ${mapToString(byPriority)}`);
+    lines.push(`**By priority:** ${mapToString(byPriority, ' | ', groupLimit)}`);
     const byType = countBy(issues, i => i.issueType || 'Unknown');
-    lines.push(`**By type:** ${mapToString(byType)}`);
+    lines.push(`**By type:** ${mapToString(byType, ' | ', groupLimit)}`);
     return lines.join('\n');
 }
 /** Extract project keys from JQL like "project in (AA, GC, GD)" or "project = AA" */
@@ -408,7 +412,7 @@ function maxGroupsForBudget(implicitCount) {
     const queriesPerGroup = STANDARD_MEASURES + implicitCount;
     return Math.floor(MAX_COUNT_QUERIES / queriesPerGroup);
 }
-async function handleSummary(jiraClient, jql, groupBy, compute) {
+async function handleSummary(jiraClient, jql, groupBy, compute, groupLimit = DEFAULT_GROUP_LIMIT) {
     const lines = [];
     lines.push(`# Summary: ${jql}`);
     lines.push(`As of ${formatDateShort(new Date())} — counts are exact (no sampling cap)`);
@@ -416,21 +420,24 @@ async function handleSummary(jiraClient, jql, groupBy, compute) {
     const implicitDefs = buildImplicitMeasures(jiraClient.customFieldIds);
     const neededImplicits = compute ? detectImplicitMeasures(compute, implicitDefs) : [];
     const groupBudget = maxGroupsForBudget(neededImplicits.length);
-    if (groupBy === 'project') {
+    // Effective group cap: user's preference vs API query budget (whichever is smaller)
+    const effectiveGroupCap = Math.min(groupLimit, groupBudget);
+    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 > groupBudget;
+        const capped = keys.length > effectiveGroupCap;
         if (capped)
-            keys = keys.slice(0, groupBudget);
+            keys = keys.slice(0, effectiveGroupCap);
         const remaining = removeProjectClause(jql);
         const rows = await batchParallel(keys.map(k => () => buildCountRow(jiraClient, k, remaining ? `project = ${k} AND (${remaining})` : `project = ${k}`, neededImplicits, implicitDefs)), ROW_BATCH_SIZE);
         rows.sort((a, b) => b.unresolved - a.unresolved);
         lines.push('');
         lines.push(renderSummaryTable(rows, compute));
         if (capped) {
-            lines.push(`*Capped at ${groupBudget} groups to stay within ${MAX_COUNT_QUERIES}-query budget*`);
+            const reason = effectiveGroupCap < groupBudget
+                ? `groupLimit=${effectiveGroupCap} — increase groupLimit to see more`
+                : `${MAX_COUNT_QUERIES}-query budget`;
+            lines.push(`*Capped at ${effectiveGroupCap} groups (${reason})*`);
         }
     }
     else if (groupBy) {
@@ -439,23 +446,29 @@ async function handleSummary(jiraClient, jql, groupBy, compute) {
         if (issues.length === 0) {
             throw new McpError(ErrorCode.InvalidParams, `No issues matched JQL — cannot discover ${groupBy} values`);
         }
-        const dims = extractDimensions(issues);
+        const dims = extractDimensions(issues, groupLimit);
         const dim = dims.find(d => d.name === groupBy);
         if (!dim || dim.values.length === 0) {
             throw new McpError(ErrorCode.InvalidParams, `No ${groupBy} values found in sampled issues`);
         }
-        // Cap groups to query budget
-        const cappedValues = dim.values.slice(0, groupBudget);
+        // Cap groups to effective limit
+        const cappedValues = dim.values.slice(0, effectiveGroupCap);
         const jqlClause = groupByJqlClause(groupBy, cappedValues);
         const rows = await batchParallel(cappedValues.map((value, idx) => () => buildCountRow(jiraClient, value, `(${jql}) AND ${jqlClause[idx]}`, neededImplicits, implicitDefs)), ROW_BATCH_SIZE);
         rows.sort((a, b) => b.unresolved - a.unresolved);
         lines.push('');
         lines.push(renderSummaryTable(rows, compute));
         if (dim.count > cappedValues.length) {
-            const reason = cappedValues.length < dim.values.length
-                ? `capped at ${groupBudget} groups (${MAX_COUNT_QUERIES}-query budget)`
-                : `from ${issues.length}-issue sample`;
-            lines.push(`*Showing top ${cappedValues.length} of ${dim.count} ${groupBy} values (${reason})*`);
+            const reasons = [];
+            if (cappedValues.length < dim.values.length) {
+                reasons.push(effectiveGroupCap < groupBudget
+                    ? `groupLimit=${effectiveGroupCap} — increase groupLimit to see more`
+                    : `${MAX_COUNT_QUERIES}-query budget`);
+            }
+            else {
+                reasons.push(`from ${issues.length}-issue sample`);
+            }
+            lines.push(`*Showing top ${cappedValues.length} of ${dim.count} ${groupBy} values (${reasons.join(', ')})*`);
         }
     }
     else {
@@ -464,6 +477,11 @@ async function handleSummary(jiraClient, jql, groupBy, compute) {
         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 */
@@ -472,7 +490,7 @@ function detectImplicitMeasures(compute, implicitMeasureDefs) {
     return Object.keys(implicitMeasureDefs).filter(name => refs.has(name));
 }
 /** Extract distinct dimension values from sampled issues */
-export function extractDimensions(issues) {
+export function extractDimensions(issues, groupLimit = DEFAULT_GROUP_LIMIT) {
     const dims = [
         { name: 'project', extractor: i => i.key.split('-')[0] },
         { name: 'status', extractor: i => i.status },
@@ -486,10 +504,10 @@ export function extractDimensions(issues) {
             const val = extractor(issue);
             counts.set(val, (counts.get(val) || 0) + 1);
         }
-        // Sort by count descending, cap at MAX_CUBE_GROUPS
+        // Sort by count descending, cap at groupLimit
         const sorted = [...counts.entries()]
             .sort((a, b) => b[1] - a[1])
-            .slice(0, MAX_CUBE_GROUPS);
+            .slice(0, groupLimit);
         return {
             name,
             values: sorted.map(([v]) => v),
@@ -521,7 +539,7 @@ export function renderCubeSetup(jql, sampleSize, dimensions) {
     lines.push('');
     lines.push(`## Suggested Cubes (budget: ${MAX_COUNT_QUERIES} queries)`);
     for (const dim of dimensions) {
-        const groups = Math.min(dim.count, MAX_CUBE_GROUPS);
+        const groups = Math.min(dim.count, DEFAULT_GROUP_LIMIT);
         const queries = groups * STANDARD_MEASURES;
         const estSeconds = Math.max(1, Math.round(queries / 12)); // ~12 parallel queries/sec
         const withinBudget = queries <= MAX_COUNT_QUERIES;
@@ -596,6 +614,9 @@ export async function handleAnalysisRequest(jiraClient, request) {
     if (args.compute && Array.isArray(args.compute) && args.compute.length > 0) {
         compute = parseComputeList(args.compute);
     }
+    // Parse groupLimit — soft cap on group/dimension values (no hard cap for summary metrics)
+    const rawGroupLimit = Number(args.groupLimit);
+    const groupLimit = rawGroupLimit > 0 ? rawGroupLimit : DEFAULT_GROUP_LIMIT;
     // Cube setup — discover dimensions from sample, no issue fetching
     if (hasCubeSetup) {
         const cubeText = await handleCubeSetup(jiraClient, jql);
@@ -609,8 +630,8 @@ 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);
-        const nextSteps = analysisNextSteps(jql, []);
+        const summaryText = await handleSummary(jiraClient, jql, groupBy, compute, groupLimit);
+        const nextSteps = analysisNextSteps(jql, [], false, groupBy);
         return {
             content: [{
                     type: 'text',
@@ -618,8 +639,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
                 }],
         };
     }
-    const DEFAULT_MAX = 100;
-    const maxResults = Math.min(Number(args.maxResults) || DEFAULT_MAX, MAX_ISSUES);
+    const maxResults = Math.min(Number(args.maxResults) || MAX_ISSUES_DEFAULT, MAX_ISSUES_HARD);
     // Fetch issues using cursor-based pagination (50 per page, Jira enhanced search API)
     const allIssues = [];
     const seen = new Set();
@@ -658,7 +678,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
     const lines = [];
     // Summary first if requested alongside other metrics
     if (hasSummary) {
-        const summaryText = await handleSummary(jiraClient, jql, groupBy, compute);
+        const summaryText = await handleSummary(jiraClient, jql, groupBy, compute, groupLimit);
         lines.push(summaryText);
     }
     // Header for fetch-based metrics
@@ -668,7 +688,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
         lines.push(`# Detail: ${jql}`);
         lines.push(`Analyzed ${allIssues.length} issues (as of ${formatDateShort(now)})`);
         if (truncated) {
-            lines.push(`*Results capped at ${maxResults} issues — query may match more.*`);
+            lines.push(`*Results capped at ${maxResults} issues — distributions below are approximate. For exact counts, use metrics: ["summary"] with groupBy instead.*`);
         }
         // Render requested metrics
         const renderers = {
@@ -676,7 +696,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
             time: () => renderTime(allIssues),
             schedule: () => renderSchedule(allIssues, now),
             cycle: () => renderCycle(allIssues, now),
-            distribution: () => renderDistribution(allIssues),
+            distribution: () => renderDistribution(allIssues, groupLimit),
         };
         for (const metric of fetchMetrics) {
             lines.push('');
@@ -684,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/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. Use "summary" for exact counts across projects (no sampling cap). Use other metrics for detailed analysis of individual issue data. Always prefer this tool over manage_jira_filter or manage_jira_project for quantitative questions (counts, totals, overdue, workload). Read jira://analysis/recipes for composition patterns.',
+        description: 'Compute project metrics over issues selected by JQL. 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. Read jira://analysis/recipes for composition patterns.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -340,12 +340,12 @@ export const toolSchemas = {
                         type: 'string',
                         enum: ['summary', 'points', 'time', 'schedule', 'cycle', 'distribution', 'cube_setup'],
                     },
-                    description: 'Which metric groups to compute. summary = exact issue counts via count API (no cap, fastest). cube_setup = sample issues and discover available dimensions/measures for cube queries. points = earned value/SPI. time = effort estimates. schedule = overdue/risk. cycle = lead time/throughput. distribution = counts by status/assignee/priority/type. Default: all except summary and 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.',
                 },
                 groupBy: {
                     type: 'string',
                     enum: ['project', 'assignee', 'priority', 'issuetype'],
-                    description: 'Split summary counts by this dimension. Use with metrics: ["summary"]. "project" produces a per-project comparison table.',
+                    description: 'Split counts by this dimension — produces a breakdown table. Use with metrics: ["summary"] for exact counts. This is the correct approach for "how many issues per assignee/priority/type" questions. "project" produces a per-project comparison.',
                 },
                 compute: {
                     type: 'array',
@@ -353,6 +353,11 @@ export const toolSchemas = {
                     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,
                 },
+                groupLimit: {
+                    type: 'integer',
+                    description: 'Max groups/dimension values to show (default 20). Applies to summary groupBy rows and distribution breakdowns. No hard cap for summary metrics — increase freely for full visibility. For detail metrics the issue fetch is separately capped by maxResults.',
+                    default: 20,
+                },
                 maxResults: {
                     type: 'integer',
                     description: 'Max issues to fetch for detail metrics (default 100, max 500). Does not apply to summary (which uses count API).',

package/build/utils/next-steps.js

@@ -125,14 +125,24 @@ 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: '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'] } });
+        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'] } });
     }
     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.5",
+  "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",