@rui.branco/jira-mcp 1.7.6 → 1.7.8

package/README.md

@@ -225,6 +225,19 @@ For Server / Data Center deployments where Confluence lives on a different host,
 
 **Why ADF for `confluence_get_page`?** The v1 `body.atlas_doc_format` expand is unreliable on modern Cloud pages — table cell background colors and some newer node types only survive the v2 `/api/v2/pages/<id>?body-format=atlas_doc_format` endpoint. `confluence_get_page` therefore does both requests in parallel and merges the v2 ADF body onto the v1 response, so callers get `body.view`, `body.storage` and `body.atlas_doc_format` in one shot.
 
+### Confluence On-Demand Activation
+
+By default, the 21 `confluence_*` tools are hidden from `tools/list` to reduce token footprint. A lightweight `confluence_enable` gateway tool is exposed instead. When a task needs Confluence, the client calls `confluence_enable` and the full tool set appears (the server sends `notifications/tools/list_changed`). Activation is per-process (not persisted to config) and does not bypass instance scopes.
+
+To expose Confluence tools from boot (skip the activation step), set the `confluence` config key or the `JIRA_MCP_CONFLUENCE` environment variable:
+
+| Method | Value |
+|--------|-------|
+| Config (`~/.config/jira-mcp/config.json`) | `"confluence": "always"` |
+| Environment variable | `JIRA_MCP_CONFLUENCE=always` |
+
+The default value is `"on-demand"`.
+
 ### Configuration
 
 Config stored at `~/.config/jira-mcp/config.json`:

package/index.js

@@ -53,6 +53,15 @@ const jiraConfigPath = path.join(
 );
 const rawConfig = JSON.parse(fs.readFileSync(jiraConfigPath, "utf8"));
 
