@aaronsb/jira-cloud-mcp 0.5.0 → 0.5.2

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,26 @@ 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). cube_setup discovers dimensions. Others fetch issue data (subject to maxResults).",
+                values: ["summary", "cube_setup", "points", "time", "schedule", "cycle", "distribution"],
+            },
+            groupBy: {
+                type: "string",
+                description: "Split summary counts by dimension. Supports all dimensions. Use cube_setup to discover values first.",
+                values: ["project", "assignee", "priority", "issuetype"],
+            },
+            compute: {
+                type: "array of strings",
+                description: "Computed columns for summary tables. Each: 'name = expr'. Arithmetic, comparisons, column refs. Implicit measures: bugs, unassigned, no_due_date, blocked.",
             },
             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 and compute for data cube queries.",
+            cube_setup: "Discover available dimensions and values from a sample. Returns dimension catalog and cost estimates. Use before cube execute.",
             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 +500,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,14 +522,22 @@ 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: "Summary only", code: { jql: "project = AA", metrics: ["summary"] } },
+                ],
+            },
+            {
+                title: "Data cube — discover then compute",
+                description: "Two-phase analysis with computed columns:",
                 steps: [
-                    { description: "Distribution only", code: { jql: "project = AA AND resolution = Unresolved", metrics: ["distribution"] } },
+                    { description: "Discover dimensions", code: { jql: "project in (AA, GC, GD, LGS) AND resolution = Unresolved", metrics: ["cube_setup"] } },
+                    { description: "Execute with compute", code: { jql: "project in (AA, GC, GD, LGS) AND resolution = Unresolved", metrics: ["summary"], groupBy: "project", compute: ["bug_pct = bugs / total * 100", "net_flow = created_7d - resolved_7d", "clearing = resolved_7d > created_7d"] } },
                 ],
             },
         ],
