@aaronsb/jira-cloud-mcp 0.5.0 → 0.5.1

package/build/client/jira-client.js

@@ -408,6 +408,18 @@ export class JiraClient {
         });
     }
     /** 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, '"');

package/build/docs/tool-documentation.js

@@ -473,15 +473,21 @@ function generateAnalysisToolDocumentation(schema) {
             },
             metrics: {
                 type: "array of strings",
-                description: "Which metric groups to include. Default: all.",
-                values: ["points", "time", "schedule", "cycle", "distribution"],
+                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 analyze (default 100, max 500).",
+                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",
@@ -489,6 +495,13 @@ function generateAnalysisToolDocumentation(schema) {
             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:",
@@ -504,10 +517,10 @@ function generateAnalysisToolDocumentation(schema) {
                 ],
             },
             {
-                title: "Workload balance",
-                description: "See how work is distributed across team members:",
+                title: "Quick project overview",
+                description: "Get exact issue counts without fetching data:",
                 steps: [
-                    { description: "Distribution only", code: { jql: "project = AA AND resolution = Unresolved", metrics: ["distribution"] } },
+                    { description: "Summary only", code: { jql: "project = AA", metrics: ["summary"] } },
                 ],
             },
         ],

package/build/handlers/analysis-handler.js

@@ -2,6 +2,7 @@ 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) {
@@ -217,6 +218,89 @@ export function renderDistribution(issues) {
     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 || {});
@@ -224,16 +308,31 @@ export async function handleAnalysisRequest(jiraClient, request) {
     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;
+    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();
@@ -260,7 +359,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
             break;
         }
     }
-    if (allIssues.length === 0) {
+    if (allIssues.length === 0 && !hasSummary) {
         return {
             content: [{
                     type: 'text',
@@ -270,23 +369,32 @@ export async function handleAnalysisRequest(jiraClient, request) {
     }
     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.*`);
+    // Summary first if requested alongside other metrics
+    if (hasSummary) {
+        const summaryText = await handleSummary(jiraClient, jql, groupBy);
+        lines.push(summaryText);
     }
-    // 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]());
+    // 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));

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: {
@@ -326,25 +326,30 @@ export const toolSchemas = {
     },
     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.',
+        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: "sprint in openSprints()", "project = AA AND fixVersion = 2.0", "assignee = currentUser() AND resolution = Unresolved".',
+                    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: ['points', 'time', 'schedule', 'cycle', 'distribution'],
+                        enum: ['summary', '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.',
+                    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 analyze (default 100, max 500).',
+                    description: 'Max issues to fetch for detail metrics (default 100, max 500). Does not apply to summary (which uses count API).',
                     default: 100,
                 },
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaronsb/jira-cloud-mcp",
-  "version": "0.5.0",
+  "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",