@rui.branco/jira-mcp 1.7.5 → 1.7.7

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) {
@@ -134,10 +143,323 @@ if (!fs.existsSync(attachmentDir)) {
   fs.mkdirSync(attachmentDir, { recursive: true });
 }
 
+// ============ TOOL METADATA + POLICY ============
+//
+// TOOL_METADATA is the source of truth for op classification — NOT the HTTP
+// method. The new Jira /search/jql endpoint is POST but semantically a read,
+// so deciding "is this a write?" from the request method would wrongly trip
+// audit + rate-limit on every search.
+
+const TOOL_METADATA = {
+  // ---- Jira reads ----
+  jira_get_myself: { product: "jira", op: "read" },
+  jira_get_ticket: { product: "jira", op: "read" },
+  jira_search: { product: "jira", op: "read" },
+  jira_search_users: { product: "jira", op: "read" },
+  jira_get_changelog: { product: "jira", op: "read" },
+  jira_list_instances: { product: "jira", op: "read" },
+  jira_get_teams: { product: "jira", op: "read" },
+  jira_get_link_types: { product: "jira", op: "read" },
+  jira_get_transitions: { product: "jira", op: "read" },
+  jira_get_worklogs: { product: "jira", op: "read" },
+  jira_get_sprints: { product: "jira", op: "read" },
+  jira_get_boards: { product: "jira", op: "read" },
+  jira_get_issue_types: { product: "jira", op: "read" },
+  jira_get_priorities: { product: "jira", op: "read" },
+  jira_get_components: { product: "jira", op: "read" },
+  jira_get_versions: { product: "jira", op: "read" },
+  // ---- Jira writes (reversible) ----
+  jira_add_comment: { product: "jira", op: "write", category: "comment" },
+  jira_reply_comment: { product: "jira", op: "write", category: "comment" },
+  jira_edit_comment: { product: "jira", op: "write", category: "comment" },
+  jira_transition: { product: "jira", op: "write", category: "transition" },
+  jira_update_ticket: { product: "jira", op: "write", category: "ticket" },
+  jira_create_ticket: { product: "jira", op: "write", category: "ticket" },
+  jira_create_subtask: { product: "jira", op: "write", category: "ticket" },
+  jira_clone_ticket: { product: "jira", op: "write", category: "ticket" },
+  jira_link_tickets: { product: "jira", op: "write", category: "link" },
+  jira_unlink_tickets: { product: "jira", op: "write", category: "link" },
+  jira_add_attachment: { product: "jira", op: "write", category: "attachment" },
+  jira_add_watcher: { product: "jira", op: "write", category: "watcher" },
+  jira_remove_watcher: { product: "jira", op: "write", category: "watcher" },
+  jira_add_worklog: { product: "jira", op: "write", category: "worklog" },
+  jira_move_to_sprint: { product: "jira", op: "write", category: "sprint" },
+  jira_add_instance: { product: "jira", op: "write", category: "config" },
+  // ---- Jira destructive ----
+  jira_delete_comment: { product: "jira", op: "destructive", category: "comment" },
+  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" },
+  confluence_search: { product: "confluence", op: "read" },
+  confluence_get_recent_pages: { product: "confluence", op: "read" },
+  confluence_get_space_root_pages: { product: "confluence", op: "read" },
+  confluence_get_page_children: { product: "confluence", op: "read" },
+  confluence_get_page: { product: "confluence", op: "read" },
+  confluence_get_comments: { product: "confluence", op: "read" },
+  confluence_get_labels: { product: "confluence", op: "read" },
+  confluence_list_attachments: { product: "confluence", op: "read" },
+  confluence_download_attachment: { product: "confluence", op: "read" },
+  // ---- Confluence writes ----
+  confluence_create_space: { product: "confluence", op: "write", category: "space" },
+  confluence_update_space: { product: "confluence", op: "write", category: "space" },
+  confluence_add_comment: { product: "confluence", op: "write", category: "comment" },
+  confluence_update_page: { product: "confluence", op: "write", category: "page" },
+  confluence_create_page: { product: "confluence", op: "write", category: "page" },
+  confluence_add_label: { product: "confluence", op: "write", category: "label" },
+  confluence_remove_label: { product: "confluence", op: "write", category: "label" },
+  confluence_upload_attachment: { product: "confluence", op: "write", category: "attachment" },
+  // ---- Confluence destructive ----
+  confluence_delete_space: { product: "confluence", op: "destructive", category: "space" },
+  confluence_delete_page: { product: "confluence", op: "destructive", category: "page" },
+};
+
+const COMMENT_TOOLS = new Set([
+  "jira_add_comment",
+  "jira_reply_comment",
+  "jira_edit_comment",
+  "confluence_add_comment",
+]);
+
+const SCOPE_PRESETS = {
+  "read-only": (m) => m.op === "read",
+  "comments-only": (m, name) => m.op === "read" || COMMENT_TOOLS.has(name),
+  "no-destructive": (m) => m.op !== "destructive",
+  unrestricted: () => true,
+};
+
+function checkScope(toolName, instance) {
+  const scopes = instance && instance.scopes;
+  // Fail-open when instance has no scopes block — preserves existing installs.
+  if (!scopes) return { allowed: true };
+
+  const meta = TOOL_METADATA[toolName];
+  // Unknown tool with scopes configured → fail closed.
+  if (!meta) {
+    return { allowed: false, reason: `Tool '${toolName}' has no metadata; denied under scoped instance '${instance.name}'.` };
+  }
+
+  // Explicit deny wins.
+  if (Array.isArray(scopes.deny) && scopes.deny.includes(toolName)) {
+    return { allowed: false, reason: `Tool '${toolName}' is in instance '${instance.name}' deny list.` };
+  }
+  // Explicit allow wins after deny.
+  if (Array.isArray(scopes.allow) && scopes.allow.includes(toolName)) {
+    return { allowed: true };
+  }
+  // Preset.
+  if (scopes.preset) {
+    const presetFn = SCOPE_PRESETS[scopes.preset];
+    if (!presetFn) {
+      return { allowed: false, reason: `Unknown scope preset '${scopes.preset}' on instance '${instance.name}'.` };
+    }
+    if (presetFn(meta, toolName)) return { allowed: true };
+    return { allowed: false, reason: `Tool '${toolName}' (${meta.op}) not permitted by preset '${scopes.preset}' on '${instance.name}'.` };
+  }
+  // scopes block present but neither preset nor allow listed → deny.
+  return { allowed: false, reason: `Tool '${toolName}' not in instance '${instance.name}' allow list.` };
+}
+
+// ---- Dry-run resolution ----
+const DRY_RUN_ENV =
+  process.env.JIRA_MCP_DRY_RUN === "1" ||
+  process.env.JIRA_MCP_DRY_RUN === "true";
+
+function resolveDryRun(toolName, args, instance) {
+  const meta = TOOL_METADATA[toolName];
+  if (!meta || meta.op === "read") return false;
+  if (args && args.dryRun === true) return true;
+  if (args && args.dryRun === false) return false;
+  if (instance && instance.dryRun === true) return true;
+  return DRY_RUN_ENV;
+}
+
+// Dry-run execution context. fetchJira/fetchConfluence check this and short-
+// circuit. Only the FIRST write in a chain is captured — multi-write tools
+// (e.g. transition with intermediate steps) report just step 1 with a note.
+const DRY_RUN_ABORT = Symbol("jira-mcp.dry-run-abort");
+const _policyCtx = { dryRun: false, plan: null };
+
+function recordDryRunCall(call) {
+  if (_policyCtx.plan) _policyCtx.plan.push(call);
+  throw DRY_RUN_ABORT;
+}
+
+// ---- Audit log ----
+const AUDIT_LOG_PATH = path.join(
+  process.env.HOME || "/tmp",
+  ".config/jira-mcp/audit.log",
+);
+const AUDIT_LOG_MAX_BYTES = 10 * 1024 * 1024;
+const AUDIT_LOG_KEEP = 5;
+const SECRET_KEY_PATTERN =
+  /^(token|auth|authorization|password|secret|api[_-]?key|file[_-]?content)$/i;
+
+function scrubArgs(value) {
+  if (value == null) return value;
+  if (Array.isArray(value)) return value.map(scrubArgs);
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (SECRET_KEY_PATTERN.test(k)) {
+        out[k] = "[REDACTED]";
+      } else if (typeof v === "string" && v.length > 4000) {
+        out[k] = v.slice(0, 4000) + `…[truncated ${v.length - 4000} chars]`;
+      } else {
+        out[k] = scrubArgs(v);
+      }
+    }
+    return out;
+  }
+  return value;
+}
+
+function rotateAuditIfNeeded() {
+  try {
+    const stat = fs.statSync(AUDIT_LOG_PATH);
+    if (stat.size < AUDIT_LOG_MAX_BYTES) return;
+  } catch {
+    return; // file does not exist yet
+  }
+  // Shift audit.log.N → audit.log.N+1
+  for (let i = AUDIT_LOG_KEEP - 1; i >= 1; i--) {
+    const src = `${AUDIT_LOG_PATH}.${i}`;
+    const dst = `${AUDIT_LOG_PATH}.${i + 1}`;
+    try { if (fs.existsSync(src)) fs.renameSync(src, dst); } catch {}
+  }
+  try { fs.renameSync(AUDIT_LOG_PATH, `${AUDIT_LOG_PATH}.1`); } catch {}
+}
+
+function audit(entry) {
+  try {
+    if (auditConfig.enabled === false) return;
+    const auditDir = path.dirname(AUDIT_LOG_PATH);
+    if (!fs.existsSync(auditDir)) fs.mkdirSync(auditDir, { recursive: true });
+    rotateAuditIfNeeded();
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n";
+    fs.appendFileSync(AUDIT_LOG_PATH, line);
+  } catch {
+    // Audit failures must not block real writes.
+  }
+}
+
+// ---- Rate limiter (token buckets) ----
+let _clock = () => Date.now();
+function _setClockForTests(fn) { _clock = fn; }
+
+// Buckets are populated lazily. Defaults are conservative-but-not-annoying.
+// User can override via config.rateLimit = { enabled: bool, global: N, perInstance: N, destructive: N }.
+const DEFAULT_RL = { enabled: true, global: 60, perInstance: 30, destructive: 5 };
+let _rlConfig = { ...DEFAULT_RL };
+const _buckets = new Map();
+
+function _bucket(key, capacity) {
+  let b = _buckets.get(key);
+  if (!b) {
+    b = { tokens: capacity, lastRefill: _clock(), capacity };
+    _buckets.set(key, b);
+  }
+  return b;
+}
+
+function _refill(b, refillPerMin) {
+  const now = _clock();
+  const elapsed = now - b.lastRefill;
+  if (elapsed <= 0) return;
+  const refill = (elapsed / 60000) * refillPerMin;
+  b.tokens = Math.min(b.capacity, b.tokens + refill);
+  b.lastRefill = now;
+}
+
+function checkRateLimit(toolName, instance) {
+  if (_rlConfig.enabled === false) return { allowed: true };
+  const meta = TOOL_METADATA[toolName];
+  if (!meta || meta.op === "read") return { allowed: true };
+
+  const checks = [
+    { key: "global", capacity: _rlConfig.global },
+    { key: `instance:${instance.name}`, capacity: _rlConfig.perInstance },
+  ];
+  if (meta.op === "destructive") {
+    checks.push({ key: "destructive", capacity: _rlConfig.destructive });
+  }
+
+  for (const c of checks) {
+    const b = _bucket(c.key, c.capacity);
+    _refill(b, c.capacity);
+    if (b.tokens < 1) {
+      const retryAfter = Math.ceil(((1 - b.tokens) / c.capacity) * 60);
+      return { allowed: false, bucket: c.key, retryAfter };
+    }
+  }
+  // Consume from all relevant buckets atomically.
+  for (const c of checks) {
+    const b = _bucket(c.key, c.capacity);
+    b.tokens -= 1;
+  }
+  return { allowed: true };
+}
+
+function _resetBucketsForTests() {
+  _buckets.clear();
+  _rlConfig = { ...DEFAULT_RL };
+}
+
+// Pick up user overrides from config.
+let auditConfig = { enabled: true };
+if (rawConfig.audit && typeof rawConfig.audit === "object") {
+  auditConfig = { ...auditConfig, ...rawConfig.audit };
+}
+if (rawConfig.rateLimit && typeof rawConfig.rateLimit === "object") {
+  _rlConfig = { ..._rlConfig, ...rawConfig.rateLimit };
+}
+
+// Target extractor for audit log.
+function extractTarget(args) {
+  if (!args || typeof args !== "object") return undefined;
+  return (
+    args.issueKey ||
+    args.pageId ||
+    args.spaceKey ||
+    args.commentId ||
+    args.boardId ||
+    args.attachmentId ||
+    args.accountId ||
+    undefined
+  );
+}
+
+// Resolve instance for policy purposes (must run BEFORE the dispatch handler).
+// Routing keys vary by tool — issueKey is most common but subtask uses
+// parentKey, link uses inwardIssueKey, create_ticket uses projectKey, and
+// Confluence tools route by spaceKey. If a tool genuinely targets a specific
+// instance via no key (e.g. jira_get_boards), it falls back to the default
+// instance — the user can still override with args.instance.
+function resolveInstanceForTool(toolName, args) {
+  if (!args) return defaultInstance;
+  if (args.instance) return getInstanceByName(args.instance);
+  const keyLike =
+    args.issueKey ||
+    args.parentKey ||
+    args.inwardIssueKey ||
+    args.outwardIssueKey;
+  if (keyLike) return getInstanceForKey(keyLike);
+  const projectLike = args.projectKey || args.spaceKey;
+  if (projectLike) return getInstanceForProject(projectLike);
+  return defaultInstance;
+}
+
 // ============ JIRA FUNCTIONS ============
 
 async function fetchJira(endpoint, options = {}, instance = defaultInstance) {
   const { method = "GET", body } = options;
+  if (_policyCtx.dryRun && method !== "GET" && method !== "HEAD") {
+    recordDryRunCall({ api: "jira", method, endpoint, body, instance: instance.name });
+  }
   const headers = {
     Authorization: `Basic ${instance.auth}`,
     Accept: "application/json",
@@ -162,6 +484,9 @@ async function fetchJira(endpoint, options = {}, instance = defaultInstance) {
 
 async function fetchJiraAgile(endpoint, options = {}, instance = defaultInstance) {
   const { method = "GET", body } = options;
+  if (_policyCtx.dryRun && method !== "GET" && method !== "HEAD") {
+    recordDryRunCall({ api: "jira-agile", method, endpoint, body, instance: instance.name });
+  }
   const headers = {
     Authorization: `Basic ${instance.auth}`,
     Accept: "application/json",
@@ -307,6 +632,15 @@ function getConfluenceBaseUrl(instance) {
 
 async function fetchConfluence(endpoint, options = {}, instance = defaultInstance) {
   const { method = "GET", body, rawBody, contentType, extraHeaders } = options;
+  if (_policyCtx.dryRun && method !== "GET" && method !== "HEAD") {
+    recordDryRunCall({
+      api: "confluence",
+      method,
+      endpoint,
+      body: body !== undefined ? body : rawBody !== undefined ? "<raw body>" : undefined,
+      instance: instance.name,
+    });
+  }
   const headers = {
     Authorization: `Basic ${instance.auth}`,
     Accept: "application/json",
@@ -435,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 (
@@ -642,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
@@ -754,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;
     }
 
@@ -792,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" });
@@ -1662,14 +2028,50 @@ 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 },
 );
 
-server.setRequestHandler(ListToolsRequestSchema, async () => {
+// Inject `dryRun` into the schema of any mutating tool so MCP clients with
+// strict schema validation accept it as a per-call argument.
+function _injectDryRunSchema(tool) {
+  const meta = TOOL_METADATA[tool.name];
+  if (!meta || meta.op === "read") return tool;
+  const schema = tool.inputSchema || {};
+  const props = schema.properties || {};
+  if (props.dryRun) return tool;
   return {
-    tools: [
+    ...tool,
+    inputSchema: {
+      ...schema,
+      properties: {
+        ...props,
+        dryRun: {
+          type: "boolean",
+          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 = [
       {
         name: "jira_get_myself",
         description:
@@ -1679,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: [],
@@ -1707,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"],
@@ -1733,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"],
@@ -1742,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: {
@@ -1750,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"],
@@ -1775,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"],
@@ -1787,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: {
@@ -1800,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"],
@@ -1827,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"],
@@ -1856,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"],
@@ -1917,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"],
@@ -1941,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"],
@@ -1971,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: [],
@@ -2063,7 +2474,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             instance: {
               type: "string",
-              description: "Instance name. Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: [],
@@ -2090,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",
@@ -2133,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"],
@@ -2156,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",
@@ -2177,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"],
@@ -2208,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"],
@@ -2231,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"],
@@ -2262,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"],
@@ -2277,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: [],
@@ -2296,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"],
@@ -2319,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"],
@@ -2346,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: [],
@@ -2369,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"],
@@ -2392,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"],
@@ -2423,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"],
@@ -2442,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"],
@@ -2473,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"],
@@ -2497,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"],
@@ -2520,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"],
@@ -2547,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: [],
@@ -2566,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"],
@@ -2581,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: [],
@@ -2600,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"],
@@ -2619,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"],
@@ -2634,7 +3047,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             instance: {
               type: "string",
-              description: "Instance name. Uses default instance if omitted.",
+              description: "Instance name (optional).",
             },
           },
           required: [],
@@ -2648,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"],
         },
@@ -2663,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"],
         },
@@ -2678,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"],
         },
@@ -2691,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"],
         },
@@ -2707,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"],
         },
@@ -2722,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: [],
         },
@@ -2736,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"],
         },
@@ -2750,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"],
         },
@@ -2764,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"],
         },
@@ -2778,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"],
         },
@@ -2793,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"],
         },
@@ -2809,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"],
         },
@@ -2825,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"],
         },
@@ -2837,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"],
         },
@@ -2849,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"],
         },
@@ -2862,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"],
         },
@@ -2875,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"],
         },
@@ -2888,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"],
         },