-        related_resources: [],
+        related_resources: ["jira://analysis/recipes"],
     };
 }
 function generateGenericToolDocumentation(toolName, schema) {

package/build/handlers/analysis-handler.js

@@ -1,8 +1,16 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { evaluateRow, extractColumnRefs, parseComputeList } from '../utils/cube-dsl.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;
+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 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 ────────────────────────────────────────────────────────────
 function bucketStatus(category) {
     switch (category) {
@@ -217,6 +225,287 @@ 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}`;
+}
+/** Implicit measures — lazily resolved if referenced in compute expressions */
+const IMPLICIT_MEASURES = {
+    bugs: 'issuetype = Bug AND resolution = Unresolved',
+    unassigned: 'assignee is EMPTY AND resolution = Unresolved',
+    no_due_date: 'dueDate is EMPTY AND resolution = Unresolved',
+    blocked: 'status = Blocked',
+};
+/** Map dimension values to JQL clauses for groupBy scoping */
+export function groupByJqlClause(dimension, values) {
+    switch (dimension) {
+        case 'project':
+            return values.map(v => `project = ${v}`);
+        case 'assignee':
+            return values.map(v => v === 'Unassigned' ? 'assignee is EMPTY' : `assignee = "${v}"`);
+        case 'priority':
+            return values.map(v => `priority = "${v}"`);
+        case 'issuetype':
+            return values.map(v => `issuetype = "${v}"`);
+    }
+}
+async function buildCountRow(jiraClient, label, baseJql, implicitMeasureNames) {
+    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')),
+    ]);
+    let implicitMeasures;
+    if (implicitMeasureNames && implicitMeasureNames.length > 0) {
+        const counts = await Promise.all(implicitMeasureNames.map(name => jiraClient.countIssues(scopeJql(baseJql, IMPLICIT_MEASURES[name]))));
+        implicitMeasures = {};
+        for (let i = 0; i < implicitMeasureNames.length; i++) {
+            implicitMeasures[implicitMeasureNames[i]] = counts[i];
+        }
+    }
+    return { label, total, unresolved, overdue, highPriority, createdRecently, resolvedRecently, implicitMeasures };
+}
+export function renderSummaryTable(rows, computeColumns) {
+    const lines = ['## Summary (exact counts)', ''];
+    const extraHeaders = computeColumns?.map(c => c.name) ?? [];
+    const headerExtra = extraHeaders.map(h => ` ${h} |`).join('');
+    const alignExtra = extraHeaders.map(() => '---:|').join('');
+    lines.push(`| Scope | Total | Open | Overdue | High+ | Created 7d | Resolved 7d |${headerExtra}`);
+    lines.push(`|-------|------:|-----:|--------:|------:|-----------:|------------:|${alignExtra}`);
+    for (const r of rows) {
+        let computed = '';
+        if (computeColumns && computeColumns.length > 0) {
+            const rowMap = countRowToMap(r);
+            const results = evaluateRow(computeColumns, rowMap);
+            computed = results.map(res => {
+                const val = typeof res.value === 'number' ? formatComputed(res.value) : res.value;
+                return ` ${val} |`;
+            }).join('');
+        }
+        lines.push(`| ${r.label} | ${r.total} | ${r.unresolved} | ${r.overdue} | ${r.highPriority} | ${r.createdRecently} | ${r.resolvedRecently} |${computed}`);
+    }
+    // Totals row if multiple
+    if (rows.length > 1) {
+        const sum = (fn) => rows.reduce((s, r) => s + fn(r), 0);
+        const totalExtra = extraHeaders.map(() => ' — |').join('');
+        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)}** |${totalExtra}`);
+    }
+    return lines.join('\n');
+}
+/** Convert a CountRow to a Map for DSL evaluation */
+function countRowToMap(row) {
+    const m = new Map();
+    m.set('total', row.total);
+    m.set('open', row.unresolved);
+    m.set('overdue', row.overdue);
+    m.set('high', row.highPriority);
+    m.set('created_7d', row.createdRecently);
+    m.set('resolved_7d', row.resolvedRecently);
+    // Add implicit measure values if present
+    if (row.implicitMeasures) {
+        for (const [k, v] of Object.entries(row.implicitMeasures)) {
+            m.set(k, v);
+        }
+    }
+    return m;
+}
+/** Format a computed number — round to 1 decimal if fractional */
+function formatComputed(n) {
+    return Number.isInteger(n) ? String(n) : n.toFixed(1);
+}
+/** Compute max groups that fit within the query budget */
+function maxGroupsForBudget(implicitCount) {
+    const queriesPerGroup = STANDARD_MEASURES + implicitCount;
+    return Math.floor(MAX_COUNT_QUERIES / queriesPerGroup);
+}
+async function handleSummary(jiraClient, jql, groupBy, compute) {
+    const lines = [];
+    lines.push(`# Summary: ${jql}`);
+    lines.push(`As of ${formatDateShort(new Date())} — counts are exact (no sampling cap)`);
+    // Detect implicit measures needed by compute expressions
+    const neededImplicits = compute ? detectImplicitMeasures(compute) : [];
+    const groupBudget = maxGroupsForBudget(neededImplicits.length);
+    if (groupBy === 'project') {
+        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;
+        if (capped)
+            keys = keys.slice(0, groupBudget);
+        const remaining = removeProjectClause(jql);
+        const rows = await Promise.all(keys.map(k => buildCountRow(jiraClient, k, remaining ? `project = ${k} AND (${remaining})` : `project = ${k}`, neededImplicits)));
+        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*`);
+        }
+    }
+    else if (groupBy) {
+        // For non-project groupBy, sample per-project for representative dimension values
+        const issues = await samplePerProject(jiraClient, jql);
+        if (issues.length === 0) {
+            throw new McpError(ErrorCode.InvalidParams, `No issues matched JQL — cannot discover ${groupBy} values`);
+        }
+        const dims = extractDimensions(issues);
+        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);
+        const jqlClause = groupByJqlClause(groupBy, cappedValues);
+        const rows = await Promise.all(cappedValues.map((value, idx) => buildCountRow(jiraClient, value, `(${jql}) AND ${jqlClause[idx]}`, neededImplicits)));
+        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})*`);
+        }
+    }
+    else {
+        // No groupBy — single row for the whole JQL
+        const row = await buildCountRow(jiraClient, 'All', jql, neededImplicits);
+        lines.push('');
+        lines.push(renderSummaryTable([row], compute));
+    }
+    return lines.join('\n');
+}
+/** Detect which implicit measures are referenced by compute expressions */
+function detectImplicitMeasures(compute) {
+    const refs = extractColumnRefs(compute);
+    return Object.keys(IMPLICIT_MEASURES).filter(name => refs.has(name));
+}
+/** Extract distinct dimension values from sampled issues */
+export function extractDimensions(issues) {
+    const dims = [
+        { name: 'project', extractor: i => i.key.split('-')[0] },
+        { name: 'status', extractor: i => i.status },
+        { name: 'assignee', extractor: i => i.assignee || 'Unassigned' },
+        { name: 'priority', extractor: i => i.priority || 'None' },
+        { name: 'issuetype', extractor: i => i.issueType || 'Unknown' },
+    ];
+    return dims.map(({ name, extractor }) => {
+        const counts = new Map();
+        for (const issue of issues) {
+            const val = extractor(issue);
+            counts.set(val, (counts.get(val) || 0) + 1);
+        }
+        // Sort by count descending, cap at MAX_CUBE_GROUPS
+        const sorted = [...counts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, MAX_CUBE_GROUPS);
+        return {
+            name,
+            values: sorted.map(([v]) => v),
+            count: counts.size,
+        };
+    });
+}
+/** Render cube setup response with dimension catalog and cost estimates */
+export function renderCubeSetup(jql, sampleSize, dimensions) {
+    const lines = [`# Cube Setup: ${jql}`, `Sampled ${sampleSize} issues to discover dimensions.`, ''];
+    // Dimension table
+    lines.push('## Available Dimensions');
+    lines.push('| Dimension | Distinct Values | Count |');
+    lines.push('|-----------|----------------|------:|');
+    for (const dim of dimensions) {
+        const displayed = dim.values.slice(0, 5).join(', ');
+        const more = dim.count > 5 ? ` +${dim.count - 5}` : '';
+        lines.push(`| ${dim.name} | ${displayed}${more} | ${dim.count} |`);
+    }
+    // Available measures
+    lines.push('');
+    lines.push('## Available Measures');
+    lines.push('Standard columns per group (via count API):');
+    lines.push('- total, open, overdue, high+, created_7d, resolved_7d');
+    lines.push('');
+    lines.push('Implicit measures (lazily resolved if referenced in `compute`):');
+    lines.push('- bugs, unassigned, no_due_date, blocked');
+    // Suggested cubes with cost estimates
+    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 queries = groups * STANDARD_MEASURES;
+        const estSeconds = Math.max(1, Math.round(queries / 12)); // ~12 parallel queries/sec
+        const withinBudget = queries <= MAX_COUNT_QUERIES;
+        const badge = withinBudget ? '' : ' ⚠️ add compute measures to stay in budget';
+        lines.push(`- \`groupBy: "${dim.name}"\` — ${groups} groups, ${queries} base queries (~${estSeconds}s)${badge}`);
+    }
+    return lines.join('\n');
+}
+/** Compute dynamic sample size: 20% of total, clamped to [50, 500] */
+async function computeSampleSize(jiraClient, jql) {
+    const total = await jiraClient.countIssues(jql);
+    return Math.max(CUBE_SAMPLE_MIN, Math.min(CUBE_SAMPLE_MAX, Math.ceil(total * CUBE_SAMPLE_PCT)));
+}
+/** Sample issues across all projects in scope for representative dimension discovery */
+async function samplePerProject(jiraClient, jql) {
+    let projectKeys = extractProjectKeys(jql);
+    if (projectKeys.length === 0) {
+        const allProjects = await jiraClient.listProjects();
+        projectKeys = allProjects.map(p => p.key);
+    }
+    const sampleSize = await computeSampleSize(jiraClient, jql);
+    if (projectKeys.length <= 1) {
+        const result = await jiraClient.searchIssuesLean(jql, sampleSize);
+        return result.issues;
+    }
+    const remaining = removeProjectClause(jql);
+    const perProject = Math.max(5, Math.floor(sampleSize / projectKeys.length));
+    const samples = await Promise.all(projectKeys.map(async (k) => {
+        const scopedJql = remaining ? `project = ${k} AND (${remaining})` : `project = ${k}`;
+        try {
+            const result = await jiraClient.searchIssuesLean(scopedJql, perProject);
+            return result.issues;
+        }
+        catch {
+            return [];
+        }
+    }));
+    return samples.flat();
+}
+async function handleCubeSetup(jiraClient, jql) {
+    const issues = await samplePerProject(jiraClient, jql);
+    if (issues.length === 0) {
+        return `# Cube Setup: ${jql}\n\nNo issues matched this query. Cannot discover dimensions.`;
+    }
+    // Extract dimensions — project dimension uses actual keys from sample
+    // (samplePerProject ensures coverage across all projects in scope)
+    const dimensions = extractDimensions(issues);
+    return renderCubeSetup(jql, issues.length, dimensions);
+}
 // ── Main Handler ───────────────────────────────────────────────────────
 export async function handleAnalysisRequest(jiraClient, request) {
     const args = normalizeArgs(request.params?.arguments || {});
@@ -224,16 +513,48 @@ 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 hasCubeSetup = requested.includes('cube_setup');
+    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;
+    // Parse compute expressions
+    let compute;
+    if (args.compute && Array.isArray(args.compute) && args.compute.length > 0) {
+        compute = parseComputeList(args.compute);
+    }
+    // Cube setup — discover dimensions from sample, no issue fetching
+    if (hasCubeSetup) {
+        const cubeText = await handleCubeSetup(jiraClient, jql);
+        const nextSteps = analysisNextSteps(jql, []);
+        return {
+            content: [{
+                    type: 'text',
+                    text: cubeText + '\n' + nextSteps,
+                }],
+        };
     }
+    // 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, []);
+        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 +581,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
             break;
         }
     }
