@aaronsb/jira-cloud-mcp 0.5.2 → 0.5.4

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,
@@ -80,6 +84,7 @@ export class JiraClient {
             'created',
             'updated',
             'resolutiondate',
+            'statuscategorychangedate',
             'duedate',
             this.customFields.startDate,
             this.customFields.storyPoints,
@@ -106,6 +111,7 @@ export class JiraClient {
             created: fields?.created || '',
             updated: fields?.updated || '',
             resolutionDate: fields?.resolutiondate || null,
+            statusCategoryChanged: fields?.statuscategorychangedate ?? fields?.statuscategorychangeddate ?? null,
             dueDate: fields?.duedate || null,
             startDate: fields?.[this.customFields.startDate] || null,
             storyPoints: fields?.[this.customFields.storyPoints] ?? null,
@@ -427,7 +433,7 @@ export class JiraClient {
             const leanFields = [
                 'summary', 'issuetype', 'priority', 'assignee', 'reporter',
                 'status', 'resolution', 'labels', 'created', 'updated',
-                'resolutiondate', 'duedate', 'timeestimate',
+                'resolutiondate', 'statuscategorychangedate', 'duedate', 'timeestimate',
                 this.customFields.startDate, this.customFields.storyPoints,
             ];
             const params = {

package/build/docs/tool-documentation.js

@@ -483,7 +483,7 @@ function generateAnalysisToolDocumentation(schema) {
             },
             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.",
+                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, stale, stale_status, backlog_rot.",
             },
             maxResults: {
                 type: "integer",

package/build/handlers/analysis-handler.js

@@ -210,6 +210,48 @@ export function renderCycle(issues, now) {
             .slice(0, 5);
         const oldestStr = oldest.map(o => `${o.key} (${o.age}d)`).join(', ');
         lines.push(`**Oldest open:** ${oldestStr}`);
+        // Staleness — how long since last update
+        const staleness = open.map(i => ({
+            key: i.key,
+            days: daysBetween(parseDate(i.updated), now),
+        }));
+        const buckets = { fresh: 0, aging: 0, stale: 0, abandoned: 0 };
+        for (const s of staleness) {
+            if (s.days < 7)
+                buckets.fresh++;
+            else if (s.days < 30)
+                buckets.aging++;
+            else if (s.days < 90)
+                buckets.stale++;
+            else
+                buckets.abandoned++;
+        }
+        lines.push(`**Staleness:** <7d: ${buckets.fresh} | 7-30d: ${buckets.aging} | 30-90d: ${buckets.stale} | 90d+: ${buckets.abandoned}`);
+        // Most stale open issues
+        const mostStale = staleness
+            .sort((a, b) => b.days - a.days)
+            .slice(0, 5);
+        if (mostStale.length > 0 && mostStale[0].days >= 30) {
+            const staleStr = mostStale.map(s => `${s.key} (${s.days}d)`).join(', ');
+            lines.push(`**Most stale:** ${staleStr}`);
+        }
+        // Status age — how long in current status
+        const withStatusAge = open.filter(i => i.statusCategoryChanged);
+        if (withStatusAge.length > 0) {
+            const statusAges = withStatusAge.map(i => daysBetween(parseDate(i.statusCategoryChanged), now));
+            const med = median(statusAges);
+            const avg = mean(statusAges);
+            lines.push(`**Status age:** median ${med.toFixed(1)} days, mean ${avg.toFixed(1)} days in current status (${withStatusAge.length} issues)`);
+            const stuck = withStatusAge
+                .map(i => ({ key: i.key, status: i.status, days: daysBetween(parseDate(i.statusCategoryChanged), now) }))
+                .filter(s => s.days >= 30)
+                .sort((a, b) => b.days - a.days)
+                .slice(0, 5);
+            if (stuck.length > 0) {
+                const stuckStr = stuck.map(s => `${s.key} ${s.status} (${s.days}d)`).join(', ');
+                lines.push(`**Stuck:** ${stuckStr}`);
+            }
+        }
     }
     return lines.join('\n');
 }
@@ -248,17 +290,39 @@ 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}`;
 }
-/** 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',
-};
+/** 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',
+        stale: 'resolution = Unresolved AND updated <= -60d',
+        stale_status: 'resolution = Unresolved AND statusCategoryChangedDate <= -30d',
+        backlog_rot: 'resolution = Unresolved AND dueDate is EMPTY AND assignee is EMPTY AND updated <= -60d',
+    };
+    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) {
@@ -272,7 +336,7 @@ export function groupByJqlClause(dimension, values) {
             return values.map(v => `issuetype = "${v}"`);
     }
 }
-async function buildCountRow(jiraClient, label, baseJql, implicitMeasureNames) {
+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')),
@@ -282,8 +346,8 @@ async function buildCountRow(jiraClient, label, baseJql, implicitMeasureNames) {
         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]))));
+    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];
@@ -348,8 +412,9 @@ 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) : [];
+    // 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') {
         let keys = extractProjectKeys(jql);
@@ -360,7 +425,7 @@ async function handleSummary(jiraClient, jql, groupBy, compute) {
         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)));
+        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, compute));
@@ -382,7 +447,7 @@ async function handleSummary(jiraClient, jql, groupBy, compute) {
         // 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)));
+        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(renderSummaryTable(rows, compute));
@@ -395,16 +460,16 @@ async function handleSummary(jiraClient, jql, groupBy, compute) {
     }
     else {
         // No groupBy — single row for the whole JQL
-        const row = await buildCountRow(jiraClient, 'All', jql, neededImplicits);
+        const row = await buildCountRow(jiraClient, 'All', jql, neededImplicits, implicitDefs);
         lines.push('');
         lines.push(renderSummaryTable([row], compute));
     }
     return lines.join('\n');
 }
 /** Detect which implicit measures are referenced by compute expressions */
-function detectImplicitMeasures(compute) {
+function detectImplicitMeasures(compute, implicitMeasureDefs) {
     const refs = extractColumnRefs(compute);
-    return Object.keys(IMPLICIT_MEASURES).filter(name => refs.has(name));
+    return Object.keys(implicitMeasureDefs).filter(name => refs.has(name));
 }
 /** Extract distinct dimension values from sampled issues */
 export function extractDimensions(issues) {
@@ -451,7 +516,7 @@ export function renderCubeSetup(jql, sampleSize, dimensions) {
     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');
+    lines.push('- bugs, unassigned, no_due_date, no_estimate, no_start_date, no_labels, blocked, stale, stale_status, backlog_rot');
     // Suggested cubes with cost estimates
     lines.push('');
     lines.push(`## Suggested Cubes (budget: ${MAX_COUNT_QUERIES} queries)`);
@@ -619,7 +684,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
         }
     }
     // Next steps