@@ -2905,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"],
         },
@@ -2919,19 +3332,153 @@ 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"],
         },
       },
-    ],
-  };
+    ];
+  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) {
+  const meta = TOOL_METADATA[name];
+  const inst = resolveInstanceForTool(name, args);
+
+  // 1. Scope check
+  const scopeResult = checkScope(name, inst);
+  if (!scopeResult.allowed) {
+    if (meta && meta.op !== "read") {
+      audit({
+        tool: name,
+        instance: inst.name,
+        target: extractTarget(args),
+        args: scrubArgs(args),
+        success: false,
+        deniedBy: "scope",
+        reason: scopeResult.reason,
+      });
+    }
+    return {
+      content: [{ type: "text", text: `Scope denied: ${scopeResult.reason}` }],
+      isError: true,
+    };
+  }
+
+  // 2. Resolve dry-run intent
+  const dryRun = resolveDryRun(name, args, inst);
+
+  // 3. Rate limit — real writes only (dry-runs do not consume quota)
+  if (!dryRun && meta && (meta.op === "write" || meta.op === "destructive")) {
+    const rl = checkRateLimit(name, inst);
+    if (!rl.allowed) {
+      audit({
+        tool: name,
+        instance: inst.name,
+        target: extractTarget(args),
+        args: scrubArgs(args),
+        success: false,
+        deniedBy: "rate-limit",
+        bucket: rl.bucket,
+        retryAfter: rl.retryAfter,
+      });
+      return {
+        content: [{
+          type: "text",
+          text: `Rate limit exceeded (bucket: ${rl.bucket}). Retry after ${rl.retryAfter}s.`,
+        }],
+        isError: true,
+      };
+    }
+  }
+
+  // 4. Execute under policy context
+  _policyCtx.dryRun = dryRun;
+  _policyCtx.plan = dryRun ? [] : null;
+  try {
+    const result = await handler();
+    if (meta && meta.op !== "read") {
+      audit({
+        tool: name,
+        instance: inst.name,
+        target: extractTarget(args),
+        args: scrubArgs(args),
+        dryRun,
+        success: true,
+      });
+    }
+    return result;
+  } catch (error) {
+    if (error === DRY_RUN_ABORT) {
+      const plan = _policyCtx.plan || [];
+      audit({
+        tool: name,
+        instance: inst.name,
+        target: extractTarget(args),
+        args: scrubArgs(args),
+        dryRun: true,
+        success: true,
+        status: "dry-run",
+        plan,
+      });
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            dryRun: true,
+            note: "Plan shows the first HTTP write only. Multi-step tools (e.g. jira_transition with intermediate steps) execute the remaining writes when run for real.",
+            plan,
+          }, null, 2),
+        }],
+      };
+    }
+    if (meta && meta.op !== "read") {
+      audit({
+        tool: name,
+        instance: inst.name,
+        target: extractTarget(args),
+        args: scrubArgs(args),
+        dryRun,
+        success: false,
+        error: error.message,
+      });
+    }
+    return {
+      content: [{ type: "text", text: `Error: ${error.message}` }],
+      isError: true,
+    };
+  } finally {
+    _policyCtx.dryRun = false;
+    _policyCtx.plan = null;
+  }
+}
+
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
 
