@aaronsb/jira-cloud-mcp 0.5.4 → 0.5.6

package/build/client/jira-client.js

@@ -95,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,
@@ -121,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) {
@@ -139,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);
@@ -171,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
@@ -375,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));
     }
@@ -477,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
@@ -578,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/handlers/analysis-handler.js

@@ -4,11 +4,12 @@ import { analysisNextSteps } from '../utils/next-steps.js';
 import { normalizeArgs } from '../utils/normalize-args.js';
 const ALL_METRICS = ['points', 'time', 'schedule', 'cycle', 'distribution'];
 const VALID_GROUP_BY = ['project', 'assignee', 'priority', 'issuetype'];
-const MAX_ISSUES = 500;
+const MAX_ISSUES_HARD = 500; // absolute ceiling for detail metrics — beyond this, context explodes
+const MAX_ISSUES_DEFAULT = 100;
 const CUBE_SAMPLE_PCT = 0.2; // 20% of total issues
 const CUBE_SAMPLE_MIN = 50; // floor — enough for rare dimension values
 const CUBE_SAMPLE_MAX = 500; // ceiling — proven fast with lean search
-const MAX_CUBE_GROUPS = 20;
+const DEFAULT_GROUP_LIMIT = 20;
 const MAX_COUNT_QUERIES = 150; // ADR-206 budget: max count API calls per execution
 const STANDARD_MEASURES = 6; // total, open, overdue, high+, created_7d, resolved_7d
 // ── Helpers ────────────────────────────────────────────────────────────