-    if (allIssues.length === 0) {
+    if (allIssues.length === 0 && !hasSummary) {
         return {
             content: [{
                     type: 'text',
@@ -270,23 +591,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.*`);
-    }
-    // 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]());
+    // Summary first if requested alongside other metrics
+    if (hasSummary) {
+        const summaryText = await handleSummary(jiraClient, jql, groupBy, compute);
+        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));

package/build/handlers/resource-handlers.js

@@ -41,6 +41,12 @@ export function setupResourceHandlers(jiraClient) {
                         mimeType: 'application/json',
                         description: 'Discovered custom fields ranked by usage — names, types, descriptions, writability'
                     },
+                    {
+                        uri: 'jira://analysis/recipes',
+                        name: 'Analysis Query Recipes',
+                        mimeType: 'text/markdown',
+                        description: 'Composition patterns for analyze_jira_issues — how to combine summary counts, groupBy, and JQL for PM dashboards'
+                    },
                     // Add tool resources
                     ...toolResources.resources
                 ]
@@ -92,6 +98,9 @@ export function setupResourceHandlers(jiraClient) {
                 if (uri === 'jira://custom-fields') {
                     return getCustomFieldsCatalog();
                 }
+                if (uri === 'jira://analysis/recipes') {
+                    return getAnalysisRecipes();
+                }
                 // Handle resource templates
                 const projectMatch = uri.match(/^jira:\/\/projects\/([^/]+)\/overview$/);
                 if (projectMatch) {
@@ -356,6 +365,118 @@ async function getContextCustomFields(jiraClient, projectKey, issueType) {
             }],
     };
 }
+/**
+ * Returns analysis query recipes — composition patterns for the analyze_jira_issues tool
+ */
+function getAnalysisRecipes() {
+    const markdown = `# Analysis Query Recipes
+
+## Two Layers
+
+Stack these for magnitude + detail:
+
+1. **Count layer** — \`analyze_jira_issues\` with \`metrics: ["summary"]\` + \`groupBy: "project"\` → exact counts, no cap
+2. **Detail layer** — \`analyze_jira_issues\` with other metrics, or \`manage_jira_filter\` execute_jql → individual issues
+
+## Recipes
+
+### Project Health Snapshot
+**Question:** Which projects are busiest / most at-risk?
+\`\`\`json
+{ "jql": "project in (AA, LGS, GD, GC) AND resolution = Unresolved", "metrics": ["summary"], "groupBy": "project" }
+\`\`\`
+
+### Net Flow / Velocity
+**Question:** Are we resolving faster than creating?
+Run two summary queries and subtract:
+- \`created >= -7d\` with \`groupBy: "project"\` → created this week
+- \`resolved >= -7d\` with \`groupBy: "project"\` → resolved this week
+Net = created - resolved. Positive = growing backlog. Negative = clearing.
+
+### Bug Ratio
+**Question:** How much open work is bugs vs planned?
+\`\`\`json
+{ "jql": "issuetype = Bug AND resolution = Unresolved", "metrics": ["summary"], "groupBy": "project" }
+\`\`\`
+
+### Overdue Breakdown
+**Question:** Where are we most behind?
+\`\`\`json
+{ "jql": "resolution = Unresolved AND dueDate < now()", "metrics": ["summary"], "groupBy": "project" }
+\`\`\`
+
+### Deadline Pressure Window
+**Question:** What's due in the next 2 weeks?
+\`\`\`json
+{ "jql": "resolution = Unresolved AND dueDate >= now() AND dueDate <= 14d", "metrics": ["summary"], "groupBy": "project" }
+\`\`\`
+
+### Stale Backlog
+**Question:** How much backlog needs grooming?
+\`\`\`json
+{ "jql": "status = Backlog AND created <= -90d", "metrics": ["summary"], "groupBy": "project" }
+\`\`\`
+
+### Ownership Gaps
+**Question:** What has no owner?
+\`\`\`json
+{ "jql": "resolution = Unresolved AND assignee is EMPTY", "metrics": ["summary"], "groupBy": "project" }
+\`\`\`
+
+### Planning Coverage
+**Question:** How much work has no due date?
+\`\`\`json
+{ "jql": "resolution = Unresolved AND dueDate is EMPTY", "metrics": ["summary"], "groupBy": "project" }
+\`\`\`
+
+## Data Cube (Advanced)
+
+For multi-dimensional analysis, use the two-phase cube pattern:
+
+### Phase 1: Discover dimensions
+\`\`\`json
+{ "jql": "project in (AA, LGS, GD, GC) AND resolution = Unresolved", "metrics": ["cube_setup"] }
+\`\`\`
+Returns available dimensions, their values, and cost estimates for each groupBy option.
+
+### Phase 2: Execute with computed columns
+\`\`\`json
+{ "jql": "project in (AA, LGS, GD, GC) AND resolution = Unresolved", "metrics": ["summary"], "groupBy": "project", "compute": ["bug_pct = bugs / total * 100", "net_flow = created_7d - resolved_7d", "clearing = resolved_7d > created_7d"] }
+\`\`\`
+
+### Compute DSL
+- Arithmetic: \`+\`, \`-\`, \`*\`, \`/\`
+- Comparisons: \`>\`, \`<\`, \`>=\`, \`<=\`, \`==\`, \`!=\` (produce Yes/No)
+- Standard columns: total, open, overdue, high, created_7d, resolved_7d
+- Implicit measures (lazily resolved): bugs, unassigned, no_due_date, blocked
+- Max 5 expressions per query
+
+### Example computed columns
+- \`bug_pct = bugs / total * 100\` — bug ratio as percentage
+- \`net_flow = created_7d - resolved_7d\` — positive = growing backlog
+- \`clearing = resolved_7d > created_7d\` — Yes/No: is backlog shrinking?
+- \`risk = overdue > 10\` — Yes/No flag for at-risk projects
+- \`velocity = resolved_7d / 7\` — daily throughput
+
+## Key Patterns
+
+- \`groupBy: "project"\` turns any query into a cross-project comparison table with exact counts
+- \`groupBy: "assignee"\` / \`"priority"\` / \`"issuetype"\` — slice by any dimension
+- \`compute\` adds derived columns without extra tool calls
+- Two summary queries = velocity (created vs resolved over same window)
+- \`dueDate is EMPTY\` surfaces planning gaps that overdue queries miss
+- \`assignee is EMPTY AND priority in (High, Highest)\` = high-priority work with no owner (most actionable)
+- Use \`cube_setup\` first to discover dimensions, then \`summary\` + \`groupBy\` + \`compute\` to execute
+- Use \`summary\` for cross-project scope, then \`distribution\`/\`schedule\` per-project for detail
+`;
+    return {
+        contents: [{
+                uri: 'jira://analysis/recipes',
+                mimeType: 'text/markdown',
+                text: markdown,
+            }],
+    };
+}
 /**
  * Gets all available issue link types
  */

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,36 @@ 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). Read jira://analysis/recipes for composition patterns.',
         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', 'cube_setup'],
                     },
-                    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). 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.',
+                },
+                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.',
+                },
+                compute: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    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, blocked. Max 5 expressions. Example: ["bug_pct = bugs / total * 100", "clearing = resolved_7d > created_7d"].',
+                    maxItems: 5,
                 },
                 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/build/utils/cube-dsl.js

