@aaronsb/jira-cloud-mcp 0.5.2 → 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

@@ -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.",
             },
             maxResults: {
                 type: "integer",

package/build/handlers/analysis-handler.js

@@ -248,17 +248,36 @@ 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',
+    };
+    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 +291,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 +301,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 +367,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 +380,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 +402,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 +415,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 +471,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');
     // Suggested cubes with cost estimates
     lines.push('');
     lines.push(`## Suggested Cubes (budget: ${MAX_COUNT_QUERIES} queries)`);

package/build/handlers/resource-handlers.js

@@ -371,103 +371,95 @@ 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 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
+- 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/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

@@ -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. Max 5 expressions. Example: ["bug_pct = bugs / total * 100", "planning_gap = no_estimate / open * 100"].',
                     maxItems: 5,
                 },
                 maxResults: {

package/package.json

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