@@ -58,11 +59,14 @@ function countBy(items, keyFn) {
 function sumBy(items, valueFn) {
     return items.reduce((sum, item) => sum + (valueFn(item) || 0), 0);
 }
-function mapToString(map, separator = ' | ') {
-    return [...map.entries()]
-        .sort((a, b) => b[1] - a[1])
-        .map(([k, v]) => `${k}: ${v}`)
-        .join(separator);
+function mapToString(map, separator = ' | ', limit) {
+    const sorted = [...map.entries()].sort((a, b) => b[1] - a[1]);
+    const capped = limit ? sorted.slice(0, limit) : sorted;
+    const result = capped.map(([k, v]) => `${k}: ${v}`).join(separator);
+    if (limit && sorted.length > limit) {
+        return `${result} | (+${sorted.length - limit} more — use groupLimit to see all)`;
+    }
+    return result;
 }
 function median(values) {
     if (values.length === 0)
@@ -255,16 +259,16 @@ export function renderCycle(issues, now) {
     }
     return lines.join('\n');
 }
-export function renderDistribution(issues) {
+export function renderDistribution(issues, groupLimit = DEFAULT_GROUP_LIMIT) {
     const lines = ['## Distribution', ''];
     const byStatus = countBy(issues, i => i.status);
-    lines.push(`**By status:** ${mapToString(byStatus)}`);
+    lines.push(`**By status:** ${mapToString(byStatus, ' | ', groupLimit)}`);
     const byAssignee = countBy(issues, i => i.assignee || 'Unassigned');
-    lines.push(`**By assignee:** ${mapToString(byAssignee)}`);
+    lines.push(`**By assignee:** ${mapToString(byAssignee, ' | ', groupLimit)}`);
     const byPriority = countBy(issues, i => i.priority || 'None');
-    lines.push(`**By priority:** ${mapToString(byPriority)}`);
+    lines.push(`**By priority:** ${mapToString(byPriority, ' | ', groupLimit)}`);
     const byType = countBy(issues, i => i.issueType || 'Unknown');
-    lines.push(`**By type:** ${mapToString(byType)}`);
+    lines.push(`**By type:** ${mapToString(byType, ' | ', groupLimit)}`);
     return lines.join('\n');
 }
 /** Extract project keys from JQL like "project in (AA, GC, GD)" or "project = AA" */
@@ -408,7 +412,7 @@ function maxGroupsForBudget(implicitCount) {
     const queriesPerGroup = STANDARD_MEASURES + implicitCount;
     return Math.floor(MAX_COUNT_QUERIES / queriesPerGroup);
 }
-async function handleSummary(jiraClient, jql, groupBy, compute) {
+async function handleSummary(jiraClient, jql, groupBy, compute, groupLimit = DEFAULT_GROUP_LIMIT) {
     const lines = [];
     lines.push(`# Summary: ${jql}`);
     lines.push(`As of ${formatDateShort(new Date())} — counts are exact (no sampling cap)`);
@@ -416,21 +420,26 @@ async function handleSummary(jiraClient, jql, groupBy, compute) {
     const implicitDefs = buildImplicitMeasures(jiraClient.customFieldIds);
     const neededImplicits = compute ? detectImplicitMeasures(compute, implicitDefs) : [];
     const groupBudget = maxGroupsForBudget(neededImplicits.length);
+    // Effective group cap: user's preference vs API query budget (whichever is smaller)
+    const effectiveGroupCap = Math.min(groupLimit, groupBudget);
     if (groupBy === 'project') {
         let keys = extractProjectKeys(jql);
         if (keys.length === 0) {
             throw new McpError(ErrorCode.InvalidParams, 'groupBy "project" requires project keys in JQL (e.g., project in (AA, GC))');
         }
-        const capped = keys.length > groupBudget;
+        const capped = keys.length > effectiveGroupCap;
         if (capped)
-            keys = keys.slice(0, groupBudget);
+            keys = keys.slice(0, effectiveGroupCap);
         const remaining = removeProjectClause(jql);
         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));
         if (capped) {
-            lines.push(`*Capped at ${groupBudget} groups to stay within ${MAX_COUNT_QUERIES}-query budget*`);
+            const reason = effectiveGroupCap < groupBudget
+                ? `groupLimit=${effectiveGroupCap} — increase groupLimit to see more`
+                : `${MAX_COUNT_QUERIES}-query budget`;
+            lines.push(`*Capped at ${effectiveGroupCap} groups (${reason})*`);
         }
     }
     else if (groupBy) {
@@ -439,23 +448,29 @@ async function handleSummary(jiraClient, jql, groupBy, compute) {
         if (issues.length === 0) {
             throw new McpError(ErrorCode.InvalidParams, `No issues matched JQL — cannot discover ${groupBy} values`);
         }
-        const dims = extractDimensions(issues);
+        const dims = extractDimensions(issues, groupLimit);
         const dim = dims.find(d => d.name === groupBy);
         if (!dim || dim.values.length === 0) {
             throw new McpError(ErrorCode.InvalidParams, `No ${groupBy} values found in sampled issues`);
         }
-        // Cap groups to query budget
-        const cappedValues = dim.values.slice(0, groupBudget);
+        // Cap groups to effective limit
+        const cappedValues = dim.values.slice(0, effectiveGroupCap);
         const jqlClause = groupByJqlClause(groupBy, cappedValues);
         const rows = await batchParallel(cappedValues.map((value, idx) => () => buildCountRow(jiraClient, value, `(${jql}) AND ${jqlClause[idx]}`, neededImplicits, implicitDefs)), ROW_BATCH_SIZE);
         rows.sort((a, b) => b.unresolved - a.unresolved);
         lines.push('');
         lines.push(renderSummaryTable(rows, compute));
         if (dim.count > cappedValues.length) {
-            const reason = cappedValues.length < dim.values.length
-                ? `capped at ${groupBudget} groups (${MAX_COUNT_QUERIES}-query budget)`
-                : `from ${issues.length}-issue sample`;
-            lines.push(`*Showing top ${cappedValues.length} of ${dim.count} ${groupBy} values (${reason})*`);
+            const reasons = [];
+            if (cappedValues.length < dim.values.length) {
+                reasons.push(effectiveGroupCap < groupBudget
+                    ? `groupLimit=${effectiveGroupCap} — increase groupLimit to see more`
+                    : `${MAX_COUNT_QUERIES}-query budget`);
+            }
+            else {
+                reasons.push(`from ${issues.length}-issue sample`);
+            }
+            lines.push(`*Showing top ${cappedValues.length} of ${dim.count} ${groupBy} values (${reasons.join(', ')})*`);
         }
     }
     else {
@@ -472,7 +487,7 @@ function detectImplicitMeasures(compute, implicitMeasureDefs) {
     return Object.keys(implicitMeasureDefs).filter(name => refs.has(name));
 }
 /** Extract distinct dimension values from sampled issues */
-export function extractDimensions(issues) {
+export function extractDimensions(issues, groupLimit = DEFAULT_GROUP_LIMIT) {
     const dims = [
         { name: 'project', extractor: i => i.key.split('-')[0] },
         { name: 'status', extractor: i => i.status },
@@ -486,10 +501,10 @@ export function extractDimensions(issues) {
             const val = extractor(issue);
             counts.set(val, (counts.get(val) || 0) + 1);
         }
-        // Sort by count descending, cap at MAX_CUBE_GROUPS
+        // Sort by count descending, cap at groupLimit
         const sorted = [...counts.entries()]
             .sort((a, b) => b[1] - a[1])
-            .slice(0, MAX_CUBE_GROUPS);
+            .slice(0, groupLimit);
         return {
             name,
             values: sorted.map(([v]) => v),
@@ -521,7 +536,7 @@ export function renderCubeSetup(jql, sampleSize, dimensions) {
     lines.push('');
     lines.push(`## Suggested Cubes (budget: ${MAX_COUNT_QUERIES} queries)`);
     for (const dim of dimensions) {
-        const groups = Math.min(dim.count, MAX_CUBE_GROUPS);
+        const groups = Math.min(dim.count, DEFAULT_GROUP_LIMIT);
         const queries = groups * STANDARD_MEASURES;
         const estSeconds = Math.max(1, Math.round(queries / 12)); // ~12 parallel queries/sec
         const withinBudget = queries <= MAX_COUNT_QUERIES;
@@ -596,6 +611,9 @@ export async function handleAnalysisRequest(jiraClient, request) {
     if (args.compute && Array.isArray(args.compute) && args.compute.length > 0) {
         compute = parseComputeList(args.compute);
     }
+    // Parse groupLimit — soft cap on group/dimension values (no hard cap for summary metrics)
+    const rawGroupLimit = Number(args.groupLimit);
+    const groupLimit = rawGroupLimit > 0 ? rawGroupLimit : DEFAULT_GROUP_LIMIT;
     // Cube setup — discover dimensions from sample, no issue fetching
     if (hasCubeSetup) {
         const cubeText = await handleCubeSetup(jiraClient, jql);
@@ -609,7 +627,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
     }
     // If only summary requested, skip issue fetching entirely
     if (hasSummary && fetchMetrics.length === 0) {
-        const summaryText = await handleSummary(jiraClient, jql, groupBy, compute);
+        const summaryText = await handleSummary(jiraClient, jql, groupBy, compute, groupLimit);
         const nextSteps = analysisNextSteps(jql, []);
         return {
             content: [{
@@ -618,8 +636,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
                 }],
         };
     }
-    const DEFAULT_MAX = 100;
-    const maxResults = Math.min(Number(args.maxResults) || DEFAULT_MAX, MAX_ISSUES);
+    const maxResults = Math.min(Number(args.maxResults) || MAX_ISSUES_DEFAULT, MAX_ISSUES_HARD);
     // Fetch issues using cursor-based pagination (50 per page, Jira enhanced search API)
     const allIssues = [];
     const seen = new Set();
@@ -658,7 +675,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
     const lines = [];
     // Summary first if requested alongside other metrics
     if (hasSummary) {
-        const summaryText = await handleSummary(jiraClient, jql, groupBy, compute);
+        const summaryText = await handleSummary(jiraClient, jql, groupBy, compute, groupLimit);
         lines.push(summaryText);
     }
     // Header for fetch-based metrics
@@ -668,7 +685,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
         lines.push(`# Detail: ${jql}`);
         lines.push(`Analyzed ${allIssues.length} issues (as of ${formatDateShort(now)})`);
         if (truncated) {
-            lines.push(`*Results capped at ${maxResults} issues — query may match more.*`);
+            lines.push(`*Results capped at ${maxResults} issues — distributions below are approximate. For exact counts, use metrics: ["summary"] with groupBy instead.*`);
         }
         // Render requested metrics
         const renderers = {
@@ -676,7 +693,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
             time: () => renderTime(allIssues),
             schedule: () => renderSchedule(allIssues, now),
             cycle: () => renderCycle(allIssues, now),
-            distribution: () => renderDistribution(allIssues),
+            distribution: () => renderDistribution(allIssues, groupLimit),
         };
         for (const metric of fetchMetrics) {
             lines.push('');

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/schemas/tool-schemas.js

@@ -326,7 +326,7 @@ export const toolSchemas = {
     },
     analyze_jira_issues: {
         name: 'analyze_jira_issues',
-        description: 'Compute project metrics over issues selected by JQL. Use "summary" for exact counts across projects (no sampling cap). Use other metrics for detailed analysis of individual issue data. Always prefer this tool over manage_jira_filter or manage_jira_project for quantitative questions (counts, totals, overdue, workload). Read jira://analysis/recipes for composition patterns.',
+        description: 'Compute project metrics over issues selected by JQL. For counting and breakdown questions ("how many by status/assignee/priority"), use metrics: ["summary"] with groupBy — this gives exact counts with no issue cap. Use detail metrics (points, time, schedule, cycle, distribution) only when you need per-issue analysis; these are capped at maxResults issues. Always prefer this tool over manage_jira_filter or manage_jira_project for quantitative questions. Read jira://analysis/recipes for composition patterns.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -340,12 +340,12 @@ export const toolSchemas = {
                         type: 'string',
                         enum: ['summary', 'points', 'time', 'schedule', 'cycle', 'distribution', 'cube_setup'],
                     },
-                    description: 'Which metric groups to compute. summary = exact issue counts via count API (no cap, fastest). cube_setup = sample issues and discover available dimensions/measures for cube queries. points = earned value/SPI. time = effort estimates. schedule = overdue/risk. cycle = lead time/throughput. distribution = counts by status/assignee/priority/type. Default: all except summary and cube_setup.',
+                    description: 'Which metric groups to compute. summary = exact counts via count API (no issue cap, fastest) — use with groupBy for "how many by assignee/status/priority" questions. distribution = approximate counts from fetched issues (capped by maxResults — use summary + groupBy instead when you need exact counts). cube_setup = discover dimensions before cube queries. points = earned value/SPI. time = effort estimates. schedule = overdue/risk. cycle = lead time/throughput. Default: all detail metrics. For counting/breakdown questions, always prefer summary + groupBy over distribution.',
                 },
                 groupBy: {
                     type: 'string',
                     enum: ['project', 'assignee', 'priority', 'issuetype'],
-                    description: 'Split summary counts by this dimension. Use with metrics: ["summary"]. "project" produces a per-project comparison table.',
+                    description: 'Split counts by this dimension — produces a breakdown table. Use with metrics: ["summary"] for exact counts. This is the correct approach for "how many issues per assignee/priority/type" questions. "project" produces a per-project comparison.',
                 },
                 compute: {
                     type: 'array',
@@ -353,6 +353,11 @@ export const toolSchemas = {
                     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,
                 },
+                groupLimit: {
+                    type: 'integer',
+                    description: 'Max groups/dimension values to show (default 20). Applies to summary groupBy rows and distribution breakdowns. No hard cap for summary metrics — increase freely for full visibility. For detail metrics the issue fetch is separately capped by maxResults.',
+                    default: 20,
+                },
                 maxResults: {
                     type: 'integer',
                     description: 'Max issues to fetch for detail metrics (default 100, max 500). Does not apply to summary (which uses count API).',

package/build/utils/next-steps.js

@@ -132,7 +132,7 @@ export function analysisNextSteps(jql, issueKeys, truncated = false) {
     }
     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'] } });
+        steps.push({ description: 'Distribution counts above are approximate (issue cap hit). For exact breakdowns use summary + groupBy', tool: 'analyze_jira_issues', example: { jql, metrics: ['summary'], groupBy: 'assignee' } }, { description: 'Or narrow JQL for precise detail metrics', 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.4",
+  "version": "0.5.6",
   "mcpName": "io.github.aaronsb/jira-cloud",
   "description": "Model Context Protocol (MCP) server for Jira Cloud - enables AI assistants to interact with Jira",
   "type": "module",