@ecubelabs/atlassian-mcp 1.10.0 → 1.12.0

package/dist/confluence-tools/confluence-storage-format-help.js

@@ -33,6 +33,7 @@ export const registerConfluenceStorageFormatHelp = (server) => {
 1. **Jira**: <ac:structured-macro ac:name="jira"><ac:parameter ac:name="key">HA-2584</ac:parameter></ac:structured-macro>
 2. **Date**: <time datetime="2025-12-03" />
 3. **User**: <ac:link><ri:user ri:account-id="ACCOUNT_ID" /></ac:link>
+   To find ACCOUNT_ID: Use Jira "search-users" or "get-user-picker" tool. Atlassian Cloud accountIds work across both Jira and Confluence.
 
 ## Key Rules
 - Use h2/h3 for headings (not h1)
@@ -129,6 +130,8 @@ Languages: javascript, typescript, python, bash, json, yaml, etc.`,
   <ri:user ri:account-id="ACCOUNT_ID" />
 </ac:link>
 
+To find ACCOUNT_ID: Use Jira "search-users" or "get-user-picker" tool to look up the user's accountId. Atlassian Cloud accountIds work across both Jira and Confluence.
+
 ## External Link
 <a href="https://example.com">Link text</a>
 
@@ -162,6 +165,15 @@ Attach images to page first, then reference by filename.`,
 ✅ ALWAYS:
 <time datetime="2025-12-03" />
 
+## User Mention (MANDATORY for people)
+❌ NEVER: "@username" or "John Doe"
+✅ ALWAYS:
+<ac:link>
+  <ri:user ri:account-id="ACCOUNT_ID" />
+</ac:link>
+
+To find ACCOUNT_ID: Use Jira "search-users" or "get-user-picker" tool.
+
 ## Status Chip
 <ac:structured-macro ac:name="status" ac:schema-version="1">
   <ac:parameter ac:name="colour">Green</ac:parameter>
@@ -187,7 +199,7 @@ Types: two_equal, three_equal. Use sparingly.`,
 ## MANDATORY Rules
 1. Jira keys → MUST use Jira macro
 2. Dates → MUST use <time> element
-3. People → MUST use user mention link
+3. People → MUST use user mention link (use Jira "search-users" or "get-user-picker" to find accountId)
 4. Lists → NEVER use <p> inside <li>
 
 ## Document Structure

package/dist/jira-tools-register.js

@@ -353,7 +353,10 @@ export const registerJiraTools = (server) => {
         summary: z.string().describe('Issue summary'),
         issueTypeId: z.string().optional().describe('Issue type ID'),
         issueTypeName: z.string().optional().describe('Issue type name'),
-        description: z.string().optional().describe('Issue description (plain text)'),
+        description: z
+            .string()
+            .optional()
+            .describe('Issue description in markdown. To mention a user, first use search-users or get-user-picker to get their accountId, then use syntax <@accountId:ACCOUNT_ID>. Example: "Assigned to <@accountId:5b10a284> for review."'),
         assigneeAccountId: z.string().optional().describe('Assignee accountId (Jira Cloud)'),
         reporterAccountId: z
             .string()
@@ -429,7 +432,10 @@ export const registerJiraTools = (server) => {
     server.tool('edit-issue', 'Edit fields on a Jira issue', {
         issueKey: z.string().describe('Jira issue key (e.g. PROJ-123)'),
         summary: z.string().optional().describe('New summary'),
-        description: z.string().optional().describe('New description (plain text)'),
+        description: z
+            .string()
+            .optional()
+            .describe('New description in markdown. To mention a user, first use search-users or get-user-picker to get their accountId, then use syntax <@accountId:ACCOUNT_ID>.'),
         assigneeAccountId: z
             .string()
             .optional()
@@ -469,7 +475,7 @@ export const registerJiraTools = (server) => {
             };
         }
     });
-    server.tool('search-users', 'Search for users', {
+    server.tool('search-users', 'Search for users to get their accountId (useful for mentioning users in Jira comments/descriptions with <@accountId:ID> syntax, or in Confluence pages with <ac:link><ri:user ri:account-id="ID" /></ac:link>). Atlassian Cloud accountIds work across both Jira and Confluence.', {
         query: z.string().optional().describe('Query string to search users'),
         accountId: z.string().optional().describe('Account ID to search for'),
         startAt: z.number().min(0).optional().describe('The index of the first item to return'),
@@ -499,7 +505,7 @@ export const registerJiraTools = (server) => {
             };
         }
     });
-    server.tool('get-user-picker', 'Get user picker suggestions for autocomplete', {
+    server.tool('get-user-picker', 'Get user picker suggestions for autocomplete. Use this to find accountIds for mentioning users in Jira (with <@accountId:ID> syntax) or Confluence (with <ac:link><ri:user ri:account-id="ID" /></ac:link>). Atlassian Cloud accountIds work across both Jira and Confluence.', {
         query: z.string().describe('Query string for user search'),
         maxResults: z.number().min(1).max(1000).optional().describe('Maximum number of users to return'),
         showAvatar: z.boolean().optional().describe('Whether to show user avatars'),
@@ -987,7 +993,13 @@ export const registerJiraTools = (server) => {
     });
     server.tool('create-comment', 'Add a comment to an issue', {
         issueKey: z.string().describe('Issue key (e.g. PROJ-123)'),
-        body: z.string().describe('Comment text'),
+        body: z
+            .string()
+            .describe('Comment text in markdown. To mention a user, use search-users or get-user-picker to get their accountId, then use syntax <@accountId:ACCOUNT_ID>. Example: "Hey <@accountId:5b10a284>, please review this."'),
+        parentId: z
+            .string()
+            .optional()
+            .describe('Parent comment ID to reply to. Use get-comments to find the comment ID to reply to.'),
         visibility: z
             .object({
             type: z.enum(['group', 'role']).describe('Visibility type'),
@@ -1002,10 +1014,11 @@ export const registerJiraTools = (server) => {
         }))
             .optional()
             .describe('Comment properties'),
-    }, async ({ issueKey, body, visibility, properties }) => {
+    }, async ({ issueKey, body, parentId, visibility, properties }) => {
         try {
             const comment = await jiraService.createComment(issueKey, {
                 body,
+                parentId,
                 visibility,
                 properties: properties,
             });
@@ -1027,7 +1040,9 @@ export const registerJiraTools = (server) => {
     server.tool('update-comment', 'Update an existing comment', {
         issueKey: z.string().describe('Issue key (e.g. PROJ-123)'),
         commentId: z.string().describe('Comment ID to update'),
-        body: z.string().describe('New comment text'),
+        body: z
+            .string()
+            .describe('New comment text in markdown. To mention a user, use search-users or get-user-picker to get their accountId, then use syntax <@accountId:ACCOUNT_ID>.'),
         visibility: z
             .object({
             type: z.enum(['group', 'role']).describe('Visibility type'),
@@ -1175,7 +1190,9 @@ export const registerJiraTools = (server) => {
             .describe('Outward issue key (either this or outwardIssueId must be provided)'),
         comment: z
             .object({
-            body: z.string().describe('Comment text'),
+            body: z
+                .string()
+                .describe('Comment text in markdown. Supports mention syntax <@accountId:ACCOUNT_ID>.'),
             visibility: z
                 .object({
                 type: z.enum(['group', 'role']).describe('Visibility type'),

package/dist/libs/adf-mention-utils.js

@@ -0,0 +1,105 @@
+import { markdownToAdf } from 'marklassian';
+const MENTION_PATTERN = /<@accountId:([^>]+)>/g;
+function hasCodeMark(marks) {
+    return marks?.some((m) => m.type === 'code') ?? false;
+}
+function splitTextWithMentions(node) {
+    if (!node.text || hasCodeMark(node.marks)) {
+        return [node];
+    }
+    const text = node.text;
+    const marks = node.marks;
+    const result = [];
+    let lastIndex = 0;
+    for (const match of text.matchAll(MENTION_PATTERN)) {
+        const matchStart = match.index;
+        const accountId = match[1];
+        // Text before the mention
+        if (matchStart > lastIndex) {
+            const before = text.slice(lastIndex, matchStart);
+            const textNode = { type: 'text', text: before };
+            if (marks?.length)
+                textNode.marks = marks;
+            result.push(textNode);
+        }
+        // Mention node (marks are NOT applied to mentions)
+        result.push({
+            type: 'mention',
+            attrs: {
+                id: accountId,
+                text: `@${accountId}`,
+                accessLevel: '',
+            },
+        });
+        lastIndex = matchStart + match[0].length;
+    }
+    // Remaining text after last mention
+    if (lastIndex < text.length) {
+        const after = text.slice(lastIndex);
+        const textNode = { type: 'text', text: after };
+        if (marks?.length)
+            textNode.marks = marks;
+        result.push(textNode);
+    }
+    return result.length > 0 ? result : [node];
+}
+function processNode(node, parentType) {
+    // Skip codeBlock contents entirely
+    if (node.type === 'codeBlock') {
+        return node;
+    }
+    // Process text nodes that may contain mention patterns
+    if (node.type === 'text' && node.text && parentType !== 'codeBlock') {
+        // splitTextWithMentions handles code mark check internally
+        const parts = splitTextWithMentions(node);
+        // If no mention was found, return original node
+        if (parts.length === 1 && parts[0] === node) {
+            return node;
+        }
+        // Return a marker that the parent should expand
+        return { type: '__mention_expanded__', content: parts };
+    }
+    // Recurse into children
+    if (node.content) {
+        const newContent = [];
+        for (const child of node.content) {
+            const processed = processNode(child, node.type);
+            if (processed.type === '__mention_expanded__' && processed.content) {
+                newContent.push(...processed.content);
+            }
+            else {
+                newContent.push(processed);
+            }
+        }
+        return { ...node, content: newContent };
+    }
+    return node;
+}
+/**
+ * Converts markdown to ADF with support for user mentions.
+ *
+ * Use the syntax `<@accountId:ACCOUNT_ID>` in markdown text to create
+ * ADF mention nodes. The ACCOUNT_ID can be obtained via the Jira
+ * `search-users` or `get-user-picker` tools.
+ *
+ * Example: "Hey <@accountId:5b10a284>, please review this."
+ */
+export function markdownToAdfWithMentions(markdown) {
+    const doc = markdownToAdf(markdown);
+    // Fast path: no mention patterns in the source text
+    if (!MENTION_PATTERN.test(markdown)) {
+        return doc;
+    }
+    // Reset regex lastIndex after test()
+    MENTION_PATTERN.lastIndex = 0;
+    return {
+        ...doc,
+        content: doc.content.map((node) => {
+            const processed = processNode(node);
+            if (processed.type === '__mention_expanded__' && processed.content) {
+                return { type: 'paragraph', content: processed.content };
+            }
+            return processed;
+        }),
+    };
+}

package/dist/libs/jira-client.js

@@ -1,5 +1,5 @@
-import { markdownToAdf } from 'marklassian';
 import { atlassianConfig } from '../config.js';
+import { markdownToAdfWithMentions } from './adf-mention-utils.js';
 import { BaseApiService } from './base-client.js';
 export class JiraService extends BaseApiService {
     constructor() {
@@ -174,7 +174,7 @@ export class JiraService extends BaseApiService {
         }
         // Optional fields
         if (options.description) {
-            fields.description = markdownToAdf(options.description);
+            fields.description = markdownToAdfWithMentions(options.description);
         }
         if (options.assigneeAccountId) {
             fields.assignee = { accountId: options.assigneeAccountId };
@@ -212,7 +212,7 @@ export class JiraService extends BaseApiService {
             fields.summary = options.summary;
         }
         if (options.description) {
-            fields.description = markdownToAdf(options.description);
+            fields.description = markdownToAdfWithMentions(options.description);
         }
         if (options.unassignAssignee) {
             fields.assignee = null;
@@ -544,8 +544,11 @@ export class JiraService extends BaseApiService {
      */
     async createComment(issueKey, options) {
         const body = {
-            body: markdownToAdf(options.body),
+            body: markdownToAdfWithMentions(options.body),
         };
+        if (options.parentId) {
+            body.parentId = options.parentId;
+        }
         if (options.visibility) {
             body.visibility = options.visibility;
         }
@@ -560,7 +563,7 @@ export class JiraService extends BaseApiService {
      */
     async updateComment(issueKey, commentId, options) {
         const body = {
-            body: markdownToAdf(options.body),
+            body: markdownToAdfWithMentions(options.body),
         };
         if (options.visibility) {
             body.visibility = options.visibility;
@@ -614,7 +617,7 @@ export class JiraService extends BaseApiService {
         };
         if (options.comment) {
             body.comment = {
-                body: markdownToAdf(options.comment.body),
+                body: markdownToAdfWithMentions(options.comment.body),
                 ...(options.comment.visibility && {
                     visibility: options.comment.visibility,
                 }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecubelabs/atlassian-mcp",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "bin": "./dist/index.js",
   "repository": {
     "url": "https://github.com/Ecube-Labs/skynet.git"