@aaronsb/jira-cloud-mcp 0.5.4 → 0.5.5

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/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/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.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",