-    const nextSteps = analysisNextSteps(jql, allIssues.slice(0, 3).map(i => i.key));
+    const nextSteps = analysisNextSteps(jql, allIssues.slice(0, 3).map(i => i.key), truncated);
     lines.push(nextSteps);
     return {
         content: [{

package/build/handlers/resource-handlers.js

@@ -371,103 +371,102 @@ async function getContextCustomFields(jiraClient, projectKey, issueType) {
 function getAnalysisRecipes() {
     const markdown = `# Analysis Query Recipes
 
-## Two Layers
+## Foundation Rules
 
-Stack these for magnitude + detail:
+- **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.
 
-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
+## Core Recipes
 
-## Recipes
-
-### Project Health Snapshot
+### Org-wide 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" }
+{ "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?
-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" }
+{ "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.
 
-### Overdue Breakdown
-**Question:** Where are we most behind?
+### Team Workload Scorecard
+**Question:** Who is overloaded or under-tracked?
 \`\`\`json
-{ "jql": "resolution = Unresolved AND dueDate < now()", "metrics": ["summary"], "groupBy": "project" }
+{ "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.
 
-### Deadline Pressure Window
-**Question:** What's due in the next 2 weeks?
+### Planning Gap Detector
+**Question:** Where is risk invisible?
 \`\`\`json
-{ "jql": "resolution = Unresolved AND dueDate >= now() AND dueDate <= 14d", "metrics": ["summary"], "groupBy": "project" }
+{ "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
-**Question:** How much backlog needs grooming?
+### 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.
 
-### Ownership Gaps
-**Question:** What has no owner?
+### Unowned + Urgent (Danger Combo)
+**Question:** What's high priority with no owner?
 \`\`\`json
-{ "jql": "resolution = Unresolved AND assignee is EMPTY", "metrics": ["summary"], "groupBy": "project" }
+{ "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.
 
-### Planning Coverage
-**Question:** How much work has no due date?
+### Blocked Issue Sweep
+**Question:** What's stuck?
+Use \`manage_jira_filter\` with \`execute_jql\` for this one:
 \`\`\`json
-{ "jql": "resolution = Unresolved AND dueDate is EMPTY", "metrics": ["summary"], "groupBy": "project" }
+{ "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 (Advanced)
+### Data Quality / Backlog Rot
+**Question:** How much of this backlog is noise?
+\`\`\`json
+{ "jql": "project in (...) AND resolution = Unresolved", "metrics": ["summary"], "groupBy": "project", "compute": ["stale_pct = stale / open * 100", "rot_pct = backlog_rot / open * 100"] }
+\`\`\`
+\`stale\` = untouched 60+ days. \`backlog_rot\` = undated + unassigned + untouched 60+ days. High rot_pct means overdue counts are misleading — the backlog is full of phantom work.
+
+## Data Cube
 
 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"] }
+{ "jql": "project in (...) AND resolution = Unresolved", "metrics": ["cube_setup"] }
 \`\`\`
-Returns available dimensions, their values, and cost estimates for each groupBy option.
+Returns available dimensions, their values, cost estimates, and query budget.
 
 ### 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"] }
+{ "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
-- Arithmetic: \`+\`, \`-\`, \`*\`, \`/\`
-- Comparisons: \`>\`, \`<\`, \`>=\`, \`<=\`, \`==\`, \`!=\` (produce Yes/No)
+### 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): 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
+- Implicit measures (lazily resolved via count API): bugs, unassigned, no_due_date, no_estimate, no_start_date, no_labels, blocked, stale (untouched 60d+), stale_status (stuck in status 30d+), backlog_rot (undated+unassigned+untouched 60d+)
+- Max 5 expressions per query, 150-query budget per execution
+- Expressions evaluate linearly — later expressions can reference earlier ones
 
-## Key Patterns
+## Gotchas
 
-- \`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
+- **\`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: [{

package/build/index.js

@@ -2,7 +2,7 @@
 import { createRequire } from 'module';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { fieldDiscovery } from './client/field-discovery.js';
 import { JiraClient } from './client/jira-client.js';
 import { handleAnalysisRequest } from './handlers/analysis-handler.js';
@@ -13,6 +13,8 @@ import { handleProjectRequest } from './handlers/project-handlers.js';
 import { createQueueHandler } from './handlers/queue-handler.js';
 import { setupResourceHandlers } from './handlers/resource-handlers.js';
 import { handleSprintRequest } from './handlers/sprint-handlers.js';
+import { promptDefinitions } from './prompts/prompt-definitions.js';
+import { getPrompt } from './prompts/prompt-messages.js';
 import { toolSchemas } from './schemas/tool-schemas.js';
 // Jira credentials from environment variables
 const JIRA_EMAIL = process.env.JIRA_EMAIL;
@@ -43,6 +45,7 @@ class JiraServer {
             capabilities: {
                 tools: {},
                 resources: {},
+                prompts: {},
             },
         });
         this.jiraClient = new JiraClient({
@@ -80,6 +83,18 @@ class JiraServer {
         this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             return resourceHandlers.readResource(request.params.uri);
         });
+        // Set up prompt handlers
+        this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+            prompts: promptDefinitions.map(p => ({
+                name: p.name,
+                description: p.description,
+                arguments: p.arguments,
+            })),
+        }));
+        this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            return getPrompt(name, args);
+        });
         // Set up tool handlers
         this.server.setRequestHandler(CallToolRequestSchema, async (request, _extra) => {
             console.error('Received request:', JSON.stringify(request, null, 2));

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/prompts/prompt-definitions.js

@@ -0,0 +1,34 @@
+/**
+ * MCP Prompt definitions for Jira analysis workflows.
+ * Prompts are user-controlled templates surfaced by clients as slash commands or menu items.
+ */
+export const promptDefinitions = [
+    {
+        name: 'backlog_health',
+        description: 'Run a data quality health check on a project backlog — surfaces rot, staleness, and planning gaps',
+        arguments: [
+            { name: 'project', description: 'Jira project key (e.g. PROJ, ENG)', required: true },
+        ],
+    },
+    {
+        name: 'contributor_workload',
+        description: 'Per-contributor workload breakdown with staleness and risk — scopes detail queries to fit within sample cap',
+        arguments: [
+            { name: 'project', description: 'Jira project key (e.g. PROJ, ENG)', required: true },
+        ],
+    },
+    {
+        name: 'sprint_review',
+        description: 'Sprint review preparation — velocity, scope changes, at-risk items, and completion forecast',
+        arguments: [
+            { name: 'board_id', description: 'Jira board ID (find via manage_jira_board list)', required: true },
+        ],
+    },
+    {
+        name: 'narrow_analysis',
+        description: 'Refine a capped analysis query — guides you to narrow JQL for precise detail metrics',
+        arguments: [
+            { name: 'jql', description: 'The JQL query to refine (from a previous capped analysis)', required: true },
+        ],
+    },
+];

package/build/prompts/prompt-messages.js

@@ -0,0 +1,111 @@
+/**
+ * Builds PromptMessage arrays for each prompt, substituting user-provided arguments.
+ */
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { promptDefinitions } from './prompt-definitions.js';
+function msg(text) {
+    return { role: 'user', content: { type: 'text', text } };
+}
+const builders = {
+    backlog_health({ project }) {
+        return {
+            description: `Backlog health check for ${project}`,
+            messages: [msg(`Analyze backlog health for project ${project}. Use the analyze_jira_issues and manage_jira_filter tools.
+
+Step 1 — Summary with data quality signals:
+{"jql":"project = ${project} AND resolution = Unresolved","metrics":["summary"],"groupBy":"priority","compute":["rot_pct = backlog_rot / open * 100","stale_pct = stale / open * 100","gap_pct = no_estimate / open * 100"]}
+
+Step 2 — Cycle metrics for staleness distribution and status age:
+{"jql":"project = ${project} AND resolution = Unresolved","metrics":["cycle"],"maxResults":100}
+
+Step 3 — Summarize findings:
+- What percentage of the backlog is rotting (no owner, no dates, untouched)?
+- What's stuck in the same status for 30+ days?
+- What's missing estimates or start dates?
+- Flag the worst offenders by issue key.
+- Recommend specific triage actions.`)],
+        };
+    },
+    contributor_workload({ project }) {
+        return {
+            description: `Contributor workload for ${project}`,
+            messages: [msg(`Analyze contributor workload for project ${project}. Use the analyze_jira_issues tool.
+
+Step 1 — Assignee distribution with quality signals:
+{"jql":"project = ${project} AND resolution = Unresolved","metrics":["summary"],"groupBy":"assignee","compute":["stale_pct = stale / open * 100","blocked_pct = blocked / open * 100"]}
+
+Step 2 — For the top 3 assignees by open issue count, run scoped detail metrics:
+{"jql":"project = ${project} AND resolution = Unresolved AND assignee = '{name}'","metrics":["cycle","schedule"]}
+
+This pattern keeps each detail query within the sample cap for precise results.
+
+Step 3 — Summarize:
+- Who has the most open work?
+- Who has the most stale or at-risk issues?
+- Are there load imbalances?
+- What needs reassignment or triage?`)],
+        };
+    },
+    sprint_review({ board_id }) {
+        return {
+            description: `Sprint review prep for board ${board_id}`,
+            messages: [msg(`Prepare a sprint review for board ${board_id}. Use manage_jira_sprint and analyze_jira_issues tools.
+
+Step 1 — Find the active sprint:
+{"operation":"list","boardId":${board_id},"state":"active"}
+
+Step 2 — Analyze sprint issues (use the sprint ID from step 1):
+{"jql":"sprint = {sprintId}","metrics":["summary","points","schedule"],"compute":["done_pct = resolved_7d / total * 100"]}
+
+Step 3 — Summarize:
+- Current velocity vs planned
+- Scope changes (items added/removed mid-sprint)
+- At-risk items (overdue, blocked, stale)
+- Completion forecast — will the sprint goal be met?`)],
+        };
+    },
+    narrow_analysis({ jql }) {
+        return {
+            description: 'Refine a capped analysis query',
+            messages: [msg(`The previous analysis was sampled — detail metrics didn't cover all matching issues.
+
+Original query: ${jql}
+
+To get precise results, help me narrow the query. Here are useful approaches:
+
+By assignee (each person's list usually fits within the cap):
+{"jql":"${jql} AND assignee = currentUser()","metrics":["cycle","schedule"]}
+
+By priority (focus on what matters):
+{"jql":"${jql} AND priority in (High, Highest)","metrics":["cycle","schedule"]}
+
+By issue type:
+{"jql":"${jql} AND issuetype = Bug","metrics":["cycle"]}
+
+By recency:
+{"jql":"${jql} AND created >= -30d","metrics":["cycle"]}
+
+Or use summary metrics for the full population (count API, no cap):
+{"jql":"${jql}","metrics":["summary"],"groupBy":"assignee","compute":["stale_pct = stale / open * 100"]}
+
+Ask me which dimension I'd like to drill into, or suggest the most useful one based on the original query.`)],
+        };
+    },
+};
+export function getPrompt(name, args) {
+    const def = promptDefinitions.find(p => p.name === name);
+    if (!def) {
+        throw new McpError(ErrorCode.InvalidParams, `Unknown prompt: ${name}`);
+    }
+    const resolvedArgs = args ?? {};
+    for (const arg of def.arguments) {
+        if (arg.required && !resolvedArgs[arg.name]) {
+            throw new McpError(ErrorCode.InvalidParams, `Missing required argument: ${arg.name}`);
+        }
+    }
+    const builder = builders[name];
+    if (!builder) {
+        throw new Error(`No message builder for prompt: ${name}`);
+    }
+    return builder(resolvedArgs);
+}

package/build/schemas/tool-schemas.js

@@ -350,7 +350,7 @@ export const toolSchemas = {
                 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"].',
+                    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, stale (untouched 60d+), stale_status (stuck in status 30d+), backlog_rot (undated+unassigned+untouched 60d+). Max 5 expressions. Example: ["bug_pct = bugs / total * 100", "rot_pct = backlog_rot / open * 100"].',
                     maxItems: 5,
                 },
                 maxResults: {

package/build/utils/next-steps.js

@@ -125,11 +125,14 @@ export function boardNextSteps(operation, boardId) {
     }
     return steps.length > 0 ? formatSteps(steps) : '';
 }
-export function analysisNextSteps(jql, issueKeys) {
+export function analysisNextSteps(jql, issueKeys, truncated = false) {
     const steps = [];
     if (issueKeys.length > 0) {
         steps.push({ description: 'Get details on a specific issue', tool: 'manage_jira_issue', example: { operation: 'get', issueKey: issueKeys[0] } });
     }
     steps.push({ description: '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 } });
+    if (truncated) {
+        steps.push({ description: 'Detail metrics are sampled — narrow JQL by assignee, priority, or type for precise results. Use summary metrics (count API) for whole-project totals', tool: 'analyze_jira_issues', example: { jql: `${jql} AND assignee = currentUser()`, metrics: ['cycle'] } });
+    }
     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.2",
+  "version": "0.5.4",
   "mcpName": "io.github.aaronsb/jira-cloud",
   "description": "Model Context Protocol (MCP) server for Jira Cloud - enables AI assistants to interact with Jira",
   "type": "module",