@aaronsb/jira-cloud-mcp 0.5.3 → 0.5.5

package/build/client/jira-client.js

@@ -84,6 +84,7 @@ export class JiraClient {
             'created',
             'updated',
             'resolutiondate',
+            'statuscategorychangedate',
             'duedate',
             this.customFields.startDate,
             this.customFields.storyPoints,
@@ -94,10 +95,20 @@ export class JiraClient {
     /** Maps a raw Jira API issue to our JiraIssueDetails shape */
     mapIssueFields(issue) {
         const fields = issue.fields ?? issue.fields;
+        // Extract people with accountIds for @mention support
+        const people = [];
+        if (fields?.assignee?.accountId && fields?.assignee?.displayName) {
+            people.push({ displayName: fields.assignee.displayName, accountId: fields.assignee.accountId, role: 'assignee' });
+        }
+        if (fields?.reporter?.accountId && fields?.reporter?.displayName) {
+            people.push({ displayName: fields.reporter.displayName, accountId: fields.reporter.accountId, role: 'reporter' });
+        }
         return {
             key: issue.key,
             summary: fields?.summary,
-            description: issue.renderedFields?.description || '',
+            description: fields?.description
+                ? TextProcessor.adfToMarkdown(fields.description)
+                : '',
             issueType: fields?.issuetype?.name || '',
             priority: fields?.priority?.name || null,
             parent: fields?.parent?.key || null,
@@ -110,6 +121,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,
@@ -119,6 +131,7 @@ export class JiraClient {
                 outward: link.outwardIssue?.key || null,
                 inward: link.inwardIssue?.key || null,
             })),
+            people: people.length > 0 ? people : undefined,
         };
     }
     async getIssue(issueKey, includeComments = false, includeAttachments = false, customFieldMeta) {
@@ -137,7 +150,7 @@ export class JiraClient {
         const params = {
             issueIdOrKey: issueKey,
             fields,
-            expand: includeComments ? 'renderedFields,comments' : 'renderedFields'
+            expand: includeComments ? 'comments' : undefined
         };
         const issue = await this.client.issues.getIssue(params);
         const issueDetails = this.mapIssueFields(issue);
@@ -169,9 +182,24 @@ export class JiraClient {
                 .map(comment => ({
                 id: comment.id,
                 author: comment.author.displayName,
-                body: comment.body?.content ? TextProcessor.extractTextFromAdf(comment.body) : String(comment.body),
+                body: comment.body?.content ? TextProcessor.adfToMarkdown(comment.body) : String(comment.body),
                 created: comment.created,
             }));
+            // Add comment authors to people list (deduplicated, capped at 10 total)
+            const existingIds = new Set((issueDetails.people || []).map(p => p.accountId));
+            const commentAuthors = [];
+            for (const comment of issue.fields.comment.comments) {
+                const aid = comment.author?.accountId;
+                const name = comment.author?.displayName;
+                if (aid && name && !existingIds.has(aid)) {
+                    existingIds.add(aid);
+                    commentAuthors.push({ displayName: name, accountId: aid, role: 'commenter' });
+                }
+            }
+            if (commentAuthors.length > 0) {
+                const people = [...(issueDetails.people || []), ...commentAuthors];
+                issueDetails.people = people.slice(0, 10);
+            }
         }
         if (includeAttachments && issue.fields.attachment) {
             issueDetails.attachments = issue.fields.attachment
@@ -373,7 +401,6 @@ export class JiraClient {
         const searchResults = await this.client.issueSearch.searchForIssuesUsingJql({
             jql: filter.jql,
             fields: this.issueFields,
-            expand: 'renderedFields'
         });
         return (searchResults.issues || []).map(issue => this.mapIssueFields(issue));
     }
@@ -431,7 +458,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 = {
@@ -475,7 +502,6 @@ export class JiraClient {
                 jql: cleanJql,
                 maxResults: Math.min(maxResults, 100),
                 fields: this.issueFields,
-                expand: 'renderedFields',
             });
             const issues = (searchResults.issues || []).map(issue => this.mapIssueFields(issue));
             // Note: Enhanced search API uses token-based pagination, not offset-based
@@ -576,7 +602,7 @@ export class JiraClient {
     async getPopulatedFields(issueKey) {
         const issue = await this.client.issues.getIssue({
             issueIdOrKey: issueKey,
-            expand: 'renderedFields,names',
+            expand: 'names',
         });
         const fieldNames = issue.names || {};
         const fields = issue.fields;

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, no_estimate, no_start_date, no_labels, 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');
 }
@@ -271,6 +313,9 @@ function buildImplicitMeasures(customFieldIds) {
         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`;
@@ -471,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, no_estimate, no_start_date, no_labels, 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)`);
@@ -639,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

@@ -430,6 +430,13 @@ Use \`manage_jira_filter\` with \`execute_jql\` for this one:
 \`\`\`
 Blocked lists tend to be small but each one is a potential cascade. Oldest first surfaces the longest-stuck items for escalation.
 
+### 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:
@@ -449,7 +456,7 @@ Returns available dimensions, their values, cost estimates, and query budget.
 - 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
+- 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
 

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

@@ -122,11 +122,11 @@ export function renderIssue(issue, transitions) {
     }
     if (issue.resolution)
         lines.push(`Resolution: ${issue.resolution}`);
-    // Description — full for single issue view
+    // Description — already markdown from ADF conversion
     if (issue.description) {
         lines.push('');
         lines.push('Description:');
-        lines.push(stripHtml(issue.description));
+        lines.push(issue.description);
     }
     // Issue links
     if (issue.issueLinks && issue.issueLinks.length > 0) {
@@ -150,7 +150,8 @@ export function renderIssue(issue, transitions) {
         }
         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)}`);
+            const preview = comment.body.split('\n').filter((l) => l.trim()).slice(0, 2).join(' | ');
+            lines.push(`[${startIdx + i}/${issue.comments.length}] ${comment.author} (${formatDate(comment.created)}): ${truncate(preview, 200)}`);
         }
     }
     // Custom fields (from catalog discovery)
@@ -172,6 +173,18 @@ export function renderIssue(issue, transitions) {
             lines.push(`${t.name} -> ${t.to.name} (id: ${t.id})`);
         }
     }