-  try {
+  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);
       const result = await fetchJira("/myself", {}, inst);
@@ -3488,11 +4035,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
       }
 
-      // Save without the computed auth field
-      const toSave = { name: instName, email, token, baseUrl, projects };
+      // Save without the computed auth field. Preserve any safety/observability
+      // fields the user has configured on the existing instance (scopes, dryRun,
+      // confluenceBaseUrl) so they survive a re-run of jira_add_instance.
+      const savedIdx = savedConfig.instances.findIndex((i) => i.name === instName);
+      const prevSaved = savedIdx >= 0 ? savedConfig.instances[savedIdx] : {};
+      const toSave = {
+        ...prevSaved,
+        name: instName,
+        email,
+        token,
+        baseUrl,
+        projects,
+      };
       if (defaultTeam) toSave.defaultTeam = defaultTeam;
       if (Object.keys(projectTeams).length > 0) toSave.projectTeams = projectTeams;
-      const savedIdx = savedConfig.instances.findIndex((i) => i.name === instName);
       if (savedIdx >= 0) {
         savedConfig.instances[savedIdx] = toSave;
       } else {
@@ -3828,6 +4385,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         Buffer.from(footer),
       ]);
 
+      if (_policyCtx.dryRun) {
+        recordDryRunCall({
+          api: "jira",
+          method: "POST",
+          endpoint: `/issue/${args.issueKey}/attachments`,
+          body: `<multipart upload: ${fileName}, ${fileBuffer.length} bytes>`,
+          instance: inst.name,
+        });
+      }
+
       const response = await fetch(
         `${inst.baseUrl}/rest/api/3/issue/${args.issueKey}/attachments`,
         {
@@ -4718,6 +5285,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const bodyBuffer = Buffer.concat(parts);
 
       const url = `${getConfluenceBaseUrl(inst)}/rest/api/content/${encodeURIComponent(args.pageId)}/child/attachment`;
+      if (_policyCtx.dryRun) {
+        recordDryRunCall({
+          api: "confluence",
+          method: "POST",
+          endpoint: `/rest/api/content/${args.pageId}/child/attachment`,
+          body: `<multipart upload: ${fileName}, ${fileBuffer.length} bytes>`,
+          instance: inst.name,
+        });
+      }
       const response = await fetch(url, {
         method: "POST",
         headers: {
@@ -4755,12 +5331,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     } else {
       throw new Error(`Unknown tool: ${name}`);
     }
-  } catch (error) {
-    return {
-      content: [{ type: "text", text: `Error: ${error.message}` }],
-      isError: true,
-    };
-  }
+  });
 });
 
 async function main() {
@@ -4774,5 +5345,14 @@ if (require.main === module) {
 
 // Export for testing
 if (typeof module !== "undefined") {
-  module.exports = { buildCommentADF, parseInlineFormatting, autoLinkTextNodes, findJiraTicketKeys, resolveTeamId, fetchJiraTeams, listTeams, searchTeamsViaJql, fetchConfluence, getConfluenceBaseUrl, textToConfluenceStorage, htmlEscape };
+  module.exports = {
+    buildCommentADF, parseInlineFormatting, autoLinkTextNodes, findJiraTicketKeys,
+    resolveTeamId, fetchJiraTeams, listTeams, searchTeamsViaJql,
+    fetchConfluence, getConfluenceBaseUrl, textToConfluenceStorage, htmlEscape,
+    // Policy module exports
+    TOOL_METADATA, checkScope, resolveDryRun, scrubArgs, extractTarget,
+    checkRateLimit, _setClockForTests, _resetBucketsForTests,
+    resolveInstanceForTool, _injectDryRunSchema,
+    AUDIT_LOG_PATH,
+  };
 }