@rui.branco/jira-mcp 1.7.6 → 1.7.7

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 (
@@ -965,6 +979,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 +1139,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 +1159,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 +2028,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 +2060,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 +2081,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 +2109,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 +2135,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 +2144,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 +2152,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 +2180,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 +2195,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 +2208,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 +2238,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 +2267,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 +2328,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 +2352,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 +2382,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 +2474,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name. Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: [],
@@ -2435,7 +2501,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 +2545,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 +2568,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 +2590,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 +2621,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 +2644,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 +2675,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 +2690,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 +2709,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 +2732,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 +2759,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 +2782,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 +2805,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 +2836,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 +2855,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 +2886,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 +2910,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 +2933,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 +2960,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 +2979,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 +2994,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 +3013,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 +3032,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 +3047,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             instance: {
               type: "string",
-              description: "Instance name. Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: [],
@@ -2993,7 +3061,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 +3076,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 +3091,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 +3104,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 +3120,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 +3135,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 +3149,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 +3163,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 +3177,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 +3191,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 +3206,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 +3222,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 +3238,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 +3250,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 +3262,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 +3275,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 +3288,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 +3301,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 +3318,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 +3332,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 +3465,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rui.branco/jira-mcp",
-  "version": "1.7.6",
+  "version": "1.7.7",
   "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": {