@aaronsb/jira-cloud-mcp 0.4.3 → 0.5.0

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,48 @@ export class JiraClient {
             comment: TextProcessor.markdownToAdf(commentBody)
         });
     }
+    /** Lightweight search returning only fields needed for analysis (no description, links, rendered HTML) */
+    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,59 @@ 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 include. Default: all.",
+                values: ["points", "time", "schedule", "cycle", "distribution"],
+            },
+            maxResults: {
+                type: "integer",
+                description: "Max issues to analyze (default 100, max 500).",
+            },
+        },
+        metric_groups: {
+            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: "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: "Workload balance",
+                description: "See how work is distributed across team members:",
+                steps: [
+                    { description: "Distribution only", code: { jql: "project = AA AND resolution = Unresolved", metrics: ["distribution"] } },
+                ],
+            },
+        ],
+        related_resources: [],
+    };
+}
 function generateGenericToolDocumentation(toolName, schema) {
     const operations = {};
     if (schema.inputSchema?.properties?.operation?.enum) {

package/build/handlers/analysis-handler.js

@@ -0,0 +1,300 @@
+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 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');
+}
+// ── 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.');
+    }
+    const DEFAULT_MAX = 100;
+    const maxResults = Math.min(Number(args.maxResults) || DEFAULT_MAX, MAX_ISSUES);
+    // Parse requested metrics
+    let metrics = ALL_METRICS;
+    if (args.metrics && Array.isArray(args.metrics)) {
+        const requested = args.metrics;
+        const valid = requested.filter(m => ALL_METRICS.includes(m));
+        if (valid.length > 0)
+            metrics = valid;
+    }
+    // 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) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `# Analysis\n\n**JQL:** \`${jql}\`\n\nNo issues matched this query.`,
+                }],
+        };
+    }
+    const now = new Date();
+    const lines = [];
+    // Header
+    lines.push(`# Analysis: ${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 metrics) {
+        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

@@ -324,6 +324,33 @@ export const toolSchemas = {
             required: ['operation'],
         },
     },
+    analyze_jira_issues: {
+        name: 'analyze_jira_issues',
+        description: 'Compute project metrics over a set of issues selected by JQL. Returns deterministic calculations: earned value (story points), effort tracking, schedule risk, flow/cycle metrics, and distribution breakdowns. Use this when asked about totals, progress, overdue items, workload balance, or any quantitative question about issues.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                jql: {
+                    type: 'string',
+                    description: 'JQL query selecting the issues to analyze. Examples: "sprint in openSprints()", "project = AA AND fixVersion = 2.0", "assignee = currentUser() AND resolution = Unresolved".',
+                },
+                metrics: {
+                    type: 'array',
+                    items: {
+                        type: 'string',
+                        enum: ['points', 'time', 'schedule', 'cycle', 'distribution'],
+                    },
+                    description: 'Which metric groups to include. Default: all. points = earned value/SPI, time = effort estimates, schedule = due dates/overdue/risk, cycle = lead time/throughput/age, distribution = counts by status/assignee/priority/type.',
+                },
+                maxResults: {
+                    type: 'integer',
+                    description: 'Max issues to analyze (default 100, max 500).',
+                    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 +364,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.0",
   "mcpName": "io.github.aaronsb/jira-cloud",
   "description": "Model Context Protocol (MCP) server for Jira Cloud - enables AI assistants to interact with Jira",
   "type": "module",