@rui.branco/jira-mcp 1.7.4 → 1.7.6

package/README.md

@@ -1,6 +1,6 @@
 # Jira MCP Server
 
-A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that brings Jira ticket context directly into Claude Code. Fetch complete ticket information including descriptions, comments, attachments, and linked Figma designs without leaving your development environment.
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that brings Jira ticket context directly into any MCP-compatible AI client — Claude Code, Codex CLI, Google's Antigravity (Gemini), Cursor, Windsurf, Zed, and others. Fetch complete ticket information including descriptions, comments, attachments, and linked Figma designs without leaving your development environment.
 
 ## Overview
 
@@ -9,7 +9,7 @@ When working on development tasks, context switching between Jira and your code
 - **Fetching complete ticket context** - Get descriptions, comments, status, and metadata instantly
 - **Downloading attachments** - Image attachments are downloaded and displayed inline
 - **Auto-fetching Figma designs** - Linked Figma URLs are automatically detected and exported as images
-- **Enabling natural queries** - Search tickets with JQL directly from Claude Code
+- **Enabling natural queries** - Search tickets with JQL directly from your AI client
 
 ## Features
 
@@ -27,20 +27,44 @@ When working on development tasks, context switching between Jira and your code
 ### Prerequisites
 
 - Node.js 18+