+// Confluence tool visibility: 'on-demand' (default) hides the confluence_*
+// tools until confluence_enable is called; 'always' exposes them from boot.
+// Env JIRA_MCP_CONFLUENCE overrides the config key.
+const confluenceMode = String(process.env.JIRA_MCP_CONFLUENCE || rawConfig.confluence || "on-demand").toLowerCase();
+if (confluenceMode !== "always" && confluenceMode !== "on-demand") {
+  console.error(`jira-mcp: invalid confluence mode "${confluenceMode}", falling back to "on-demand"`);
+}
+let confluenceActive = confluenceMode === "always";
+
 // Normalize config to multi-instance format
 let instances;
 if (rawConfig.instances) {
@@ -181,6 +190,8 @@ const TOOL_METADATA = {
   jira_delete_ticket: { product: "jira", op: "destructive", category: "ticket" },
   jira_remove_attachment: { product: "jira", op: "destructive", category: "attachment" },
   jira_remove_instance: { product: "jira", op: "destructive", category: "config" },
+  // ---- Confluence activation ----
+  confluence_enable: { product: "confluence", op: "read" },
   // ---- Confluence reads ----
   confluence_get_spaces: { product: "confluence", op: "read" },
   confluence_get_space: { product: "confluence", op: "read" },
@@ -758,7 +769,10 @@ function extractText(content, urls = []) {
       } else if (node.type === "hardBreak") {
         text += "\n";
       } else if (node.type === "mention") {
-        text += `@${node.attrs?.text || "user"}`;
+        // attrs.text already includes the leading "@" (e.g. "@Rui Branco").
+        // Don't prepend a second one.
+        const mentionText = node.attrs?.text || "@user";
+        text += mentionText.startsWith("@") ? mentionText : `@${mentionText}`;
       } else if (node.type === "mediaGroup" || node.type === "mediaSingle") {
         text += "[image attachment]\n";
       } else if (
@@ -788,6 +802,14 @@ function extractTextSimple(content) {
   return result.text;
 }
 
+// Prefix each line with "> " so echoed comments render as a markdown blockquote
+function quoteText(text) {
+  return text
+    .split("\n")
+    .map((line) => (line.trim() ? `> ${line}` : ">"))
+    .join("\n");
+}
+
 // ============ USER SEARCH & MENTIONS ============
 
 // Cache for user lookups to avoid repeated API calls
@@ -965,6 +987,54 @@ function autoLinkTextNodes(nodes, instance = defaultInstance) {
   return result;
 }
 
+// Detect a markdown list item line. Returns {indent, ordered, text} or null.
+// Bullets: -, *, + followed by a space. Ordered: "1." or "1)" followed by a space.
+// The marker must be followed by whitespace so inline emphasis (*italic*) and
+// horizontal rules (***) are NOT misread as list items.
+function listItemMatch(line) {
+  const m = line.match(/^(\s*)([-*+]|\d+[.)])\s+(.*)$/);
+  if (!m) return null;
+  return { indent: m[1].length, ordered: /\d/.test(m[2]), text: m[3] };
+}
+
+// Recursively parse a (possibly nested) markdown list starting at lines[startIdx].
+// baseIndent is the indentation of items at this level; more-indented items are
+// folded into the previous item as a nested list. Returns {node, nextIndex}.
+async function parseListBlock(lines, startIdx, baseIndent, instance) {
+  const items = [];
+  let i = startIdx;
+  let ordered = null;
+  while (i < lines.length) {
+    if (!lines[i].trim()) break; // blank line ends the list
+    const m = listItemMatch(lines[i]);
+    if (!m) break;
+    if (m.indent < baseIndent) break; // dedent: belongs to a parent list
+    if (m.indent > baseIndent) {
+      // Deeper indent: nest under the previous item at this level.
+      const sub = await parseListBlock(lines, i, m.indent, instance);
+      if (items.length > 0) {
+        items[items.length - 1].content.push(sub.node);
+      } else {
+        items.push({ type: "listItem", content: [sub.node] });
+      }
+      i = sub.nextIndex;
+      continue;
+    }
+    if (ordered === null) ordered = m.ordered; // list type set by first item
+    else if (m.ordered !== ordered) break; // marker switched: caller starts a new list
+    const inlineContent = await parseInlineFormatting(m.text, instance);
+    items.push({
+      type: "listItem",
+      content: [{ type: "paragraph", content: inlineContent }],
+    });
+    i++;
+  }
+  return {
+    node: { type: ordered ? "orderedList" : "bulletList", content: items },
+    nextIndex: i,
+  };
+}
+
 // Parse text with markdown formatting and @mentions, build ADF content
 async function buildCommentADF(text, instance = defaultInstance) {
   // Sanitize: replace em dashes and en dashes with hyphen
@@ -1077,35 +1147,17 @@ async function buildCommentADF(text, instance = defaultInstance) {
       continue;
     }
 
-    // --- Bullet list (- items) ---
-    if (trimmed.startsWith("- ")) {
-      const listItems = [];
-      while (i < lines.length && lines[i].trim().startsWith("- ")) {
-        const itemText = lines[i].trim().substring(2);
-        const inlineContent = await parseInlineFormatting(itemText, instance);
-        listItems.push({
-          type: "listItem",
-          content: [{ type: "paragraph", content: inlineContent }],
-        });
-        i++;
-      }
-      content.push({ type: "bulletList", content: listItems });
-      continue;
-    }
-
-    // --- Ordered list (1. items) ---
-    if (/^\d+\.\s/.test(trimmed)) {
-      const listItems = [];
-      while (i < lines.length && /^\d+\.\s/.test(lines[i].trim())) {
-        const itemText = lines[i].trim().replace(/^\d+\.\s/, "");
-        const inlineContent = await parseInlineFormatting(itemText, instance);
-        listItems.push({
-          type: "listItem",
-          content: [{ type: "paragraph", content: inlineContent }],
-        });
-        i++;
-      }
-      content.push({ type: "orderedList", content: listItems });
+    // --- Lists (bullet -,*,+ or ordered 1./1)) with nesting ---
+    const listStart = listItemMatch(line);
+    if (listStart) {
+      const { node, nextIndex } = await parseListBlock(
+        lines,
+        i,
+        listStart.indent,
+        instance,
+      );
+      content.push(node);
+      i = nextIndex;
       continue;
     }
 
@@ -1115,13 +1167,12 @@ async function buildCommentADF(text, instance = defaultInstance) {
       i < lines.length &&
       lines[i].trim() &&
       !lines[i].trim().startsWith("```") &&
-      !lines[i].trim().startsWith("# ") &&
-      !lines[i].trim().startsWith("## ") &&
-      !lines[i].trim().startsWith("### ") &&
+      !/^#{1,6}\s/.test(lines[i].trim()) &&
       !lines[i].trim().startsWith("> ") &&
-      !lines[i].trim().startsWith("- ") &&
-      !/^\d+\.\s/.test(lines[i].trim()) &&
+      !listItemMatch(lines[i]) &&
       !/^-{3,}$/.test(lines[i].trim()) &&
+      !/^\*{3,}$/.test(lines[i].trim()) &&
+      !/^_{3,}$/.test(lines[i].trim()) &&
       !(lines[i].trim().startsWith("|") && lines[i].trim().endsWith("|"))
     ) {
       if (paragraphContent.length > 0) paragraphContent.push({ type: "hardBreak" });
@@ -1985,9 +2036,20 @@ async function getChangelogsBulk(jql, maxResults = 50, instance = defaultInstanc
 
 // ============ MCP SERVER ============
 
+const SERVER_INSTRUCTIONS = `# jira-mcp usage rules
+
+- \`instance\` (optional, on most tools): multi-instance setups only. Omit it — it auto-detects from the issue key prefix, else uses the default instance.
+- \`dryRun\` (optional, on mutating tools): if true, returns the HTTP request that would be sent (method, endpoint, body) without calling Atlassian. Multi-step tools only show the first write.
+${confluenceMode !== "always" ? "- Confluence tools are hidden until activated: call `confluence_enable` first when a task needs Confluence (pages, spaces, page comments, labels, attachments).\n" : ""}
+## Writing Jira comments (jira_add_comment / jira_reply_comment / jira_edit_comment)
+Write one short conversational paragraph: start with @DisplayName of who to notify (NOT [~accountId:...] syntax), say what changed, and end with the next step (e.g. 'Ready for verification.'). Keep it HIGH LEVEL for stakeholders/PO/QA — WHAT changed and the impact, not how it was built. Include technical detail (endpoints, payloads, API contracts) ONLY when the reader is a developer and it makes sense; otherwise leave out code, file paths, branch names, commit hashes, and framework-internal terms. NEVER use em dashes (—) or en dashes (–) — use commas, periods, or rewrite. Avoid bullet lists, headings, and bold unless the update genuinely needs them.
+
+## Writing descriptions (jira_create_ticket / jira_update_ticket / jira_create_subtask)
+Structure with Markdown: a one/two-sentence overview, then ## / ### headings (Overview, Details, Acceptance Criteria), '-' bullet lists, numbered steps, tables for structured data, **bold** key terms, fenced \`\`\` blocks for code/payloads. Blank line between blocks. Concise and scannable. Never use em/en dashes.`;
+
 const server = new Server(
   { name: "jira-mcp", version: "1.0.0" },
-  { capabilities: { tools: {} } },
+  { capabilities: { tools: { listChanged: true } }, instructions: SERVER_INSTRUCTIONS },
 );
 
 // Inject `dryRun` into the schema of any mutating tool so MCP clients with
@@ -2006,13 +2068,16 @@ function _injectDryRunSchema(tool) {
         ...props,
         dryRun: {
           type: "boolean",
-          description: "If true, return the HTTP request that would be sent (method, endpoint, body) without calling Atlassian. Multi-step tools only show the first write.",
+          description: "Preview: return the would-be HTTP request without executing.",
         },
       },
     },
   };
 }
 
+// Additive formatting guidance moved to SERVER_INSTRUCTIONS to reduce per-tool
+// token cost. Field descriptions retain their short base text only.
+
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   const rawTools = [
       {
@@ -2024,7 +2089,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             instance: {
               type: "string",
-              description: "Instance name (for multi-instance setups). Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: [],
@@ -2052,7 +2117,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey"],
@@ -2078,7 +2143,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name (for multi-instance setups). Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["jql"],
@@ -2087,7 +2152,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       {
         name: "jira_add_comment",
         description:
-          "Add a comment to a Jira ticket. IMPORTANT RULES: (1) Write comments at a HIGH LEVEL for stakeholders, product owners, and managers. Focus on WHAT was done and the business impact, NOT how it was done. Example: 'Implemented the new filtering feature for the dashboard' instead of 'Added a useEffect hook with debounced API calls to filter endpoint'. (2) NEVER mention technical details: no code, no function names, no file paths, no git branches, no commit hashes, no 'pushed to main', no framework-specific terms (React, Angular, hooks, components, etc.). (3) Use @DisplayName (e.g. @Julia Pereszta) for mentions, NOT [~accountId:...] syntax. (4) NEVER use em dashes (—) or en dashes (–), use commas, periods, or rewrite the sentence instead.",
+          "Add a comment to a Jira ticket. Follow the server instructions' comment style rules.",
         inputSchema: {
           type: "object",
           properties: {
@@ -2095,10 +2160,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: "string",
               description: "The Jira issue key (e.g., MODS-123)",
             },
-            comment: { type: "string", description: "The comment text to add" },
+            comment: {
+              type: "string",
+              description: "The comment text to add.",
+            },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey", "comment"],
@@ -2120,10 +2188,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               description:
                 "The ID of the comment to reply to. Use jira_get_ticket to see comments and their IDs.",
             },
-            reply: { type: "string", description: "The reply text" },
+            reply: {
+              type: "string",
+              description: "The reply text.",
+            },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey", "commentId", "reply"],
@@ -2132,7 +2203,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       {
         name: "jira_edit_comment",
         description:
-          "Edit an existing comment on a Jira ticket. Replaces the comment text. IMPORTANT: Use @DisplayName (e.g. @Julia Pereszta) for mentions — NOT [~accountId:...] syntax. Keep comments non-technical and user-facing. Never mention git details like 'pushed to main', branch names, or technical implementation details.",
+          "Edit an existing comment on a Jira ticket (replaces the text). Follow the server instructions' comment style rules.",
         inputSchema: {
           type: "object",
           properties: {
@@ -2145,10 +2216,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               description:
                 "The ID of the comment to edit. Use jira_get_ticket to see comments and their IDs.",
             },
-            comment: { type: "string", description: "The new comment text" },
+            comment: {
+              type: "string",
+              description: "The new comment text.",
+            },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey", "commentId", "comment"],
@@ -2172,7 +2246,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey", "commentId"],
@@ -2201,7 +2275,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey"],
@@ -2262,7 +2336,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey"],
@@ -2286,7 +2360,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name (for multi-instance setups). Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["query"],
@@ -2316,7 +2390,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name (for multi-instance setups with jql). Auto-detected from issueKey if provided.",
+              description: "Instance name (optional).",
             },
           },
           required: [],
@@ -2408,7 +2482,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name. Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: [],
@@ -2435,7 +2509,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             description: {
               type: "string",
-              description: "The issue description text. Supports @mentions via @DisplayName.",
+              description:
+                "The issue description text. Supports @mentions via @DisplayName.",
             },
             assignee: {
               type: "string",
@@ -2478,7 +2553,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from project key if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["projectKey", "issueType", "summary"],
@@ -2501,7 +2576,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             description: {
               type: "string",
-              description: "The subtask description text. Supports @mentions via @DisplayName.",
+              description:
+                "The subtask description text. Supports @mentions via @DisplayName.",
             },
             assignee: {
               type: "string",
@@ -2522,7 +2598,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from parent issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["parentKey", "summary"],
@@ -2553,7 +2629,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from inward issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["inwardIssueKey", "outwardIssueKey", "linkType"],
@@ -2576,7 +2652,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey"],
@@ -2607,7 +2683,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey"],
@@ -2622,7 +2698,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             instance: {
               type: "string",
-              description: "Instance name (for multi-instance setups). Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: [],
@@ -2641,7 +2717,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey"],
@@ -2664,7 +2740,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey", "linkedIssueKey"],
@@ -2691,7 +2767,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: [],
@@ -2714,7 +2790,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey", "accountId"],
@@ -2737,7 +2813,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey", "accountId"],
@@ -2768,7 +2844,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey", "timeSpent"],
@@ -2787,7 +2863,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey"],
@@ -2818,7 +2894,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from issue key prefix if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["issueKey"],
@@ -2842,7 +2918,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name (for multi-instance setups). Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["sprintId", "issueKeys"],
@@ -2865,7 +2941,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name (for multi-instance setups). Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["boardId"],
@@ -2892,7 +2968,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name (for multi-instance setups). Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: [],
@@ -2911,7 +2987,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from project key if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["projectKey"],
@@ -2926,7 +3002,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             instance: {
               type: "string",
-              description: "Instance name (for multi-instance setups). Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: [],
@@ -2945,7 +3021,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from project key if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["projectKey"],
@@ -2964,7 +3040,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name override. Auto-detected from project key if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: ["projectKey"],
@@ -2979,7 +3055,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             instance: {
               type: "string",
-              description: "Instance name. Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: [],
@@ -2993,7 +3069,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           type: "object",
           properties: {
             spaceKey: { type: "string", description: "Space key (e.g., 'ENG')." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["spaceKey"],
         },
@@ -3008,7 +3084,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             spaceKey: { type: "string", description: "Unique space key (letters/numbers). Will be uppercased." },
             name: { type: "string", description: "Human-readable space name." },
             description: { type: "string", description: "Optional plain-text description." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["spaceKey", "name"],
         },
@@ -3023,7 +3099,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             spaceKey: { type: "string", description: "Space key to update." },
             name: { type: "string", description: "New space name." },
             description: { type: "string", description: "New plain-text description." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["spaceKey"],
         },
@@ -3036,7 +3112,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           type: "object",
           properties: {
             spaceKey: { type: "string", description: "Space key to delete." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["spaceKey"],
         },
@@ -3052,7 +3128,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             spaceKey: { type: "string", description: "Optional space key to scope the search." },
             type: { type: "string", description: "Content type (default: page). e.g. page, blogpost, comment, attachment." },
             limit: { type: "number", description: "Max results (default: 25)." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["query"],
         },
@@ -3067,7 +3143,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             spaceKey: { type: "string", description: "Optional space key to scope the query." },
             sinceDays: { type: "number", description: "Days back from now (default: 30)." },
             limit: { type: "number", description: "Max results (default: 25)." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: [],
         },
@@ -3081,7 +3157,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             spaceKey: { type: "string", description: "Space key (required)." },
             limit: { type: "number", description: "Max results (default: 50)." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["spaceKey"],
         },
@@ -3095,7 +3171,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             pageId: { type: "string", description: "Parent page ID (required)." },
             limit: { type: "number", description: "Max results (default: 50)." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["pageId"],
         },
@@ -3109,7 +3185,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             pageId: { type: "string", description: "Page ID (required)." },
             includeAdf: { type: "boolean", description: "Fetch ADF body via v2 API and merge (default: true)." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["pageId"],
         },
@@ -3123,7 +3199,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             pageId: { type: "string", description: "Page ID (required)." },
             limit: { type: "number", description: "Max results (default: 50)." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["pageId"],
         },
@@ -3138,7 +3214,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             pageId: { type: "string", description: "Page ID (required)." },
             body: { type: "string", description: "Comment body (plain text by default, or storage XHTML if format=storage)." },
             format: { type: "string", description: "'text' (default) or 'storage'." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["pageId", "body"],
         },
@@ -3154,7 +3230,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             title: { type: "string", description: "New page title (optional — retains current if omitted)." },
             body: { type: "string", description: "New body as storage XHTML (optional — retains current if omitted)." },
             version: { type: "number", description: "Explicit new version number. If omitted, current+1 is computed." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["pageId"],
         },
@@ -3170,7 +3246,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             title: { type: "string", description: "Page title (required)." },
             body: { type: "string", description: "Storage-format XHTML body (required)." },
             parentId: { type: "string", description: "Optional parent page ID to nest under." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["spaceKey", "title", "body"],
         },
@@ -3182,7 +3258,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           type: "object",
           properties: {
             pageId: { type: "string", description: "Page ID (required)." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["pageId"],
         },
@@ -3194,7 +3270,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           type: "object",
           properties: {
             pageId: { type: "string", description: "Page ID (required)." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["pageId"],
         },
@@ -3207,7 +3283,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             pageId: { type: "string", description: "Page ID (required)." },
             label: { type: "string", description: "Label name (required)." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["pageId", "label"],
         },
@@ -3220,7 +3296,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             pageId: { type: "string", description: "Page ID (required)." },
             label: { type: "string", description: "Label name (required)." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["pageId", "label"],
         },
@@ -3233,7 +3309,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             pageId: { type: "string", description: "Page ID (required)." },
             limit: { type: "number", description: "Max results (default: 50)." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["pageId"],
         },
@@ -3250,7 +3326,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             fileContent: { type: "string", description: "Base64-encoded file content (requires fileName)." },
             fileName: { type: "string", description: "File name (required with fileContent; optional with filePath)." },
             comment: { type: "string", description: "Optional attachment comment." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["pageId"],
         },
@@ -3264,13 +3340,22 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             pageId: { type: "string", description: "Page ID (required)." },
             filename: { type: "string", description: "Attachment filename (required)." },
-            instance: { type: "string", description: "Instance name. Uses default instance if omitted." },
+            instance: { type: "string", description: "Instance name (optional)." },
           },
           required: ["pageId", "filename"],
         },
       },
     ];
-  return { tools: rawTools.map(_injectDryRunSchema) };
+  let tools = rawTools;
+  if (!confluenceActive) {
+    tools = rawTools.filter(t => !t.name.startsWith("confluence_"));
+    tools.push({
+      name: "confluence_enable",
+      description: "Activate the Confluence tool set (pages, spaces, page comments, labels, attachments, search). Call this first when a task needs Confluence; the confluence_* tools then become available. Activation only changes tool visibility for this server process; per-instance scopes still apply to every Confluence operation.",
+      inputSchema: { type: "object", properties: {}, required: [] },
+    });
+  }
+  return { tools: tools.map(_injectDryRunSchema) };
 });
 
 async function runWithPolicy(name, args, handler) {
@@ -3388,6 +3473,19 @@ async function runWithPolicy(name, args, handler) {
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
 
+  if (name === "confluence_enable") {
+    const wasActive = confluenceActive;
+    confluenceActive = true;
+    if (!wasActive) server.sendToolListChanged().catch((e) => console.error("jira-mcp: tools/list_changed notification failed:", e?.message || e));
+    return { content: [{ type: "text", text: wasActive ? "Confluence tools were already active." : "Confluence tools activated — the confluence_* tools are now available." }] };
+  }
+  // A client with a cached tool list may call a confluence_* tool directly
+  // while hidden — auto-activate instead of failing.
+  if (!confluenceActive && TOOL_METADATA[name]?.product === "confluence" && name !== "confluence_enable") {
+    confluenceActive = true;
+    server.sendToolListChanged().catch((e) => console.error("jira-mcp: tools/list_changed notification failed:", e?.message || e));
+  }
+
   return runWithPolicy(name, args, async () => {
     if (name === "jira_get_myself") {
       const inst = getInstanceByName(args.instance);
@@ -3509,11 +3607,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }, inst);
       const author = result.author?.displayName || "Unknown";
       const created = new Date(result.created).toLocaleString();
+      const postedText = quoteText(extractTextSimple(result.body).trim());
       return {
         content: [
           {
             type: "text",
-            text: `Comment added to ${args.issueKey} by ${author} at ${created}.`,
+            text: `Comment added to ${args.issueKey} by ${author} at ${created}:\n\n${postedText}`,
           },
         ],
       };
@@ -3577,11 +3676,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }, inst);
       const author = result.author?.displayName || "Unknown";
       const created = new Date(result.created).toLocaleString();
+      const postedText = quoteText(extractTextSimple(result.body).trim());
       return {
         content: [
           {
             type: "text",
-            text: `Reply to ${originalAuthor}'s comment posted on ${args.issueKey} by ${author} at ${created}.`,
+            text: `Reply to ${originalAuthor}'s comment posted on ${args.issueKey} by ${author} at ${created}:\n\n${postedText}`,
           },
         ],
       };
@@ -3601,11 +3701,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         { method: "PUT", body },
         inst,
       );
+      const editedText = quoteText(extractTextSimple(result.body).trim());
       return {
         content: [
           {
             type: "text",
-            text: `Comment ${args.commentId} on ${args.issueKey} updated.`,
+            text: `Comment ${args.commentId} on ${args.issueKey} updated:\n\n${editedText}`,
           },
         ],
       };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rui.branco/jira-mcp",
-  "version": "1.7.6",
+  "version": "1.7.8",
   "description": "Jira & Confluence MCP server for any MCP-compatible AI client (Claude Code, Codex, Antigravity, Cursor, etc.) - fetch tickets, search with JQL, update tickets, manage comments, change status, get Figma designs. Optional per-tool scopes, dry-run, audit log, and rate limiting.",
   "main": "index.js",
   "bin": {