@@ -0,0 +1,249 @@
+/**
+ * Bounded DSL for computed columns in data cube queries.
+ *
+ * Expressions: `name = expr` where expr supports:
+ * - Column references (any existing column name)
+ * - Numeric literals
+ * - Arithmetic: + - * /
+ * - Comparisons: > < >= <= == != (produce Yes/No)
+ *
+ * Evaluation is linear — each expression can reference columns from
+ * earlier expressions. No functions, no loops, no nesting beyond parens.
+ */
+const MAX_EXPRESSIONS = 5;
+const OP_CHARS = new Set(['+', '-', '*', '/', '>', '<', '=', '!']);
+/** Parse a compute expression string into name + expr */
+export function parseComputeExpr(raw) {
+    const eqIdx = raw.indexOf('=');
+    // Must have = that isn't part of == or != or >= or <=
+    if (eqIdx === -1) {
+        throw new Error(`Invalid compute expression: missing "=" in "${raw}"`);
+    }
+    // Find the first = that is an assignment (not ==, !=, >=, <=)
+    let assignIdx = -1;
+    for (let i = 0; i < raw.length; i++) {
+        if (raw[i] === '=') {
+            const prev = i > 0 ? raw[i - 1] : '';
+            const next = i + 1 < raw.length ? raw[i + 1] : '';
+            if (prev !== '!' && prev !== '>' && prev !== '<' && prev !== '=' && next !== '=') {
+                assignIdx = i;
+                break;
+            }
+        }
+    }
+    if (assignIdx === -1) {
+        throw new Error(`Invalid compute expression: no assignment "=" found in "${raw}"`);
+    }
+    const name = raw.slice(0, assignIdx).trim();
+    const expr = raw.slice(assignIdx + 1).trim();
+    if (!name || !/^[a-zA-Z_]\w*$/.test(name)) {
+        throw new Error(`Invalid column name: "${name}"`);
+    }
+    if (!expr) {
+        throw new Error(`Empty expression for column "${name}"`);
+    }
+    return { name, expr };
+}
+/** Tokenize an expression string */
+function tokenize(expr) {
+    const tokens = [];
+    let i = 0;
+    while (i < expr.length) {
+        // Skip whitespace
+        if (expr[i] === ' ' || expr[i] === '\t') {
+            i++;
+            continue;
+        }
+        // Parentheses
+        if (expr[i] === '(' || expr[i] === ')') {
+            tokens.push({ type: 'paren', value: expr[i] });
+            i++;
+            continue;
+        }
+        // Operators (multi-char first: >=, <=, ==, !=)
+        if (OP_CHARS.has(expr[i])) {
+            const two = expr.slice(i, i + 2);
+            if (['>=', '<=', '==', '!='].includes(two)) {
+                tokens.push({ type: 'op', value: two });
+                i += 2;
+                continue;
+            }
+            if (['+', '-', '*', '/', '>', '<'].includes(expr[i])) {
+                tokens.push({ type: 'op', value: expr[i] });
+                i++;
+                continue;
+            }
+        }
+        // Numbers (integers and decimals)
+        if (/\d/.test(expr[i])) {
+            let num = '';
+            while (i < expr.length && /[\d.]/.test(expr[i])) {
+                num += expr[i];
+                i++;
+            }
+            tokens.push({ type: 'number', value: num });
+            continue;
+        }
+        // Identifiers (column names)
+        if (/[a-zA-Z_]/.test(expr[i])) {
+            let ident = '';
+            while (i < expr.length && /\w/.test(expr[i])) {
+                ident += expr[i];
+                i++;
+            }
+            tokens.push({ type: 'ident', value: ident });
+            continue;
+        }
+        throw new Error(`Unexpected character "${expr[i]}" in expression`);
+    }
+    return tokens;
+}
+/**
+ * Evaluate a tokenized expression with operator precedence.
+ * Uses a simple recursive descent: comparison < additive < multiplicative < primary
+ */
+function evaluate(tokens, columns) {
+    let pos = 0;
+    function peek() { return tokens[pos]; }
+    function advance() { return tokens[pos++]; }
+    function primary() {
+        const tok = peek();
+        if (!tok)
+            throw new Error('Unexpected end of expression');
+        if (tok.type === 'paren' && tok.value === '(') {
+            advance(); // consume (
+            const val = additiveExpr();
+            const close = peek();
+            if (!close || close.value !== ')')
+                throw new Error('Missing closing parenthesis');
+            advance(); // consume )
+            return val;
+        }
+        if (tok.type === 'number') {
+            advance();
+            const num = parseFloat(tok.value);
+            if (isNaN(num))
+                throw new Error(`Invalid number: "${tok.value}"`);
+            return num;
+        }
+        if (tok.type === 'ident') {
+            advance();
+            const val = columns.get(tok.value);
+            if (val === undefined)
+                throw new Error(`Unknown column: "${tok.value}"`);
+            return val;
+        }
+        throw new Error(`Unexpected token: "${tok.value}"`);
+    }
+    function multiplicativeExpr() {
+        let left = primary();
+        while (peek()?.type === 'op' && (peek().value === '*' || peek().value === '/')) {
+            const op = advance().value;
+            const right = primary();
+            if (op === '*')
+                left *= right;
+            else
+                left = right === 0 ? 0 : left / right; // division by zero → 0
+        }
+        return left;
+    }
+    function additiveExpr() {
+        let left = multiplicativeExpr();
+        while (peek()?.type === 'op' && (peek().value === '+' || peek().value === '-')) {
+            const op = advance().value;
+            const right = multiplicativeExpr();
+            if (op === '+')
+                left += right;
+            else
+                left -= right;
+        }
+        return left;
+    }
+    function comparisonExpr() {
+        const left = additiveExpr();
+        const tok = peek();
+        if (tok?.type === 'op' && ['>', '<', '>=', '<=', '==', '!='].includes(tok.value)) {
+            const op = advance().value;
+            const right = additiveExpr();
+            let result;
+            switch (op) {
+                case '>':
+                    result = left > right;
+                    break;
+                case '<':
+                    result = left < right;
+                    break;
+                case '>=':
+                    result = left >= right;
+                    break;
+                case '<=':
+                    result = left <= right;
+                    break;
+                case '==':
+                    result = left === right;
+                    break;
+                case '!=':
+                    result = left !== right;
+                    break;
+                default: throw new Error(`Unknown operator: "${op}"`);
+            }
+            return result ? 'Yes' : 'No';
+        }
+        return left;
+    }
+    const result = comparisonExpr();
+    if (pos < tokens.length) {
+        throw new Error(`Unexpected token after expression: "${tokens[pos].value}"`);
+    }
+    return result;
+}
+/** Parse and validate a list of compute expressions */
+export function parseComputeList(rawExpressions) {
+    if (rawExpressions.length > MAX_EXPRESSIONS) {
+        throw new Error(`Too many compute expressions (max ${MAX_EXPRESSIONS}, got ${rawExpressions.length})`);
+    }
+    const columns = [];
+    const names = new Set();
+    for (const raw of rawExpressions) {
+        const col = parseComputeExpr(raw);
+        if (names.has(col.name)) {
+            throw new Error(`Duplicate column name: "${col.name}"`);
+        }
+        names.add(col.name);
+        columns.push(col);
+    }
+    return columns;
+}
+/** Evaluate compute expressions against a row of column values */
+export function evaluateRow(columns, rowValues) {
+    // Work on a copy so computed columns accumulate
+    const ctx = new Map(rowValues);
+    const results = [];
+    for (const col of columns) {
+        const tokens = tokenize(col.expr);
+        const value = evaluate(tokens, ctx);
+        // Store numeric value in context for subsequent expressions
+        if (typeof value === 'number') {
+            ctx.set(col.name, value);
+        }
+        else {
+            // Boolean results stored as 1/0 for downstream references
+            ctx.set(col.name, value === 'Yes' ? 1 : 0);
+        }
+        results.push({ name: col.name, value });
+    }
+    return results;
+}
+/** Extract column references from expressions (for lazy measure detection) */
+export function extractColumnRefs(columns) {
+    const refs = new Set();
+    for (const col of columns) {
+        const tokens = tokenize(col.expr);
+        for (const tok of tokens) {
+            if (tok.type === 'ident') {
+                refs.add(tok.value);
+            }
+        }
+    }
+    return refs;
+}

package/build/utils/next-steps.js

@@ -130,6 +130,6 @@ export function analysisNextSteps(jql, issueKeys) {
     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);
+    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 } });
+    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.0",
+  "version": "0.5.2",
   "mcpName": "io.github.aaronsb/jira-cloud",
   "description": "Model Context Protocol (MCP) server for Jira Cloud - enables AI assistants to interact with Jira",
   "type": "module",