-- [Claude Code](https://claude.ai/code) CLI
+- An MCP-compatible AI client (see [Step 1](#step-1-register-with-your-mcp-client) below)
 - Jira Cloud account with API access
 
-### Step 1: Add to Claude Code
+### Step 1: Register with your MCP client
+
+Pick the snippet for your client. All of them launch the server over stdio.
+
+**Claude Code:**
 
 ```bash
 claude mcp add --transport stdio jira -- npx -y @rui.branco/jira-mcp
 ```
 
+**Codex CLI:** add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.jira]
+command = "npx"
+args = ["-y", "@rui.branco/jira-mcp"]
+```
+
+**Google Antigravity / Gemini CLI:** add to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "jira": { "command": "npx", "args": ["-y", "@rui.branco/jira-mcp"] }
+  }
+}
+```
+
+**Cursor, Windsurf, Zed, Cline, Continue, etc.:** add the same `command`/`args` pair to whatever JSON config that client uses for MCP servers (the exact path varies, but the shape is standard across clients).
+
 ### Step 2: Get Your Jira API Token
 
 1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
 2. Click **"Create API token"**
-3. Enter a label (e.g., "Claude Code MCP")
+3. Enter a label (e.g., "jira-mcp")
 4. Click **"Create"**
 5. Copy the token (you won't be able to see it again)
 
@@ -66,7 +90,7 @@ npx @rui.branco/jira-mcp setup
 
 ### Step 4: Verify
 
-Restart Claude Code and run `/mcp` to verify the server is connected.
+Restart your AI client and check its MCP status (e.g. `/mcp` in Claude Code, `mcp` in Codex CLI, or the equivalent panel in your client) to verify the server is connected.
 
 ### Alternative: Manual Installation
 
@@ -78,7 +102,7 @@ cd ~/.config/jira-mcp && npm install
 node setup.js
 ```
 
-Then add to Claude Code:
+Then register the local entry point with your MCP client (replace the `npx -y @rui.branco/jira-mcp` command from Step 1 with `node $HOME/.config/jira-mcp/index.js`). Example for Claude Code:
 
 ```bash
 claude mcp add --transport stdio jira -- node $HOME/.config/jira-mcp/index.js
@@ -146,11 +170,11 @@ This MCP automatically detects Figma URLs in ticket descriptions and comments. W
 - Figma links are automatically fetched
 - Large frames are split into sections for better readability
 - Images are exported at 2x scale for clarity
-- All images are displayed inline in Claude Code
+- All images are displayed inline in clients that support image content blocks (Claude Code, Codex, Antigravity, etc.)
 
 To enable Figma integration:
 1. Install and configure [figma-mcp](https://github.com/rui-branco/figma-mcp)
-2. Restart Claude Code
+2. Restart your AI client
 3. Figma links will be auto-fetched when you get a ticket
 
 ## API Reference
@@ -230,11 +254,92 @@ The server provides clear error messages:
 - Tokens are never logged or transmitted except to Jira/Figma APIs
 - Attachments are downloaded to `~/.config/jira-mcp/attachments/`
 
+## Safety & Observability
+
+Four opt-in controls limit what an agent can do without your approval and give you a trail when something goes wrong. All four are off by default for existing installs — drop the relevant config block into `~/.config/jira-mcp/config.json` to turn them on.
+
+### Per-tool scopes
+
+Restrict which tools each instance can call. Useful for "this Atlassian instance is read-only" or "this one only allows comments".
+
+```json
+{
+  "instances": [
+    {
+      "name": "prod",
+      "email": "you@company.com",
+      "token": "...",
+      "baseUrl": "https://company.atlassian.net",
+      "scopes": { "preset": "read-only" }
+    },
+    {
+      "name": "sandbox",
+      "email": "you@company.com",
+      "token": "...",
+      "baseUrl": "https://sandbox.atlassian.net",
+      "scopes": { "preset": "no-destructive", "deny": ["jira_remove_attachment"] }
+    }
+  ]
+}
+```
+
+Presets: `read-only`, `comments-only`, `no-destructive`, `unrestricted`. You can combine a preset with `allow: [...]` and `deny: [...]` — deny wins. If `scopes` is present, an unknown tool name fails closed. If `scopes` is omitted, the instance behaves as before (no restrictions).
+
+### Dry-run mode
+
+For any mutating tool call, return the HTTP request that *would* be sent without actually calling Atlassian. Useful for previewing what an agent is about to do.
+
+Three layers of precedence (most-specific wins):
+
+1. **Per call:** pass `dryRun: true` to any mutating tool.
+2. **Per instance:** add `"dryRun": true` to an instance in `config.json`.
+3. **Environment:** export `JIRA_MCP_DRY_RUN=1` before launching your AI client.
+
+Read tools ignore the flag. The response looks like:
+
+```json
+{
+  "dryRun": true,
+  "plan": [{ "api": "jira", "method": "POST", "endpoint": "/issue/PROJ-1/comment", "body": { ... } }]
+}
+```
+
+For multi-step tools (e.g. `jira_transition` with intermediate statuses) only the first write is captured.
+
+### Audit log
+
+Every write attempt — successful, failed, denied by scope, denied by rate limit, or dry-run — is appended as a JSON line to `~/.config/jira-mcp/audit.log`. Token-like fields (`token`, `authorization`, `password`, `apiKey`, `fileContent`, etc.) are redacted before they hit disk. Rotates at 10 MB, keeps 5 historical files.
+
+Disable with `"audit": { "enabled": false }` at the top level of `config.json`.
+
+### Rate limiting
+
+Layered in-memory token buckets prevent runaway loops. Defaults:
+
+- **global:** 60 writes/minute
+- **per-instance:** 30 writes/minute
+- **destructive tools** (`*_delete_*`, `jira_remove_*`, `confluence_delete_*`): 5/minute
+
+On limit hit the tool call fails immediately with a `Rate limit exceeded` error — no sleeping, no queueing. Reads bypass the limiter entirely. Dry-runs don't consume tokens.
+
+Override or disable in `config.json`:
+
+```json
+{
+  "rateLimit": {
+    "enabled": true,
+    "global": 120,
+    "perInstance": 60,
+    "destructive": 10
+  }
+}
+```
+
 ## License
 
 MIT
 
 ## Related
 
-- [figma-mcp](https://github.com/rui-branco/figma-mcp) - Figma MCP server for Claude Code
+- [figma-mcp](https://github.com/rui-branco/figma-mcp) - Figma MCP server (works with any MCP-compatible AI client)
 - [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification

package/index.js

@@ -134,10 +134,321 @@ 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 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 +473,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 +621,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",
@@ -1667,9 +1990,31 @@ const server = new Server(
   { capabilities: { tools: {} } },
 );
 
-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: "If true, return the HTTP request that would be sent (method, endpoint, body) without calling Atlassian. Multi-step tools only show the first write.",
+        },
+      },
+    },
+  };
+}
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  const rawTools = [
       {
         name: "jira_get_myself",
         description:
@@ -2924,14 +3269,126 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ["pageId", "filename"],
         },
       },
-    ],
-  };
+    ];
+  return { tools: rawTools.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 {
+  return runWithPolicy(name, args, async () => {
     if (name === "jira_get_myself") {
       const inst = getInstanceByName(args.instance);
       const result = await fetchJira("/myself", {}, inst);
@@ -3488,11 +3945,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 {
@@ -3721,20 +4188,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (args.labels) {
         fields.labels = args.labels;
       }
-      let teamWarning = "";
-      if (args.team) {
-        fields.customfield_10001 = await resolveTeamId(args.team, inst);
-      } else {
-        // Inherit team from parent ticket
-        const parentIssue = await fetchJira(
-          `/issue/${args.parentKey}?fields=customfield_10001`, {}, inst,
-        );
-        if (parentIssue.fields?.customfield_10001) {
-          fields.customfield_10001 = parentIssue.fields.customfield_10001;
-        } else if (inst.defaultTeam && inst.defaultTeam !== "none") {
-          teamWarning = `\n\nNote: Parent ${args.parentKey} has no team assigned. Instance default team is "${inst.defaultTeam.name}". Use team parameter to assign it.`;
-        }
-      }
+      // Subtasks inherit team from their parent in Jira — never send customfield_10001
 
       const result = await fetchJira("/issue", { method: "POST", body: { fields } }, inst);
       const newKey = result.key;
@@ -3742,7 +4196,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         content: [
           {
             type: "text",
-            text: `Created subtask ${newKey} under ${args.parentKey}: ${args.summary}\nURL: ${inst.baseUrl}/browse/${newKey}${teamWarning}`,
+            text: `Created subtask ${newKey} under ${args.parentKey}: ${args.summary}\nURL: ${inst.baseUrl}/browse/${newKey}`,
           },
         ],
       };
@@ -3841,6 +4295,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`,
         {
@@ -4731,6 +5195,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: {
@@ -4768,12 +5241,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() {
@@ -4787,5 +5255,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,
+  };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rui.branco/jira-mcp",
-  "version": "1.7.4",
-  "description": "Jira MCP server for Claude Code - fetch tickets, search with JQL, update tickets, manage comments, change status, and get Figma designs",
+  "version": "1.7.6",
+  "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": {
     "jira-mcp": "./index.js"