@aaronsb/jira-cloud-mcp 0.4.3 → 0.5.1

package/build/client/jira-client.js

@@ -100,6 +100,7 @@ export class JiraClient {
             assignee: fields?.assignee?.displayName || null,
             reporter: fields?.reporter?.displayName || '',
             status: fields?.status?.name || '',
+            statusCategory: fields?.status?.statusCategory?.key || 'unknown',
             resolution: fields?.resolution?.name || null,
             labels: fields?.labels || [],
             created: fields?.created || '',
@@ -107,8 +108,8 @@ export class JiraClient {
             resolutionDate: fields?.resolutiondate || null,
             dueDate: fields?.duedate || null,
             startDate: fields?.[this.customFields.startDate] || null,
-            storyPoints: fields?.[this.customFields.storyPoints] || null,
-            timeEstimate: fields?.timeestimate || null,
+            storyPoints: fields?.[this.customFields.storyPoints] ?? null,
+            timeEstimate: fields?.timeestimate ?? null,
             issueLinks: (fields?.issuelinks || []).map((link) => ({
                 type: link.type?.name || '',
                 outward: link.outwardIssue?.key || null,
@@ -406,6 +407,60 @@ export class JiraClient {
             comment: TextProcessor.markdownToAdf(commentBody)
         });
     }
+    /** Lightweight search returning only fields needed for analysis (no description, links, rendered HTML) */
+    async countIssues(jql) {
+        try {
+            const cleanJql = jql.replace(/\\"/g, '"');
+            console.error(`Counting issues for JQL: ${cleanJql}`);
+            const result = await this.client.issueSearch.countIssues({ jql: cleanJql });
+            return result.count ?? 0;
+        }
+        catch (error) {
+            console.error('Error counting issues:', error);
+            throw error;
+        }
+    }
+    async searchIssuesLean(jql, maxResults = 50, nextPageToken) {
+        try {
+            const cleanJql = jql.replace(/\\"/g, '"');
+            console.error(`Executing lean JQL search with query: ${cleanJql}${nextPageToken ? ' (page token)' : ''}`);
+            const leanFields = [
+                'summary', 'issuetype', 'priority', 'assignee', 'reporter',
+                'status', 'resolution', 'labels', 'created', 'updated',
+                'resolutiondate', 'duedate', 'timeestimate',
+                this.customFields.startDate, this.customFields.storyPoints,
+            ];
+            const params = {
+                jql: cleanJql,
+                maxResults: Math.min(maxResults, 50),
+                fields: leanFields,
+            };
+            if (nextPageToken) {
+                params.nextPageToken = nextPageToken;
+            }
+            const timeoutMs = 30_000;
+            const searchResults = await Promise.race([
+                this.client.issueSearch.searchForIssuesUsingJqlEnhancedSearch(params),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`Lean search timed out after ${timeoutMs / 1000}s — try a narrower JQL query or smaller maxResults`)), timeoutMs)),
+            ]);
+            const issues = (searchResults.issues || []).map(issue => this.mapIssueFields(issue));
+            const hasMore = !!searchResults.nextPageToken;
+            return {
+                issues,
+                pagination: {
+                    startAt: 0,
+                    maxResults,
+                    total: hasMore ? issues.length + 1 : issues.length,
+                    hasMore,
+                    nextPageToken: searchResults.nextPageToken || undefined,
+                }
+            };
+        }
+        catch (error) {
+            console.error('Error executing lean JQL search:', error);
+            throw error;
+        }
+    }
     async searchIssues(jql, startAt = 0, maxResults = 25) {
         try {
             // Remove escaped quotes from JQL

package/build/docs/tool-documentation.js

@@ -15,6 +15,7 @@ const documentationGenerators = {
     manage_jira_filter: generateFilterToolDocumentation,
     manage_jira_project: generateProjectToolDocumentation,
     queue_jira_operations: generateQueueToolDocumentation,
+    analyze_jira_issues: generateAnalysisToolDocumentation,
 };
 export function generateToolDocumentation(toolName, schema) {
     const generator = documentationGenerators[toolName];
@@ -460,6 +461,72 @@ function generateQueueToolDocumentation(_schema) {
         related_resources: [],
     };
 }
+function generateAnalysisToolDocumentation(schema) {
+    return {
+        name: "Issue Analysis",
+        description: schema.description,
+        parameters: {
+            jql: {
+                type: "string",
+                description: "JQL query selecting the issues to analyze.",
+                required: true,
+            },
+            metrics: {
+                type: "array of strings",
+                description: "Which metric groups to compute. summary uses count API (no cap). Others fetch issue data (subject to maxResults).",
+                values: ["summary", "points", "time", "schedule", "cycle", "distribution"],
+            },
+            groupBy: {
+                type: "string",
+                description: "Split summary counts by dimension. Use with metrics: ['summary'].",
+                values: ["project", "assignee", "priority", "issuetype"],
+            },
+            maxResults: {
+                type: "integer",
+                description: "Max issues to fetch for detail metrics (default 100, max 500). Does not apply to summary.",
+            },
+        },
+        metric_groups: {
+            summary: "Exact counts — total, open, overdue, high priority, created/resolved last 7 days. No sampling cap. Supports groupBy for cross-project comparison.",
+            points: "Earned Value — PV, EV, remaining, SPI, status breakdown, unestimated count",
+            time: "Effort — original estimate, completed, remaining by status category",
+            schedule: "Risk — date window, overdue count/slip, due soon, concentration risk, missing dates",
+            cycle: "Flow — lead time median/mean, throughput, open issue age, oldest open",
+            distribution: "Composition — counts by status, assignee, priority, issue type",
+        },
+        common_use_cases: [
+            {
+                title: "Cross-project comparison",
+                description: "Compare issue counts across multiple projects (exact, no cap):",
+                steps: [
+                    { description: "Summary by project", code: { jql: "project in (AA, GC, GD, LGS)", metrics: ["summary"], groupBy: "project" } },
+                ],
+            },
+            {
+                title: "Sprint health check",
+                description: "Analyze all issues in the current sprint:",
+                steps: [
+                    { description: "Full analysis", code: { jql: "sprint in openSprints()" } },
+                ],
+            },
+            {
+                title: "Schedule risk for a release",
+                description: "Check overdue and upcoming deadlines:",
+                steps: [
+                    { description: "Schedule only", code: { jql: "project = AA AND fixVersion = 2.0", metrics: ["schedule"] } },
+                ],
+            },
+            {
+                title: "Quick project overview",
+                description: "Get exact issue counts without fetching data:",
+                steps: [
+                    { description: "Summary only", code: { jql: "project = AA", metrics: ["summary"] } },
+                ],
+            },
+        ],
+        related_resources: [],
+    };
+}
 function generateGenericToolDocumentation(toolName, schema) {
     const operations = {};
     if (schema.inputSchema?.properties?.operation?.enum) {

package/build/handlers/analysis-handler.js

@@ -0,0 +1,408 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+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;
+// ── Helpers ────────────────────────────────────────────────────────────
+function bucketStatus(category) {
+    switch (category) {
+        case 'new': return 'To Do';
+        case 'indeterminate': return 'In Progress';
+        case 'done': return 'Done';
+        default: return 'To Do';
+    }
+}
+/** Parse a date string to a Date without timezone shift for date-only values */
+function parseDate(dateStr) {
+    const dateOnly = dateStr.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+    if (dateOnly) {
+        const [, y, m, d] = dateOnly;
+        return new Date(Number(y), Number(m) - 1, Number(d));
+    }
+    return new Date(dateStr);
+}
+function formatDateShort(date) {
+    return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
+}
+function daysBetween(a, b) {
+    return Math.round((b.getTime() - a.getTime()) / (1000 * 60 * 60 * 24));
+}
+function formatDuration(seconds) {
+    const hours = Math.floor(seconds / 3600);
+    const days = Math.floor(hours / 8); // 8-hour work day
+    if (days > 0) {
+        const remainingHours = hours % 8;
+        return remainingHours > 0 ? `${days}d ${remainingHours}h` : `${days}d`;
+    }
+    const minutes = Math.floor((seconds % 3600) / 60);
+    if (hours > 0)
+        return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+    return `${minutes}m`;
+}
+function countBy(items, keyFn) {
+    const counts = new Map();
+    for (const item of items) {
+        const key = keyFn(item);
+        counts.set(key, (counts.get(key) || 0) + 1);
+    }
+    return counts;
+}
+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 median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 !== 0 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+function mean(values) {
+    if (values.length === 0)
+        return 0;
+    return values.reduce((s, v) => s + v, 0) / values.length;
+}
+// ── Metric Renderers (exported for testing) ────────────────────────────
+export function renderPoints(issues) {
+    const estimated = issues.filter(i => i.storyPoints != null);
+    const unestimated = issues.length - estimated.length;
+    const byBucket = new Map();
+    for (const issue of issues) {
+        const bucket = bucketStatus(issue.statusCategory);
+        byBucket.set(bucket, (byBucket.get(bucket) ?? 0) + (issue.storyPoints ?? 0));
+    }
+    const pv = sumBy(issues, i => i.storyPoints);
+    const ev = byBucket.get('Done') ?? 0;
+    const remaining = pv - ev;
+    const spi = pv > 0 ? (ev / pv) : null;
+    const lines = ['## Points (Earned Value)', ''];
+    lines.push('| Metric | Value |');
+    lines.push('|--------|-------|');
+    lines.push(`| Planned Value (PV) | ${pv} pts |`);
+    lines.push(`| Earned Value (EV) | ${ev} pts |`);
+    lines.push(`| Remaining | ${remaining} pts |`);
+    lines.push(`| SPI | ${spi !== null ? spi.toFixed(2) : 'N/A (no estimates)'} |`);
+    if (unestimated > 0) {
+        lines.push(`| Unestimated | ${unestimated} issue${unestimated !== 1 ? 's' : ''} |`);
+    }
+    lines.push('');
+    const bucketStr = ['To Do', 'In Progress', 'Done']
+        .map(b => `${b}: ${byBucket.get(b) ?? 0} pts`)
+        .join(' | ');
+    lines.push(`**By status:** ${bucketStr}`);
+    return lines.join('\n');
+}
+export function renderTime(issues) {
+    const estimated = issues.filter(i => i.timeEstimate != null);
+    const unestimated = issues.length - estimated.length;
+    const total = sumBy(issues, i => i.timeEstimate);
+    const byBucket = new Map();
+    for (const issue of issues) {
+        const bucket = bucketStatus(issue.statusCategory);
+        byBucket.set(bucket, (byBucket.get(bucket) ?? 0) + (issue.timeEstimate ?? 0));
+    }
+    const done = byBucket.get('Done') ?? 0;
+    const remaining = total - done;
+    const lines = ['## Time (Effort)', ''];
+    lines.push('| Metric | Value |');
+    lines.push('|--------|-------|');
+    lines.push(`| Original Estimate | ${formatDuration(total)} |`);
+    lines.push(`| Completed | ${formatDuration(done)} |`);
+    lines.push(`| Remaining | ${formatDuration(remaining)} |`);
+    if (unestimated > 0) {
+        lines.push(`| Unestimated | ${unestimated} issue${unestimated !== 1 ? 's' : ''} |`);
+    }
+    return lines.join('\n');
+}
+export function renderSchedule(issues, now) {
+    const lines = ['## Schedule', ''];
+    // Date range
+    const startDates = issues.filter(i => i.startDate).map(i => parseDate(i.startDate));
+    const dueDates = issues.filter(i => i.dueDate).map(i => parseDate(i.dueDate));
+    const allDates = [...startDates, ...dueDates];
+    if (allDates.length > 0) {
+        const earliest = new Date(Math.min(...allDates.map(d => d.getTime())));
+        const latest = new Date(Math.max(...allDates.map(d => d.getTime())));
+        lines.push(`**Window:** ${formatDateShort(earliest)} - ${formatDateShort(latest)}`);
+    }
+    // Overdue
+    const overdue = issues.filter(i => i.dueDate && !i.resolutionDate && parseDate(i.dueDate) < now);
+    if (overdue.length > 0) {
+        const totalSlip = overdue.reduce((sum, i) => sum + daysBetween(parseDate(i.dueDate), now), 0);
+        const keys = overdue.slice(0, 5).map(i => i.key).join(', ');
+        const more = overdue.length > 5 ? ` +${overdue.length - 5} more` : '';
+        lines.push(`**Overdue:** ${overdue.length} issue${overdue.length !== 1 ? 's' : ''}, ${totalSlip} days total slip (${keys}${more})`);
+    }
+    else {
+        lines.push('**Overdue:** none');
+    }
+    // Due soon
+    for (const window of [7, 14, 30]) {
+        const cutoff = new Date(now.getTime() + window * 24 * 60 * 60 * 1000);
+        const dueSoon = issues.filter(i => i.dueDate && !i.resolutionDate &&
+            parseDate(i.dueDate) >= now && parseDate(i.dueDate) <= cutoff);
+        if (dueSoon.length > 0) {
+            lines.push(`**Due next ${window} days:** ${dueSoon.length} issue${dueSoon.length !== 1 ? 's' : ''}`);
+        }
+    }
+    // Concentration risk
+    const dueDateCounts = countBy(issues.filter(i => i.dueDate && !i.resolutionDate), i => i.dueDate);
+    const concentrated = [...dueDateCounts.entries()]
+        .filter(([, count]) => count >= 3)
+        .sort((a, b) => b[1] - a[1]);
+    if (concentrated.length > 0) {
+        const top = concentrated.slice(0, 3)
+            .map(([date, count]) => `${formatDateShort(parseDate(date))} has ${count} issues`)
+            .join('; ');
+        lines.push(`**Concentration:** ${top}`);
+    }
+    // No due date
+    const noDueDate = issues.filter(i => !i.dueDate && !i.resolutionDate);
+    if (noDueDate.length > 0) {
+        lines.push(`**No due date:** ${noDueDate.length} issue${noDueDate.length !== 1 ? 's' : ''}`);
+    }
+    return lines.join('\n');
+}
+export function renderCycle(issues, now) {
+    const lines = ['## Cycle (Flow Metrics)', ''];
+    // Lead time for resolved issues
+    const resolved = issues.filter(i => i.resolutionDate && i.created);
+    if (resolved.length > 0) {
+        const leadTimes = resolved.map(i => daysBetween(parseDate(i.created), parseDate(i.resolutionDate)));
+        const med = median(leadTimes);
+        const avg = mean(leadTimes);
+        lines.push(`**Lead time (resolved):** median ${med.toFixed(1)} days, mean ${avg.toFixed(1)} days (${resolved.length} issues)`);
+        // Throughput
+        const createdDates = resolved.map(i => parseDate(i.resolutionDate).getTime());
+        const earliest = Math.min(...createdDates);
+        const latest = Math.max(...createdDates);
+        const weeks = Math.max(1, (latest - earliest) / (7 * 24 * 60 * 60 * 1000));
+        const throughput = resolved.length / weeks;
+        lines.push(`**Throughput:** ${throughput.toFixed(1)} issues/week`);
+    }
+    else {
+        lines.push('**Lead time:** no resolved issues in set');
+    }
+    // Age of open issues
+    const open = issues.filter(i => !i.resolutionDate && i.created);
+    if (open.length > 0) {
+        const ages = open.map(i => daysBetween(parseDate(i.created), now));
+        const avgAge = mean(ages);
+        lines.push(`**Open issue age:** mean ${avgAge.toFixed(1)} days (${open.length} issues)`);
+        // Oldest open
+        const oldest = open
+            .map(i => ({ key: i.key, age: daysBetween(parseDate(i.created), now) }))
+            .sort((a, b) => b.age - a.age)
+            .slice(0, 5);
+        const oldestStr = oldest.map(o => `${o.key} (${o.age}d)`).join(', ');
+        lines.push(`**Oldest open:** ${oldestStr}`);
+    }
+    return lines.join('\n');
+}
+export function renderDistribution(issues) {
+    const lines = ['## Distribution', ''];
+    const byStatus = countBy(issues, i => i.status);
+    lines.push(`**By status:** ${mapToString(byStatus)}`);
+    const byAssignee = countBy(issues, i => i.assignee || 'Unassigned');
+    lines.push(`**By assignee:** ${mapToString(byAssignee)}`);
+    const byPriority = countBy(issues, i => i.priority || 'None');
+    lines.push(`**By priority:** ${mapToString(byPriority)}`);
+    const byType = countBy(issues, i => i.issueType || 'Unknown');
+    lines.push(`**By type:** ${mapToString(byType)}`);
+    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)
+    const inMatch = jql.match(/project\s+in\s*\(([^)]+)\)/i);
+    if (inMatch) {
+        return inMatch[1].split(',').map(k => k.trim().replace(/['"]/g, ''));
+    }
+    // project = AA
+    const eqMatch = jql.match(/project\s*=\s*['"]?(\w+)['"]?/i);
+    if (eqMatch) {
+        return [eqMatch[1]];
+    }
+    return [];
+}
+/** Remove the project clause from JQL, returning remaining constraints */
+export function removeProjectClause(jql) {
+    return jql
+        .replace(/project\s+in\s*\([^)]+\)\s*(AND\s*)?/i, '')
+        .replace(/project\s*=\s*['"]?\w+['"]?\s*(AND\s*)?/i, '')
+        .replace(/^\s*AND\s*/i, '')
+        .replace(/\s*AND\s*$/i, '')
+        .trim();
+}
+/** Build a scoped JQL by adding a condition to the base query */
+function scopeJql(baseJql, condition) {
+    return `(${baseJql}) AND ${condition}`;
+}
+async function buildCountRow(jiraClient, label, baseJql) {
+    const [total, unresolved, overdue, highPriority, createdRecently, resolvedRecently] = await Promise.all([
+        jiraClient.countIssues(baseJql),
+        jiraClient.countIssues(scopeJql(baseJql, 'resolution = Unresolved')),
+        jiraClient.countIssues(scopeJql(baseJql, 'resolution = Unresolved AND dueDate < now()')),
+        jiraClient.countIssues(scopeJql(baseJql, 'priority in (High, Highest, Critical, Blocker)')),
+        jiraClient.countIssues(scopeJql(baseJql, 'created >= -7d')),
+        jiraClient.countIssues(scopeJql(baseJql, 'resolved >= -7d')),
+    ]);
+    return { label, total, unresolved, overdue, highPriority, createdRecently, resolvedRecently };
+}
+export function renderSummaryTable(rows) {
+    const lines = ['## Summary (exact counts)', ''];
+    lines.push('| Scope | Total | Open | Overdue | High+ | Created 7d | Resolved 7d |');
+    lines.push('|-------|------:|-----:|--------:|------:|-----------:|------------:|');
+    for (const r of rows) {
+        lines.push(`| ${r.label} | ${r.total} | ${r.unresolved} | ${r.overdue} | ${r.highPriority} | ${r.createdRecently} | ${r.resolvedRecently} |`);
+    }
+    // Totals row if multiple
+    if (rows.length > 1) {
+        const sum = (fn) => rows.reduce((s, r) => s + fn(r), 0);
+        lines.push(`| **Total** | **${sum(r => r.total)}** | **${sum(r => r.unresolved)}** | **${sum(r => r.overdue)}** | **${sum(r => r.highPriority)}** | **${sum(r => r.createdRecently)}** | **${sum(r => r.resolvedRecently)}** |`);
+    }
+    return lines.join('\n');
+}
+async function handleSummary(jiraClient, jql, groupBy) {
+    const lines = [];
+    lines.push(`# Summary: ${jql}`);
+    lines.push(`As of ${formatDateShort(new Date())} — counts are exact (no sampling cap)`);
+    if (groupBy === 'project') {
+        const 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 remaining = removeProjectClause(jql);
+        const rows = await Promise.all(keys.map(k => buildCountRow(jiraClient, k, remaining ? `project = ${k} AND (${remaining})` : `project = ${k}`)));
+        rows.sort((a, b) => b.unresolved - a.unresolved);
+        lines.push('');
+        lines.push(renderSummaryTable(rows));
+    }
+    else if (groupBy) {
+        // For non-project groupBy, get the overall count first
+        const overallRow = await buildCountRow(jiraClient, 'All', jql);
+        lines.push('');
+        lines.push(renderSummaryTable([overallRow]));
+        lines.push('');
+        lines.push(`*groupBy "${groupBy}" — only "project" supports per-group breakdown currently. Other dimensions coming soon.*`);
+    }
+    else {
+        // No groupBy — single row for the whole JQL
+        const row = await buildCountRow(jiraClient, 'All', jql);
+        lines.push('');
+        lines.push(renderSummaryTable([row]));
+    }
+    return lines.join('\n');
+}
+// ── Main Handler ───────────────────────────────────────────────────────
+export async function handleAnalysisRequest(jiraClient, request) {
+    const args = normalizeArgs(request.params?.arguments || {});
+    const jql = args.jql;
+    if (!jql || typeof jql !== 'string' || jql.trim() === '') {
+        throw new McpError(ErrorCode.InvalidParams, 'jql parameter is required.');
+    }
+    // Parse requested metrics
+    const requested = (args.metrics && Array.isArray(args.metrics))
+        ? args.metrics
+        : [];
+    const hasSummary = requested.includes('summary');
+    const fetchMetrics = requested.length > 0
+        ? requested.filter(m => ALL_METRICS.includes(m))
+        : ALL_METRICS;
+    // Parse groupBy
+    const groupBy = (typeof args.groupBy === 'string' && VALID_GROUP_BY.includes(args.groupBy))
+        ? args.groupBy
+        : undefined;
+    // If only summary requested, skip issue fetching entirely
+    if (hasSummary && fetchMetrics.length === 0) {
+        const summaryText = await handleSummary(jiraClient, jql, groupBy);
+        const nextSteps = analysisNextSteps(jql, []);
+        return {
+            content: [{
+                    type: 'text',
+                    text: summaryText + '\n' + nextSteps,
+                }],
+        };
+    }
+    const DEFAULT_MAX = 100;
+    const maxResults = Math.min(Number(args.maxResults) || DEFAULT_MAX, MAX_ISSUES);
+    // Fetch issues using cursor-based pagination (50 per page, Jira enhanced search API)
+    const allIssues = [];
+    const seen = new Set();
+    let nextPageToken;
+    let truncated = false;
+    const maxPages = Math.ceil(maxResults / 50) + 1;
+    let pageCount = 0;
+    while (allIssues.length < maxResults) {
+        if (++pageCount > maxPages)
+            break;
+        const remaining = maxResults - allIssues.length;
+        const result = await jiraClient.searchIssuesLean(jql, Math.min(50, remaining), nextPageToken);
+        for (const issue of result.issues) {
+            if (!seen.has(issue.key)) {
+                seen.add(issue.key);
+                allIssues.push(issue);
+            }
+        }
+        if (!result.pagination.hasMore || result.issues.length === 0)
+            break;
+        nextPageToken = result.pagination.nextPageToken;
+        if (allIssues.length >= maxResults) {
+            truncated = result.pagination.hasMore;
+            break;
+        }
+    }
+    if (allIssues.length === 0 && !hasSummary) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `# Analysis\n\n**JQL:** \`${jql}\`\n\nNo issues matched this query.`,
+                }],
+        };
+    }
+    const now = new Date();
+    const lines = [];
+    // Summary first if requested alongside other metrics
+    if (hasSummary) {
+        const summaryText = await handleSummary(jiraClient, jql, groupBy);
+        lines.push(summaryText);
+    }
+    // Header for fetch-based metrics
+    if (fetchMetrics.length > 0 && allIssues.length > 0) {
+        if (hasSummary)
+            lines.push('');
+        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.*`);
+        }
+        // Render requested metrics
+        const renderers = {
+            points: () => renderPoints(allIssues),
+            time: () => renderTime(allIssues),
+            schedule: () => renderSchedule(allIssues, now),
+            cycle: () => renderCycle(allIssues, now),
+            distribution: () => renderDistribution(allIssues),
+        };
+        for (const metric of fetchMetrics) {
+            lines.push('');
+            lines.push(renderers[metric]());
+        }
+    }
+    // Next steps
+    const nextSteps = analysisNextSteps(jql, allIssues.slice(0, 3).map(i => i.key));
+    lines.push(nextSteps);
+    return {
+        content: [{
+                type: 'text',
+                text: lines.join('\n'),
+            }],
+    };
+}

package/build/index.js

@@ -5,6 +5,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ErrorCode, 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';
 import { handleBoardRequest } from './handlers/board-handlers.js';
 import { handleFilterRequest } from './handlers/filter-handlers.js';
 import { handleIssueRequest } from './handlers/issue-handlers.js';
@@ -91,6 +92,7 @@ class JiraServer {
                     manage_jira_board: handleBoardRequest,
                     manage_jira_sprint: handleSprintRequest,
                     manage_jira_filter: handleFilterRequest,
+                    analyze_jira_issues: handleAnalysisRequest,
                 };
                 const handlers = {
                     ...toolHandlers,

package/build/schemas/tool-schemas.js

@@ -1,7 +1,7 @@
 export const toolSchemas = {
     manage_jira_filter: {
         name: 'manage_jira_filter',
-        description: 'Search for issues using JQL queries, or manage saved filters',
+        description: 'Search for issues using JQL queries, or manage saved filters. Returns issue details (title, status, description). For quantitative questions (counts, totals, overdue, workload), use analyze_jira_issues instead.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -242,7 +242,7 @@ export const toolSchemas = {
     },
     manage_jira_project: {
         name: 'manage_jira_project',
-        description: 'List projects or get project details including status counts',
+        description: 'List projects or get project configuration and metadata. For issue counts, workload, or cross-project comparison, use analyze_jira_issues with metrics: ["summary"] instead.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -324,6 +324,38 @@ export const toolSchemas = {
             required: ['operation'],
         },
     },
+    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).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                jql: {
+                    type: 'string',
+                    description: 'JQL query selecting the issues to analyze. Examples: "project in (AA, GC, LGS)", "sprint in openSprints()", "assignee = currentUser() AND resolution = Unresolved".',
+                },
+                metrics: {
+                    type: 'array',
+                    items: {
+                        type: 'string',
+                        enum: ['summary', 'points', 'time', 'schedule', 'cycle', 'distribution'],
+                    },
+                    description: 'Which metric groups to compute. summary = exact issue counts via count API (no cap, fastest). 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.',
+                },
+                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.',
+                },
+                maxResults: {
+                    type: 'integer',
+                    description: 'Max issues to fetch for detail metrics (default 100, max 500). Does not apply to summary (which uses count API).',
+                    default: 100,
+                },
+            },
+            required: ['jql'],
+        },
+    },
     queue_jira_operations: {
         name: 'queue_jira_operations',
         description: 'Execute multiple Jira operations in a single call. Operations run sequentially with result references ($0.key) and per-operation error strategies (bail/continue).',
@@ -337,7 +369,7 @@ export const toolSchemas = {
                         properties: {
                             tool: {
                                 type: 'string',
-                                enum: ['manage_jira_issue', 'manage_jira_filter', 'manage_jira_sprint', 'manage_jira_project', 'manage_jira_board'],
+                                enum: ['manage_jira_issue', 'manage_jira_filter', 'manage_jira_sprint', 'manage_jira_project', 'manage_jira_board', 'analyze_jira_issues'],
                                 description: 'Which tool to call.',
                             },
                             args: {

package/build/utils/next-steps.js

@@ -125,3 +125,11 @@ export function boardNextSteps(operation, boardId) {
     }
     return steps.length > 0 ? formatSteps(steps) : '';
 }
+export function analysisNextSteps(jql, issueKeys) {
+    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: '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 } });
+    return formatSteps(steps);
+}

package/package.json

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