@aaronsb/jira-cloud-mcp 0.5.1 → 0.5.3

package/README.md

@@ -40,26 +40,31 @@ Generate an API token at [Atlassian Account Settings](https://id.atlassian.com/m
 
 | Tool | Description |
 |------|-------------|
-| `manage_jira_issue` | Get, create, update, delete, move, transition, comment on, or link Jira issues |
+| `manage_jira_issue` | Get, create, update, delete, move, transition, comment on, link, or traverse hierarchy of issues |
 | `manage_jira_filter` | Search for issues using JQL queries, or manage saved filters |
-| `manage_jira_project` | List projects or get project details including status counts |
+| `manage_jira_project` | List projects or get project configuration and metadata |
 | `manage_jira_board` | List boards or get board details and configuration |
 | `manage_jira_sprint` | Manage sprints: create, start, close, and assign issues to sprints |
-| `queue_jira_operations` | Execute multiple operations in one call with result references and error strategies |
+| `queue_jira_operations` | Batch multiple operations with result references (`$0.key`) and error strategies |
+| `analyze_jira_issues` | Compute metrics, exact counts, and data cube analysis over issues selected by JQL |
 
-Each tool accepts an `operation` parameter (except `queue_jira_operations` which takes an `operations` array). Detailed documentation is available as MCP resources at `jira://tools/{tool_name}/documentation`.
+Each tool accepts an `operation` parameter (except `queue_jira_operations` which takes an `operations` array, and `analyze_jira_issues` which takes `jql` + `metrics`). Per-tool documentation is available as MCP resources at `jira://tools/{tool_name}/documentation`.
+
+See [docs/tools.md](docs/tools.md) for detailed tool descriptions, workspace patterns, and design principles.
 
 ## MCP Resources
 
 | Resource | Description |
 |----------|-------------|
 | `jira://instance/summary` | Instance-level statistics |
+| `jira://projects/distribution` | Project distribution overview |
 | `jira://projects/{key}/overview` | Project overview with status counts |
 | `jira://boards/{id}/overview` | Board overview with sprint info |
 | `jira://issue-link-types` | Available issue link types |
 | `jira://custom-fields` | Custom field catalog (auto-discovered at startup) |
 | `jira://custom-fields/{project}/{issueType}` | Context-specific custom fields |
-| `jira://tools/{name}/documentation` | Tool documentation |
+| `jira://analysis/recipes` | Analysis query patterns and compute DSL reference |
+| `jira://tools/{name}/documentation` | Per-tool documentation |
 
 ## License
 

package/build/client/jira-client.js

@@ -8,6 +8,10 @@ export class JiraClient {
     get v3Client() {
         return this.client;
     }
+    /** Expose custom field IDs for JQL construction outside the client */
+    get customFieldIds() {
+        return this.customFields;
+    }
     constructor(config) {
         const clientConfig = {
             host: config.host,

package/build/docs/tool-documentation.js

@@ -473,21 +473,26 @@ function generateAnalysisToolDocumentation(schema) {
             },
             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"],
+                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. Use with metrics: ['summary'].",
+                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, no_estimate, no_start_date, no_labels, blocked.",
+            },
             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.",
+            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",
@@ -523,8 +528,16 @@ function generateAnalysisToolDocumentation(schema) {
                     { description: "Summary only", code: { jql: "project = AA", metrics: ["summary"] } },
                 ],
             },
+            {
+                title: "Data cube — discover then compute",
+                description: "Two-phase analysis with computed columns:",
+                steps: [
+                    { 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,9 +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) {
@@ -241,11 +248,50 @@ export function removeProjectClause(jql) {
         .replace(/\s*AND\s*$/i, '')
         .trim();
 }
+/** Run async tasks in batches to avoid API rate limiting */
+async function batchParallel(tasks, batchSize) {
+    const results = [];
+    for (let i = 0; i < tasks.length; i += batchSize) {
+        const batch = tasks.slice(i, i + batchSize);
+        results.push(...await Promise.all(batch.map(fn => fn())));
+    }
+    return results;
+}
+const ROW_BATCH_SIZE = 3; // ~18-33 concurrent count queries per batch
 /** 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) {
+/** Implicit measures — lazily resolved if referenced in compute expressions.
+ *  Built dynamically because some use custom field IDs. */
+function buildImplicitMeasures(customFieldIds) {
+    const 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',
+        no_labels: 'labels is EMPTY AND resolution = Unresolved',
+    };
+    if (customFieldIds) {
+        measures.no_estimate = `${customFieldIds.storyPoints} is EMPTY AND resolution = Unresolved`;
+        measures.no_start_date = `${customFieldIds.startDate} is EMPTY AND resolution = Unresolved`;
+    }
+    return measures;
+}
+/** 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, implicitMeasureDefs) {
     const [total, unresolved, overdue, highPriority, createdRecently, resolvedRecently] = await Promise.all([
         jiraClient.countIssues(baseJql),
         jiraClient.countIssues(scopeJql(baseJql, 'resolution = Unresolved')),
@@ -254,53 +300,232 @@ async function buildCountRow(jiraClient, label, baseJql) {
         jiraClient.countIssues(scopeJql(baseJql, 'created >= -7d')),
         jiraClient.countIssues(scopeJql(baseJql, 'resolved >= -7d')),
     ]);
-    return { label, total, unresolved, overdue, highPriority, createdRecently, resolvedRecently };
+    let implicitMeasures;
+    if (implicitMeasureNames && implicitMeasureNames.length > 0 && implicitMeasureDefs) {
+        const counts = await Promise.all(implicitMeasureNames.map(name => jiraClient.countIssues(scopeJql(baseJql, implicitMeasureDefs[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) {
+export function renderSummaryTable(rows, computeColumns) {
     const lines = ['## Summary (exact counts)', ''];
-    lines.push('| Scope | Total | Open | Overdue | High+ | Created 7d | Resolved 7d |');
-    lines.push('|-------|------:|-----:|--------:|------:|-----------:|------------:|');
+    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) {
-        lines.push(`| ${r.label} | ${r.total} | ${r.unresolved} | ${r.overdue} | ${r.highPriority} | ${r.createdRecently} | ${r.resolvedRecently} |`);
+        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);
-        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)}** |`);
+        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');
 }
-async function handleSummary(jiraClient, jql, groupBy) {
+/** 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)`);
+    // Build implicit measures with custom field IDs for JQL construction
+    const implicitDefs = buildImplicitMeasures(jiraClient.customFieldIds);
+    const neededImplicits = compute ? detectImplicitMeasures(compute, implicitDefs) : [];
+    const groupBudget = maxGroupsForBudget(neededImplicits.length);
     if (groupBy === 'project') {
-        const keys = extractProjectKeys(jql);
+        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}`)));
+        const rows = await batchParallel(keys.map(k => () => buildCountRow(jiraClient, k, remaining ? `project = ${k} AND (${remaining})` : `project = ${k}`, neededImplicits, implicitDefs)), ROW_BATCH_SIZE);
         rows.sort((a, b) => b.unresolved - a.unresolved);
         lines.push('');
-        lines.push(renderSummaryTable(rows));
+        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, get the overall count first
-        const overallRow = await buildCountRow(jiraClient, 'All', jql);
-        lines.push('');
-        lines.push(renderSummaryTable([overallRow]));
+        // 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 batchParallel(cappedValues.map((value, idx) => () => buildCountRow(jiraClient, value, `(${jql}) AND ${jqlClause[idx]}`, neededImplicits, implicitDefs)), ROW_BATCH_SIZE);
+        rows.sort((a, b) => b.unresolved - a.unresolved);
         lines.push('');
-        lines.push(`*groupBy "${groupBy}" — only "project" supports per-group breakdown currently. Other dimensions coming soon.*`);
+        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);
+        const row = await buildCountRow(jiraClient, 'All', jql, neededImplicits, implicitDefs);
         lines.push('');
-        lines.push(renderSummaryTable([row]));
+        lines.push(renderSummaryTable([row], compute));
     }
     return lines.join('\n');
 }
+/** Detect which implicit measures are referenced by compute expressions */
+function detectImplicitMeasures(compute, implicitMeasureDefs) {
+    const refs = extractColumnRefs(compute);
+    return Object.keys(implicitMeasureDefs).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, no_estimate, no_start_date, no_labels, 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 || {});
@@ -313,6 +538,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
         ? 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;
@@ -320,9 +546,25 @@ export async function handleAnalysisRequest(jiraClient, request) {
     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);
+        const summaryText = await handleSummary(jiraClient, jql, groupBy, compute);
         const nextSteps = analysisNextSteps(jql, []);
         return {
             content: [{
@@ -371,7 +613,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
     const lines = [];
     // Summary first if requested alongside other metrics
     if (hasSummary) {
-        const summaryText = await handleSummary(jiraClient, jql, groupBy);
+        const summaryText = await handleSummary(jiraClient, jql, groupBy, compute);
         lines.push(summaryText);
     }
     // Header for fetch-based metrics

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,110 @@ 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
+
+## Foundation Rules
+
+- **Always start with cube_setup** on unfamiliar JQL before committing to a query. It tells you what dimensions exist, how many distinct values each has, and estimates query cost. Think of it as DESCRIBE TABLE before a SQL query.
+- **\`metrics: ["summary"] + groupBy: "project"\` is your default opening move.** It's exact (no sampling cap), fast, and gives you a cross-project comparison in one call. Use everything else to drill down after.
+- **The \`distribution\` metric is rich but capped at 500 issues.** Only use it scoped to a single project, never cross-project. Mixing it into a broad query will silently undersample.
+- **\`manage_jira_project\` issue counts cap at 100** — never use it for actual counts, only for metadata. \`analyze_jira_issues\` with \`metrics: ["summary"]\` is always more accurate.
+
+## Core Recipes
+
+### Org-wide Health Snapshot
+**Question:** Which projects are busiest / most at-risk?
+\`\`\`json
+{ "jql": "project in (...) AND resolution = Unresolved", "metrics": ["summary"], "groupBy": "project", "compute": ["overdue_pct = overdue / open * 100", "high_pct = high / open * 100", "clearing = resolved_7d > created_7d", "planning_gap = no_due_date / open * 100"] }
+\`\`\`
+One query, full picture. The \`clearing\` boolean immediately flags which projects are accumulating debt.
+
+### Net Flow / Velocity
+**Question:** Are we resolving faster than creating?
+\`\`\`json
+{ "jql": "project in (...) AND (created >= -7d OR resolved >= -7d)", "metrics": ["summary"], "groupBy": "project", "compute": ["net_flow = resolved_7d - created_7d", "clearing = resolved_7d > created_7d"] }
+\`\`\`
+Positive net_flow = clearing, negative = accumulating. The OR condition in JQL ensures you capture both sides of the ledger.
+
+### Team Workload Scorecard
+**Question:** Who is overloaded or under-tracked?
+\`\`\`json
+{ "jql": "project in (...) AND resolution = Unresolved AND assignee is not EMPTY", "metrics": ["summary"], "groupBy": "assignee", "compute": ["overdue_pct = overdue / open * 100", "high_pct = high / open * 100", "no_dates = no_due_date / open * 100"] }
+\`\`\`
+The \`no_dates\` column is the secret ingredient — it distinguishes "this person is behind" from "this person has no dates set so overdue looks artificially low." Scope to 2-3 projects max.
+
+### Planning Gap Detector
+**Question:** Where is risk invisible?
+\`\`\`json
+{ "jql": "resolution = Unresolved AND dueDate is EMPTY", "metrics": ["summary"], "groupBy": "project" }
+\`\`\`
+Projects with high-priority open issues and no due dates aren't "on time" — they're untracked. Don't trust overdue numbers in projects with high planning gap.
+
+### Stale Backlog Grooming Target
+**Question:** What needs a decision?
+\`\`\`json
+{ "jql": "status = Backlog AND created <= -90d", "metrics": ["summary"], "groupBy": "project" }
+\`\`\`
+Anything sitting in Backlog 90+ days with no movement is a decision waiting to happen. Pair with \`manage_jira_filter\` execute_jql to get the actual list for a grooming session.
+
+### Unowned + Urgent (Danger Combo)
+**Question:** What's high priority with no owner?
+\`\`\`json
+{ "jql": "resolution = Unresolved AND assignee is EMPTY AND priority in (High, Highest)", "metrics": ["summary"], "groupBy": "project" }
+\`\`\`
+This should always return zero. When it doesn't, it's the most actionable finding in the entire system.
+
+### Blocked Issue Sweep
+**Question:** What's stuck?
+Use \`manage_jira_filter\` with \`execute_jql\` for this one:
+\`\`\`json
+{ "operation": "execute_jql", "jql": "status = Blocked ORDER BY created ASC" }
+\`\`\`
+Blocked lists tend to be small but each one is a potential cascade. Oldest first surfaces the longest-stuck items for escalation.
+
+## Data Cube
+
+For multi-dimensional analysis, use the two-phase cube pattern:
+
+### Phase 1: Discover dimensions
+\`\`\`json
+{ "jql": "project in (...) AND resolution = Unresolved", "metrics": ["cube_setup"] }
+\`\`\`
+Returns available dimensions, their values, cost estimates, and query budget.
+
+### Phase 2: Execute with computed columns
+\`\`\`json
+{ "jql": "project in (...) 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 Reference
+- Arithmetic: \`+\`, \`-\`, \`*\`, \`/\` (division by zero = 0)
+- Comparisons: \`>\`, \`<\`, \`>=\`, \`<=\`, \`==\`, \`!=\` (produce Yes/No — cannot be summed or averaged)
+- Standard columns: total, open, overdue, high, created_7d, resolved_7d
+- Implicit measures (lazily resolved via count API): bugs, unassigned, no_due_date, no_estimate, no_start_date, no_labels, blocked
+- Max 5 expressions per query, 150-query budget per execution
+- Expressions evaluate linearly — later expressions can reference earlier ones
+
+## Gotchas
+
+- **\`groupBy: "assignee"\` on large JQL will error.** Scope to 2-3 projects at a time.
+- **Don't trust overdue in projects with high planning_gap.** If 100% of issues have no due date, overdue = 0 is meaningless, not good news.
+- **Boolean computed columns (Yes/No) can't be summed or averaged.** Don't try to build a ratio on top of one.
+- **\`resolved >= -7d\` is the reliable resolution window.** The Resolved 7d column in summary derives from this same window.
+- **Use \`cube_setup\` first** to discover dimensions, then \`summary\` + \`groupBy\` + \`compute\` to execute.
+`;
+    return {
+        contents: [{
+                uri: 'jira://analysis/recipes',
+                mimeType: 'text/markdown',
+                text: markdown,
+            }],
+    };
+}
 /**
  * Gets all available issue link types
  */

package/build/mcp/markdown-renderer.js

@@ -83,41 +83,33 @@ export function renderIssue(issue, transitions) {
     const lines = [];
     lines.push(`# ${issue.key}: ${issue.summary}`);
     lines.push('');
-    // Core fields
-    lines.push(`**Type:** ${issue.issueType} | **Status:** ${formatStatus(issue.status)}${issue.priority ? ` | **Priority:** ${issue.priority}` : ''}`);
-    if (issue.assignee) {
-        lines.push(`**Assignee:** ${issue.assignee}`);
-    }
-    else {
-        lines.push(`**Assignee:** Unassigned`);
-    }
-    lines.push(`**Reporter:** ${issue.reporter}`);
-    if (issue.parent) {
-        lines.push(`**Parent:** ${issue.parent}`);
-    }
-    if (issue.labels && issue.labels.length > 0) {
-        lines.push(`**Labels:** ${issue.labels.join(', ')}`);
-    }
-    // Dates
+    // Core fields — pipe-delimited
+    const core = [issue.issueType, formatStatus(issue.status)];
+    if (issue.priority)
+        core.push(issue.priority);
+    core.push(issue.assignee || 'Unassigned');
+    lines.push(core.join(' | '));
+    lines.push(`Reporter: ${issue.reporter}`);
+    if (issue.parent)
+        lines.push(`Parent: ${issue.parent}`);
+    if (issue.labels && issue.labels.length > 0)
+        lines.push(`Labels: ${issue.labels.join(', ')}`);
+    // Dates — single line
     const dates = [];
     if (issue.created)
         dates.push(`Created ${formatDate(issue.created)}`);
     if (issue.updated)
         dates.push(`Updated ${formatDate(issue.updated)}`);
-    if (dates.length > 0)
-        lines.push(`**${dates.join(' | ')}**`);
-    const scheduleDates = [];
     if (issue.startDate)
-        scheduleDates.push(`Start: ${formatDate(issue.startDate)}`);
+        dates.push(`Start ${formatDate(issue.startDate)}`);
     if (issue.dueDate)
-        scheduleDates.push(`Due: ${formatDate(issue.dueDate)}`);
+        dates.push(`Due ${formatDate(issue.dueDate)}`);
     if (issue.resolutionDate)
-        scheduleDates.push(`Resolved: ${formatDate(issue.resolutionDate)}`);
-    if (scheduleDates.length > 0)
-        lines.push(`**${scheduleDates.join(' | ')}**`);
-    if (issue.storyPoints) {
-        lines.push(`**Points:** ${issue.storyPoints}`);
-    }
+        dates.push(`Resolved ${formatDate(issue.resolutionDate)}`);
+    if (dates.length > 0)
+        lines.push(dates.join(' | '));
+    if (issue.storyPoints)
+        lines.push(`Points: ${issue.storyPoints}`);
     if (issue.timeEstimate) {
         const hours = Math.floor(issue.timeEstimate / 3600);
         const minutes = Math.floor((issue.timeEstimate % 3600) / 60);
@@ -126,61 +118,58 @@ export function renderIssue(issue, transitions) {
             parts.push(`${hours}h`);
         if (minutes > 0)
             parts.push(`${minutes}m`);
-        lines.push(`**Estimate:** ${parts.length > 0 ? parts.join(' ') : '0m'}`);
+        lines.push(`Estimate: ${parts.length > 0 ? parts.join(' ') : '0m'}`);
     }
-    if (issue.resolution) {
-        lines.push(`**Resolution:** ${issue.resolution}`);
-    }
-    // Description (truncated for token efficiency)
+    if (issue.resolution)
+        lines.push(`Resolution: ${issue.resolution}`);
+    // Description — full for single issue view
     if (issue.description) {
         lines.push('');
-        lines.push('## Description');
-        const desc = stripHtml(issue.description);
-        lines.push(truncate(desc, 300));
+        lines.push('Description:');
+        lines.push(stripHtml(issue.description));
     }
     // Issue links
     if (issue.issueLinks && issue.issueLinks.length > 0) {
         lines.push('');
-        lines.push('## Links');
+        lines.push('Links:');
         for (const link of issue.issueLinks) {
-            if (link.outward) {
-                lines.push(`- ${link.type} -> ${link.outward}`);
-            }
-            if (link.inward) {
-                lines.push(`- ${link.type} <- ${link.inward}`);
-            }
+            if (link.outward)
+                lines.push(`${link.type} -> ${link.outward}`);
+            if (link.inward)
+                lines.push(`${link.type} <- ${link.inward}`);
         }
     }
     // Comments (if present)
     if (issue.comments && issue.comments.length > 0) {
         lines.push('');
-        lines.push(`## Comments (${issue.comments.length})`);
-        // Show last 3 comments
-        const recentComments = issue.comments.slice(-3);
-        for (const comment of recentComments) {
-            lines.push(`- **${comment.author}** (${formatDate(comment.created)}): ${truncate(stripHtml(comment.body), 100)}`);
+        lines.push(`Comments (${issue.comments.length}):`);
+        const recentComments = issue.comments.slice(-5);
+        const startIdx = issue.comments.length - recentComments.length + 1;
+        if (issue.comments.length > 5) {
+            lines.push(`  +${issue.comments.length - 5} older comments`);
         }
-        if (issue.comments.length > 3) {
-            lines.push(`  ... and ${issue.comments.length - 3} more comments`);
+        for (let i = 0; i < recentComments.length; i++) {
+            const comment = recentComments[i];
+            lines.push(`[${startIdx + i}/${issue.comments.length}] ${comment.author} (${formatDate(comment.created)}): ${stripHtml(comment.body)}`);
         }
     }
     // Custom fields (from catalog discovery)
     if (issue.customFieldValues && issue.customFieldValues.length > 0) {
         lines.push('');
-        lines.push('## Custom Fields');
+        lines.push('Custom Fields:');
         for (const cf of issue.customFieldValues) {
             const displayValue = Array.isArray(cf.value)
                 ? cf.value.join(', ')
                 : String(cf.value);
-            lines.push(`- **${cf.name}** (${cf.type}): ${displayValue}`);
+            lines.push(`${cf.name} (${cf.type}): ${displayValue}`);
         }
     }
     // Available transitions
     if (transitions && transitions.length > 0) {
         lines.push('');
-        lines.push('## Available Actions');
+        lines.push('Actions:');
         for (const t of transitions) {
-            lines.push(`- **${t.name}** -> ${t.to.name} (id: ${t.id})`);
+            lines.push(`${t.name} -> ${t.to.name} (id: ${t.id})`);
         }
     }
     return lines.join('\n');
@@ -214,26 +203,18 @@ export function renderIssueSearchResults(issues, pagination, jql) {
     // Issues list
     for (let i = 0; i < issues.length; i++) {
         const issue = issues[i];
-        const num = pagination.startAt + i + 1;
-        lines.push(`## ${num}. ${issue.key}: ${issue.summary}`);
-        const meta = [`${formatStatus(issue.status)}`, issue.assignee || 'Unassigned'];
+        const meta = [issue.key, issue.summary, formatStatus(issue.status), issue.assignee || 'Unassigned'];
         if (issue.priority)
             meta.push(issue.priority);
-        lines.push(meta.join(' | '));
-        const searchDates = [];
         if (issue.dueDate)
-            searchDates.push(`Due: ${formatDate(issue.dueDate)}`);
-        if (issue.startDate)
-            searchDates.push(`Start: ${formatDate(issue.startDate)}`);
-        if (searchDates.length > 0)
-            lines.push(searchDates.join(' | '));
+            meta.push(`due ${formatDate(issue.dueDate)}`);
+        lines.push(meta.join(' | '));
         if (issue.description) {
             const desc = stripHtml(issue.description);
             if (desc.length > 0) {
-                lines.push(`> ${truncate(desc, 120)}`);
+                lines.push(`  ${truncate(desc, 120)}`);
             }
         }
-        lines.push('');
     }
     // Pagination guidance
     lines.push('---');
@@ -297,19 +278,16 @@ export function renderProjectList(projects) {
     lines.push(`# Projects (${projects.length})`);
     lines.push('');
     for (const project of projects) {
-        lines.push(`## ${project.key}: ${project.name}`);
-        if (project.lead) {
-            lines.push(`Lead: ${project.lead}`);
-        }
-        if (project.description) {
-            lines.push(`> ${truncate(stripHtml(project.description), 100)}`);
-        }
+        const parts = [project.key, project.name];
+        if (project.lead)
+            parts.push(project.lead);
         if (project.statusCounts) {
             const total = Object.values(project.statusCounts).reduce((a, b) => a + b, 0);
-            lines.push(`Issues: ${total}`);
+            parts.push(`${total} issues`);
         }
-        lines.push('');
+        lines.push(parts.join(' | '));
     }
+    lines.push('');
     lines.push('---');
     lines.push(`Tip: Use manage_jira_project with operation="get" and projectKey="KEY" for details`);
     return lines.join('\n');
@@ -348,9 +326,9 @@ export function renderBoardList(boards) {
         byType[type].push(board);
     }
     for (const [type, typeBoards] of Object.entries(byType)) {
-        lines.push(`## ${type.charAt(0).toUpperCase() + type.slice(1)} Boards`);
+        lines.push(`${type.charAt(0).toUpperCase() + type.slice(1)} Boards:`);
         for (const board of typeBoards) {
-            lines.push(`- **${board.name}** (id: ${board.id})${board.projectKey ? ` - ${board.projectKey}` : ''}`);
+            lines.push(`${board.name} | id: ${board.id}${board.projectKey ? ` | ${board.projectKey}` : ''}`);
         }
         lines.push('');
     }
@@ -378,7 +356,7 @@ export function renderSprint(sprint) {
     }
     if (sprint.issues && sprint.issues.length > 0) {
         lines.push('');
-        lines.push(`## Issues (${sprint.issues.length})`);
+        lines.push(`Issues (${sprint.issues.length}):`);
         // Group by status
         const byStatus = {};
         for (const issue of sprint.issues) {
@@ -388,9 +366,9 @@ export function renderSprint(sprint) {
             byStatus[status].push(issue);
         }
         for (const [status, statusIssues] of Object.entries(byStatus)) {
-            lines.push(`### ${status} (${statusIssues.length})`);
+            lines.push(`${status} (${statusIssues.length}):`);
             for (const issue of statusIssues) {
-                lines.push(`- ${issue.key}: ${issue.summary}${issue.assignee ? ` [${issue.assignee}]` : ''}`);
+                lines.push(`${issue.key} | ${issue.summary}${issue.assignee ? ` | ${issue.assignee}` : ''}`);
             }
         }
     }
@@ -431,16 +409,16 @@ export function renderFilterList(filters) {
     const favorites = filters.filter(f => f.favourite);
     const others = filters.filter(f => !f.favourite);
     if (favorites.length > 0) {
-        lines.push('## Favorites');
+        lines.push('Favorites:');
         for (const filter of favorites) {
-            lines.push(`- **${filter.name}** (id: ${filter.id}) - ${filter.owner}`);
+            lines.push(`${filter.name} | id: ${filter.id} | ${filter.owner}`);
         }
         lines.push('');
     }
     if (others.length > 0) {
-        lines.push('## Other Filters');
+        lines.push('Other Filters:');
         for (const filter of others) {
-            lines.push(`- ${filter.name} (id: ${filter.id}) - ${filter.owner}`);
+            lines.push(`${filter.name} | id: ${filter.id} | ${filter.owner}`);
         }
     }
     return lines.join('\n');

package/build/schemas/tool-schemas.js

@@ -326,7 +326,7 @@ export const toolSchemas = {
     },
     analyze_jira_issues: {
         name: 'analyze_jira_issues',
-        description: 'Compute project metrics over issues selected by JQL. Use "summary" for exact counts across projects (no sampling cap). Use other metrics for detailed analysis of individual issue data. Always prefer this tool over manage_jira_filter or manage_jira_project for quantitative questions (counts, totals, overdue, workload).',
+        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: {
@@ -338,15 +338,21 @@ export const toolSchemas = {
                     type: 'array',
                     items: {
                         type: 'string',
-                        enum: ['summary', 'points', 'time', 'schedule', 'cycle', 'distribution'],
+                        enum: ['summary', 'points', 'time', 'schedule', 'cycle', 'distribution', 'cube_setup'],
                     },
-                    description: 'Which metric groups to compute. summary = exact issue counts via count API (no cap, fastest). 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.',
+                    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, no_estimate, no_start_date, no_labels, blocked. Max 5 expressions. Example: ["bug_pct = bugs / total * 100", "planning_gap = no_estimate / open * 100"].',
+                    maxItems: 5,
+                },
                 maxResults: {
                     type: 'integer',
                     description: 'Max issues to fetch for detail metrics (default 100, max 500). Does not apply to summary (which uses count API).',

package/build/utils/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.1",
+  "version": "0.5.3",
   "mcpName": "io.github.aaronsb/jira-cloud",
   "description": "Model Context Protocol (MCP) server for Jira Cloud - enables AI assistants to interact with Jira",
   "type": "module",