+    // People — accountIds for @mentions and assignee operations
+    if (issue.people && issue.people.length > 0) {
+        lines.push('');
+        lines.push('People:');
+        for (const person of issue.people) {
+            lines.push(`${person.displayName} | ${person.role} | accountId: ${person.accountId}`);
+        }
+        lines.push('Use accountId to assign issues or @mention in comments');
+    }
+    // Formatting hint — remind the agent that descriptions/comments accept markdown
+    lines.push('');
+    lines.push('Formatting: write markdown for descriptions and comments (headings, **bold**, *italic*, ~~strikethrough~~, `code`, lists)');
     return lines.join('\n');
 }
 /**
@@ -210,7 +223,7 @@ export function renderIssueSearchResults(issues, pagination, jql) {
             meta.push(`due ${formatDate(issue.dueDate)}`);
         lines.push(meta.join(' | '));
         if (issue.description) {
-            const desc = stripHtml(issue.description);
+            const desc = issue.description.split('\n').filter((l) => l.trim()).slice(0, 2).join(' | ');
             if (desc.length > 0) {
                 lines.push(`  ${truncate(desc, 120)}`);
             }

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, no_estimate, no_start_date, no_labels, blocked. Max 5 expressions. Example: ["bug_pct = bugs / total * 100", "planning_gap = no_estimate / open * 100"].',
+                    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/build/utils/text-processing.js

@@ -1,6 +1,46 @@
 import MarkdownIt from 'markdown-it';
+// Jira accountIds: hex strings or "712020:uuid-format"
+const MENTION_RE = /@([a-zA-Z0-9][a-zA-Z0-9:_-]{9,})/g;
 export class TextProcessor {
-    static md = new MarkdownIt();
+    static md = new MarkdownIt().enable('strikethrough');
+    /**
+     * Split text into alternating text and mention ADF nodes.
+     * Recognizes @accountId patterns and converts them to ADF mention nodes.
+     */
+    static splitMentions(text, marks) {
+        const nodes = [];
+        let lastIndex = 0;
+        MENTION_RE.lastIndex = 0;
+        let match;
+        while ((match = MENTION_RE.exec(text)) !== null) {
+            // Text before the mention
+            if (match.index > lastIndex) {
+                const before = text.slice(lastIndex, match.index);
+                const node = { type: 'text', text: before };
+                if (marks?.length)
+                    node.marks = marks;
+                nodes.push(node);
+            }
+            // Mention node
+            nodes.push({
+                type: 'mention',
+                attrs: { id: match[1], text: `@${match[1]}` },
+            });
+            lastIndex = MENTION_RE.lastIndex;
+        }
+        // Remaining text after last mention
+        if (lastIndex < text.length) {
+            const remaining = text.slice(lastIndex);
+            const node = { type: 'text', text: remaining };
+            if (marks?.length)
+                node.marks = marks;
+            nodes.push(node);
+        }
+        // No mentions found — return empty so caller uses original logic
+        if (nodes.length === 0)
+            return [];
+        return nodes;
+    }
     static markdownToAdf(markdown) {
         // Replace literal \n sequences with actual newlines so markdown-it
         // correctly splits paragraphs. MCP JSON transport may deliver these
@@ -73,6 +113,24 @@ export class TextProcessor {
                     for (let i = 0; i < token.children.length; i++) {
                         const child = token.children[i];
                         if (child.type === 'text') {
+                            // Check for @accountId mentions in this text segment
+                            const mentionNodes = TextProcessor.splitMentions(child.content, marks.length > 0 ? marks : undefined);
+                            if (mentionNodes.length > 0) {
+                                // Flush any pending plain text first
+                                if (currentText) {
+                                    lastBlock.content.push({
+                                        type: 'text',
+                                        text: currentText,
+                                        ...(marks.length > 0 && { marks })
+                                    });
+                                    currentText = '';
+                                }
+                                lastBlock.content.push(...mentionNodes);
+                                // Reset marks after flushing mention-bearing text
+                                if (marks.length > 0)
+                                    marks = [];
+                                continue;
+                            }
                             if (currentText && marks.length > 0) {
                                 lastBlock.content.push({
                                     type: 'text',
@@ -104,6 +162,16 @@ export class TextProcessor {
                             }
                             marks.push({ type: 'em' });
                         }
+                        else if (child.type === 's_open') {
+                            if (currentText) {
+                                lastBlock.content.push({
+                                    type: 'text',
+                                    text: currentText
+                                });
+                                currentText = '';
+                            }
+                            marks.push({ type: 'strike' });
+                        }
                         else if (child.type === 'link_open') {
                             if (currentText) {
                                 lastBlock.content.push({
@@ -183,6 +251,134 @@ export class TextProcessor {
         }
         return '';
     }
+    /**
+     * Convert ADF to markdown, preserving formatting for round-trip fidelity.
+     * This is the inverse of markdownToAdf — the agent reads markdown and
+     * writes markdown, so the formatting survives the Jira round-trip.
+     */
+    static adfToMarkdown(node) {
+        if (!node)
+            return '';
+        switch (node.type) {
+            case 'doc':
+                return (node.content || [])
+                    .map((child) => TextProcessor.adfToMarkdown(child))
+                    .join('\n\n')
+                    .replace(/\n{3,}/g, '\n\n')
+                    .trim();
+            case 'paragraph':
+                return (node.content || [])
+                    .map((child) => TextProcessor.adfToMarkdown(child))
+                    .join('');
+            case 'heading': {
+                const level = node.attrs?.level || 1;
+                const prefix = '#'.repeat(level);
+                const text = (node.content || [])
+                    .map((child) => TextProcessor.adfToMarkdown(child))
+                    .join('');
+                return `${prefix} ${text}`;
+            }
+            case 'text': {
+                let text = node.text || '';
+                if (node.marks) {
+                    // Apply inline marks first (bold, italic, etc.), then link outermost
+                    // so we get **[text](url)** not [**text**](url)
+                    const inlineMarks = node.marks.filter((m) => m.type !== 'link');
+                    const linkMark = node.marks.find((m) => m.type === 'link');
+                    for (const mark of inlineMarks) {
+                        switch (mark.type) {
+                            case 'strong':
+                                text = `**${text}**`;
+                                break;
+                            case 'em':
+                                text = `*${text}*`;
+                                break;
+                            case 'strike':
+                                text = `~~${text}~~`;
+                                break;
+                            case 'code':
+                                text = `\`${text}\``;
+                                break;
+                        }
+                    }
+                    if (linkMark) {
+                        text = `[${text}](${linkMark.attrs?.href || ''})`;
+                    }
+                }
+                return text;
+            }
+            case 'mention':
+                // Emit @accountId so the agent can reuse it in comments
+                return `@${node.attrs?.id || node.attrs?.text?.replace('@', '') || ''}`;
+            case 'hardBreak':
+                return '\n';
+            case 'bulletList':
+                return (node.content || [])
+                    .map((child) => TextProcessor.adfToMarkdown(child))
+                    .join('\n');
+            case 'orderedList':
+                return (node.content || [])
+                    .map((child, i) => {
+                    const itemText = TextProcessor.adfListItemContent(child);
+                    return `${i + 1}. ${itemText}`;
+                })
+                    .join('\n');
+            case 'listItem': {
+                const itemText = TextProcessor.adfListItemContent(node);
+                return `- ${itemText}`;
+            }
+            case 'codeBlock': {
+                const lang = node.attrs?.language || '';
+                const code = (node.content || [])
+                    .map((child) => child.text || '')
+                    .join('');
+                return `\`\`\`${lang}\n${code}\n\`\`\``;
+            }
+            case 'blockquote': {
+                const content = (node.content || [])
+                    .map((child) => TextProcessor.adfToMarkdown(child))
+                    .join('\n');
+                return content.split('\n').map((line) => `> ${line}`).join('\n');
+            }
+            case 'rule':
+                return '---';
+            case 'table':
+            case 'tableRow':
+            case 'tableHeader':
+            case 'tableCell':
+                // Flatten table content to text — ADF tables don't round-trip well through markdown
+                return (node.content || [])
+                    .map((child) => TextProcessor.adfToMarkdown(child))
+                    .join(node.type === 'tableRow' ? ' | ' : '\n');
+            case 'mediaSingle':
+            case 'media':
+                // Media nodes can't round-trip; skip silently
+                return '';
+            case 'inlineCard':
+                return node.attrs?.url || '';
+            default:
+                // Unknown node — recurse into children if present
+                if (node.content) {
+                    return (node.content || [])
+                        .map((child) => TextProcessor.adfToMarkdown(child))
+                        .join('');
+                }
+                return node.text || '';
+        }
+    }
+    /** Extract text content from a listItem node (skipping the wrapping paragraph) */
+    static adfListItemContent(node) {
+        return (node.content || [])
+            .map((child) => {
+            if (child.type === 'paragraph') {
+                return (child.content || [])
+                    .map((c) => TextProcessor.adfToMarkdown(c))
+                    .join('');
+            }
+            return TextProcessor.adfToMarkdown(child);
+        })
+            .join('\n');
+    }
     static isFieldPopulated(value) {
         if (value === null || value === undefined)
             return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaronsb/jira-cloud-mcp",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "mcpName": "io.github.aaronsb/jira-cloud",
   "description": "Model Context Protocol (MCP) server for Jira Cloud - enables AI assistants to interact with Jira",
   "type": "module",