@rui.branco/jira-mcp 1.0.0

package/README.md

@@ -0,0 +1,183 @@
+# 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.
+
+## Overview
+
+When working on development tasks, context switching between Jira and your code editor breaks flow and wastes time. This MCP server solves that by:
+
+- **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
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| Full Ticket Details | Summary, description, status, priority, assignee, reporter, sprint, parent |
+| Comments | All comments with author and timestamp |
+| Attachments | Auto-download image attachments (PNG, JPG, GIF, WebP) |
+| Linked Issues | View related tickets and their relationships |
+| Figma Integration | Auto-detect and export Figma designs linked in tickets |
+| JQL Search | Search across your Jira instance with powerful queries |
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+
+- [Claude Code](https://claude.ai/code) CLI
+- Jira Cloud account with API access
+
+### Quick Setup
+
+```bash
+# Clone to ~/.config (recommended)
+cd ~/.config
+git clone https://github.com/rui-branco/jira-mcp.git
+cd jira-mcp
+
+# Install dependencies
+npm install
+
+# Run interactive setup
+node setup.js
+```
+
+The setup will prompt for:
+1. **Jira email** - Your Atlassian account email
+2. **API token** - Generate at [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+3. **Base URL** - Your Jira instance (e.g., `https://company.atlassian.net`)
+
+### Alternative: Command-Line Setup
+
+```bash
+node setup.js "your@email.com" "YOUR_API_TOKEN" "https://company.atlassian.net"
+```
+
+### Claude Code Configuration
+
+Add to your `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["~/.config/jira-mcp/index.js"]
+    }
+  }
+}
+```
+
+> **Note:** If you cloned to a different location, update the path accordingly.
+
+Restart Claude Code to load the MCP server.
+
+## Usage
+
+### Fetch a Ticket
+
+```
+> Get ticket PROJ-123
+
+# Returns full ticket with description, comments, attachments, and Figma designs
+```
+
+### Search Tickets
+
+```
+> Search for my open tickets
+
+# Uses JQL: assignee = currentUser() AND status != Done
+```
+
+### Example Output
+
+```
+# PROJ-123: Implement user authentication
+
+Status: In Progress | Type: Story | Priority: High
+Assignee: John Doe | Reporter: Jane Smith
+
+## Description
+Implement OAuth2 authentication flow...
+
+## Comments (2)
+### Jane Smith - Jan 15, 2025
+Please ensure we support Google SSO...
+
+## Attachments (1)
+- mockup.png (image/png, 245KB)
+  [Image displayed inline]
+
+## Figma Designs (1)
+### Auth Flow Design - Login Screen
+- Exported 3 image(s):
+  - Login Form: ~/.config/figma-mcp/exports/...
+  - Error States: ~/.config/figma-mcp/exports/...
+  - Success State: ~/.config/figma-mcp/exports/...
+```
+
+## Figma Integration
+
+This MCP automatically detects Figma URLs in ticket descriptions and comments. When [figma-mcp](https://github.com/rui-branco/figma-mcp) is configured:
+
+- 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
+
+To enable Figma integration:
+1. Install and configure [figma-mcp](https://github.com/rui-branco/figma-mcp)
+2. Restart Claude Code
+3. Figma links will be auto-fetched when you get a ticket
+
+## API Reference
+
+### Tools
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `jira_get_ticket` | Fetch a ticket by key | `issueKey` (required), `downloadImages`, `fetchFigma` |
+| `jira_search` | Search with JQL | `jql` (required), `maxResults` |
+
+### Configuration
+
+Config stored at `~/.config/jira-mcp/config.json`:
+
+```json
+{
+  "email": "your@email.com",
+  "token": "YOUR_API_TOKEN",
+  "baseUrl": "https://company.atlassian.net"
+}
+```
+
+## Error Handling
+
+The server provides clear error messages:
+
+| Error | Meaning |
+|-------|---------|
+| `Figma API rate limit exceeded` | Too many Figma requests, wait a few minutes |
+| `Figma access denied` | Check Figma token or file permissions |
+| `Figma not configured` | Install and configure figma-mcp |
+
+## Security
+
+- API tokens are stored locally in `~/.config/jira-mcp/config.json`
+- Config files are excluded from git via `.gitignore`
+- Tokens are never logged or transmitted except to Jira/Figma APIs
+- Attachments are downloaded to `~/.config/jira-mcp/attachments/`
+
+## License
+
+MIT
+
+## Related
+
+- [figma-mcp](https://github.com/rui-branco/figma-mcp) - Figma MCP server for Claude Code
+- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification

package/index.js

@@ -0,0 +1,807 @@
+#!/usr/bin/env node
+
+const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} = require("@modelcontextprotocol/sdk/types.js");
+const fs = require("fs");
+const path = require("path");
+const fetch = require("node-fetch");
+
+// Load Jira config
+const jiraConfigPath = path.join(process.env.HOME, ".config/jira-mcp/config.json");
+const jiraConfig = JSON.parse(fs.readFileSync(jiraConfigPath, "utf8"));
+const auth = Buffer.from(`${jiraConfig.email}:${jiraConfig.token}`).toString("base64");
+
+// Load Figma config (optional)
+let figmaConfig = null;
+const figmaConfigPath = path.join(process.env.HOME, ".config/figma-mcp/config.json");
+try {
+  if (fs.existsSync(figmaConfigPath)) {
+    figmaConfig = JSON.parse(fs.readFileSync(figmaConfigPath, "utf8"));
+  }
+} catch (e) {
+  // Figma not configured, that's ok
+}
+
+// Directories
+const attachmentDir = path.join(process.env.HOME, ".config/jira-mcp/attachments");
+const figmaExportsDir = path.join(process.env.HOME, ".config/figma-mcp/exports");
+
+if (!fs.existsSync(attachmentDir)) {
+  fs.mkdirSync(attachmentDir, { recursive: true });
+}
+
+// ============ JIRA FUNCTIONS ============
+
+async function fetchJira(endpoint) {
+  const response = await fetch(`${jiraConfig.baseUrl}/rest/api/3${endpoint}`, {
+    headers: {
+      Authorization: `Basic ${auth}`,
+      Accept: "application/json",
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`Jira API error: ${response.status} ${response.statusText}`);
+  }
+  return response.json();
+}
+
+async function downloadAttachment(url, filename, issueKey) {
+  const issueDir = path.join(attachmentDir, issueKey);
+  if (!fs.existsSync(issueDir)) {
+    fs.mkdirSync(issueDir, { recursive: true });
+  }
+
+  const localPath = path.join(issueDir, filename);
+
+  if (fs.existsSync(localPath)) {
+    return localPath;
+  }
+
+  const response = await fetch(url, {
+    headers: { Authorization: `Basic ${auth}` },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to download ${filename}: ${response.status}`);
+  }
+
+  const buffer = await response.buffer();
+  fs.writeFileSync(localPath, buffer);
+
+  return localPath;
+}
+
+function extractText(content, urls = []) {
+  if (!content) return { text: "", urls };
+  if (typeof content === "string") return { text: content, urls };
+
+  let text = "";
+  if (content.content) {
+    for (const node of content.content) {
+      if (node.type === "text") {
+        text += node.text || "";
+        // Check for link marks
+        if (node.marks) {
+          for (const mark of node.marks) {
+            if (mark.type === "link" && mark.attrs?.href) {
+              urls.push(mark.attrs.href);
+            }
+          }
+        }
+      } else if (node.type === "paragraph") {
+        const result = extractText(node, urls);
+        text += result.text + "\n";
+        urls = result.urls;
+      } else if (node.type === "hardBreak") {
+        text += "\n";
+      } else if (node.type === "mention") {
+        text += `@${node.attrs?.text || "user"}`;
+      } else if (node.type === "mediaGroup" || node.type === "mediaSingle") {
+        text += "[image attachment]\n";
+      } else if (node.type === "inlineCard" || node.type === "blockCard" || node.type === "embedCard") {
+        // Smart links / embeds - extract URL
+        const url = node.attrs?.url;
+        if (url) {
+          text += url + "\n";
+          urls.push(url);
+        }
+      } else if (node.content) {
+        const result = extractText(node, urls);
+        text += result.text;
+        urls = result.urls;
+      }
+    }
+  }
+  return { text, urls };
+}
+
+// Wrapper for backward compatibility
+function extractTextSimple(content) {
+  const result = extractText(content, []);
+  return result.text;
+}
+
+// ============ JIRA URL DETECTION ============
+
+function findJiraTicketKeys(text, currentKey = null) {
+  if (!text) return [];
+
+  // Match Jira URLs like https://company.atlassian.net/browse/PROJ-123
+  const urlRegex = /https?:\/\/[^\s]+\/browse\/([A-Z][A-Z0-9]+-\d+)/g;
+  // Match ticket keys directly like PROJ-123
+  const keyRegex = /\b([A-Z][A-Z0-9]+-\d+)\b/g;
+
+  const keys = new Set();
+  let match;
+
+  while ((match = urlRegex.exec(text)) !== null) {
+    if (match[1] !== currentKey) {
+      keys.add(match[1]);
+    }
+  }
+
+  while ((match = keyRegex.exec(text)) !== null) {
+    if (match[1] !== currentKey) {
+      keys.add(match[1]);
+    }
+  }
+
+  return [...keys];
+}
+
+// ============ FIGMA FUNCTIONS ============
+
+function findFigmaUrls(text) {
+  if (!text) return [];
+  // Match Figma URLs
+  const regex = /https:\/\/(?:www\.)?figma\.com\/(?:file|design|proto)\/([a-zA-Z0-9]+)\/[^\s)>\]"']*/g;
+  const matches = [];
+  let match;
+  while ((match = regex.exec(text)) !== null) {
+    matches.push(match[0]);
+  }
+  return [...new Set(matches)]; // dedupe
+}
+
+function parseFigmaUrl(url) {
+  const urlObj = new URL(url);
+  const pathParts = urlObj.pathname.split("/");
+
+  let fileKey = null;
+  for (let i = 0; i < pathParts.length; i++) {
+    if (pathParts[i] === "file" || pathParts[i] === "design" || pathParts[i] === "proto") {
+      fileKey = pathParts[i + 1];
+      break;
+    }
+  }
+
+  if (!fileKey) return null;
+
+  // Get node ID and convert from hyphen to colon format
+  const rawNodeId = urlObj.searchParams.get("node-id");
+  const nodeId = rawNodeId ? rawNodeId.replace(/-/g, ":") : null;
+
+  return { fileKey, nodeId };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function figmaFetchWithRetry(url, options = {}, { maxRetries = 3, maxWaitSec = 30 } = {}) {
+  let attempts = 0;
+
+  while (true) {
+    const response = await fetch(url, {
+      ...options,
+      headers: { ...options.headers, "X-Figma-Token": figmaConfig.token },
+    });
+
+    if (response.ok) {
+      return response;
+    }
+
+    if (response.status === 429) {
+      const retryAfterSec = Number(response.headers.get("retry-after")) || 60;
+
+      // Don't retry if wait is too long (monthly limit) or too many attempts
+      if (retryAfterSec > maxWaitSec || attempts++ >= maxRetries) {
+        const waitTime = retryAfterSec > 3600
+          ? `${Math.round(retryAfterSec / 3600)} hours (monthly limit reached)`
+          : `${retryAfterSec} seconds`;
+        return { rateLimited: true, retryAfter: waitTime };
+      }
+
+      await sleep(retryAfterSec * 1000);
+      continue;
+    }
+
+    return response;
+  }
+}
+
+async function fetchFigmaDesign(url) {
+  if (!figmaConfig) {
+    return { error: "Figma not configured. Run: node ~/.config/figma-mcp/setup.js" };
+  }
+
+  const parsed = parseFigmaUrl(url);
+  if (!parsed) {
+    return { error: "Invalid Figma URL" };
+  }
+
+  const { fileKey, nodeId } = parsed;
+
+  try {
+    // Get file info
+    const fileRes = await figmaFetchWithRetry(`https://api.figma.com/v1/files/${fileKey}?depth=1`);
+
+    if (fileRes.rateLimited) {
+      return { error: `Figma API rate limit exceeded. Try again in ${fileRes.retryAfter} seconds.` };
+    }
+    if (!fileRes.ok) {
+      if (fileRes.status === 403) {
+        return { error: "Figma access denied. Check your token or file permissions." };
+      } else if (fileRes.status === 404) {
+        return { error: "Figma file not found. Check the URL." };
+      }
+      return { error: `Figma API error: ${fileRes.status}` };
+    }
+    const fileData = await fileRes.json();
+
+    let result = {
+      name: fileData.name,
+      lastModified: fileData.lastModified,
+      url: url,
+      nodeId: nodeId,
+      nodeName: null,
+      images: [], // Changed to array for multiple images
+    };
+
+    if (!fs.existsSync(figmaExportsDir)) {
+      fs.mkdirSync(figmaExportsDir, { recursive: true });
+    }
+
+    // If specific node, get its info and export images
+    if (nodeId) {
+      // Get node info with depth=2 to see children
+      const nodeRes = await figmaFetchWithRetry(
+        `https://api.figma.com/v1/files/${fileKey}/nodes?ids=${encodeURIComponent(nodeId)}&depth=2`
+      );
+
+      if (nodeRes.ok) {
+        const nodeData = await nodeRes.json();
+        const node = nodeData.nodes && nodeData.nodes[nodeId];
+
+        if (node && node.document) {
+          const doc = node.document;
+          result.nodeName = doc.name;
+
+          // Check if it's a large frame with children
+          const bb = doc.absoluteBoundingBox;
+          const isLarge = bb && (bb.width > 1500 || bb.height > 2000);
+          const exportableChildren = [];
+
+          if (doc.children) {
+            for (const child of doc.children) {
+              const isExportable = ["FRAME", "COMPONENT", "GROUP", "SECTION"].includes(child.type);
+              const cbb = child.absoluteBoundingBox;
+              const hasSize = cbb && cbb.width >= 100 && cbb.height >= 100;
+              if (isExportable && hasSize) {
+                exportableChildren.push({ id: child.id, name: child.name });
+              }
+            }
+          }
+
+          // Export children if large frame, otherwise export whole frame
+          if (isLarge && exportableChildren.length > 0) {
+            const childIds = exportableChildren.slice(0, 8).map(c => c.id);
+            const idsParam = childIds.join(",");
+
+            const imgRes = await figmaFetchWithRetry(
+              `https://api.figma.com/v1/images/${fileKey}?ids=${encodeURIComponent(idsParam)}&format=png&scale=2`
+            );
+
+            if (imgRes.ok) {
+              const imgData = await imgRes.json();
+              for (const childId of childIds) {
+                const imageUrl = imgData.images && imgData.images[childId];
+                if (imageUrl) {
+                  try {
+                    const downloadRes = await fetch(imageUrl);
+                    if (downloadRes.ok) {
+                      const buffer = await downloadRes.buffer();
+                      const childInfo = exportableChildren.find(c => c.id === childId);
+                      const sanitizedId = childId.replace(/[^a-zA-Z0-9-]/g, "_");
+                      const filename = `${fileKey}_${sanitizedId}.png`;
+                      const imagePath = path.join(figmaExportsDir, filename);
+                      fs.writeFileSync(imagePath, buffer);
+                      result.images.push({
+                        buffer,
+                        path: imagePath,
+                        name: childInfo?.name || childId
+                      });
+                    }
+                  } catch (e) { /* skip */ }
+                }
+              }
+            }
+          } else {
+            // Export whole frame
+            const imgRes = await figmaFetchWithRetry(
+              `https://api.figma.com/v1/images/${fileKey}?ids=${encodeURIComponent(nodeId)}&format=png&scale=2`
+            );
+
+            if (imgRes.ok) {
+              const imgData = await imgRes.json();
+              const imageUrl = imgData.images && imgData.images[nodeId];
+              if (imageUrl) {
+                const downloadRes = await fetch(imageUrl);
+                if (downloadRes.ok) {
+                  const buffer = await downloadRes.buffer();
+                  const sanitizedId = nodeId.replace(/[^a-zA-Z0-9-]/g, "_");
+                  const filename = `${fileKey}_${sanitizedId}.png`;
+                  const imagePath = path.join(figmaExportsDir, filename);
+                  fs.writeFileSync(imagePath, buffer);
+                  result.images.push({ buffer, path: imagePath, name: doc.name });
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
+    return result;
+  } catch (e) {
+    return { error: `Figma fetch failed: ${e.message}` };
+  }
+}
+
+// ============ MAIN TICKET FUNCTION ============
+
+async function getTicket(issueKey, downloadImages = true, fetchFigma = true) {
+  const issue = await fetchJira(`/issue/${issueKey}?expand=renderedFields`);
+  const fields = issue.fields;
+
+  let output = `# ${issueKey}: ${fields.summary}\n\n`;
+  output += `**Status:** ${fields.status?.name || "Unknown"}\n`;
+  output += `**Type:** ${fields.issuetype?.name || "Unknown"}\n`;
+  output += `**Priority:** ${fields.priority?.name || "None"}\n`;
+  output += `**Assignee:** ${fields.assignee?.displayName || "Unassigned"}\n`;
+  output += `**Reporter:** ${fields.reporter?.displayName || "Unknown"}\n`;
+
+  if (fields.sprint) {
+    output += `**Sprint:** ${fields.sprint.name}\n`;
+  }
+
+  if (fields.parent) {
+    output += `**Parent:** ${fields.parent.key} - ${fields.parent.fields?.summary || ""}\n`;
+  }
+
+  // Subtasks
+  if (fields.subtasks?.length > 0) {
+    output += `**Subtasks:** ${fields.subtasks.length}\n`;
+  }
+
+  // Extract description text and embedded URLs
+  const descResult = extractText(fields.description, []);
+  output += `\n## Description\n\n`;
+  output += descResult.text || "_No description_";
+  output += "\n";
+
+  // Collect all URLs found in the ticket
+  let allUrls = [...descResult.urls];
+  let allText = descResult.text;
+
+  // Fetch FULL parent ticket details
+  if (fields.parent) {
+    output += `\n## Parent Ticket: ${fields.parent.key}\n\n`;
+    try {
+      const parentIssue = await fetchJira(`/issue/${fields.parent.key}?expand=renderedFields`);
+      const pf = parentIssue.fields;
+
+      output += `**${pf.summary}**\n`;
+      output += `Status: ${pf.status?.name || "Unknown"} | `;
+      output += `Type: ${pf.issuetype?.name || "Unknown"} | `;
+      output += `Priority: ${pf.priority?.name || "None"}\n`;
+      output += `Assignee: ${pf.assignee?.displayName || "Unassigned"}\n\n`;
+
+      // Full description
+      const parentDesc = extractText(pf.description, []);
+      if (parentDesc.text && parentDesc.text.trim()) {
+        output += `### Description\n${parentDesc.text}\n`;
+        allText += " " + parentDesc.text;
+        allUrls = allUrls.concat(parentDesc.urls);
+      }
+
+      // Parent comments
+      if (pf.comment?.comments?.length > 0) {
+        output += `\n### Comments (${pf.comment.comments.length})\n`;
+        for (const comment of pf.comment.comments) {
+          const author = comment.author?.displayName || "Unknown";
+          const created = new Date(comment.created).toLocaleString();
+          const commentText = extractText(comment.body, []);
+          output += `**${author}** - ${created}\n`;
+          output += `${commentText.text}\n\n`;
+          allText += " " + commentText.text;
+        }
+      }
+
+      output += "\n---\n\n";
+    } catch (e) {
+      output += `_Could not fetch parent details: ${e.message}_\n\n`;
+    }
+  }
+
+  // Get comments
+  if (fields.comment?.comments?.length > 0) {
+    output += `\n## Comments (${fields.comment.comments.length})\n\n`;
+    for (const comment of fields.comment.comments) {
+      const author = comment.author?.displayName || "Unknown";
+      const created = new Date(comment.created).toLocaleString();
+      const commentResult = extractText(comment.body, []);
+      output += `### ${author} - ${created}\n`;
+      output += commentResult.text + "\n\n";
+      allText += " " + commentResult.text;
+      allUrls = allUrls.concat(commentResult.urls);
+    }
+  }
+
+  // Get attachments
+  const downloadedImages = [];
+  if (fields.attachment?.length > 0) {
+    output += `\n## Attachments (${fields.attachment.length})\n\n`;
+    for (const att of fields.attachment) {
+      const isImage = att.mimeType?.startsWith("image/");
+      output += `- **${att.filename}** (${att.mimeType}, ${Math.round(att.size / 1024)}KB)\n`;
+
+      if (downloadImages && isImage) {
+        try {
+          const localPath = await downloadAttachment(att.content, att.filename, issueKey);
+          output += `  Local: ${localPath}\n`;
+          downloadedImages.push(localPath);
+        } catch (e) {
+          output += `  Download failed: ${e.message}\n`;
+        }
+      } else {
+        output += `  URL: ${att.content}\n`;
+      }
+    }
+  }
+
+  // Subtasks - fetch full details
+  if (fields.subtasks?.length > 0) {
+    output += `\n## Subtasks (${fields.subtasks.length})\n\n`;
+
+    for (const subtask of fields.subtasks) {
+      output += `### ${subtask.key}: ${subtask.fields?.summary || ""}\n`;
+      output += `Status: ${subtask.fields?.status?.name || "Unknown"} | `;
+      output += `Type: ${subtask.fields?.issuetype?.name || "Subtask"}\n`;
+
+      try {
+        const subtaskDetails = await fetchJira(`/issue/${subtask.key}`);
+        const sf = subtaskDetails.fields;
+
+        if (sf.assignee) {
+          output += `Assignee: ${sf.assignee.displayName}\n`;
+        }
+
+        const subtaskDesc = extractText(sf.description, []);
+        if (subtaskDesc.text && subtaskDesc.text.trim()) {
+          const desc = subtaskDesc.text.length > 300
+            ? subtaskDesc.text.substring(0, 300) + "..."
+            : subtaskDesc.text;
+          output += `\n${desc}\n`;
+        }
+        output += "\n";
+      } catch (e) {
+        output += "\n";
+      }
+    }
+  }
+
+  // Linked issues - fetch full details
+  if (fields.issuelinks?.length > 0) {
+    output += `\n## Linked Issues (${fields.issuelinks.length})\n\n`;
+
+    // Collect linked issue keys
+    const linkedIssues = [];
+    for (const link of fields.issuelinks) {
+      if (link.outwardIssue) {
+        linkedIssues.push({
+          key: link.outwardIssue.key,
+          relation: link.type.outward,
+          summary: link.outwardIssue.fields?.summary || ""
+        });
+      }
+      if (link.inwardIssue) {
+        linkedIssues.push({
+          key: link.inwardIssue.key,
+          relation: link.type.inward,
+          summary: link.inwardIssue.fields?.summary || ""
+        });
+      }
+    }
+
+    // Fetch full details for each linked issue
+    const maxLinkedToFetch = 10;
+    for (let i = 0; i < Math.min(linkedIssues.length, maxLinkedToFetch); i++) {
+      const linked = linkedIssues[i];
+      output += `### ${linked.relation}: ${linked.key}\n`;
+      output += `**${linked.summary}**\n\n`;
+
+      try {
+        const linkedIssue = await fetchJira(`/issue/${linked.key}?expand=renderedFields`);
+        const lf = linkedIssue.fields;
+
+        output += `Status: ${lf.status?.name || "Unknown"} | `;
+        output += `Type: ${lf.issuetype?.name || "Unknown"} | `;
+        output += `Priority: ${lf.priority?.name || "None"}\n`;
+        output += `Assignee: ${lf.assignee?.displayName || "Unassigned"}\n\n`;
+
+        // Get FULL description (no truncation)
+        const linkedDesc = extractText(lf.description, []);
+        if (linkedDesc.text && linkedDesc.text.trim()) {
+          output += `#### Description\n${linkedDesc.text}\n`;
+        }
+
+        // Get comments from linked ticket
+        if (lf.comment?.comments?.length > 0) {
+          output += `\n#### Comments (${lf.comment.comments.length})\n`;
+          for (const comment of lf.comment.comments) {
+            const author = comment.author?.displayName || "Unknown";
+            const created = new Date(comment.created).toLocaleString();
+            const commentText = extractText(comment.body, []);
+            output += `**${author}** - ${created}\n`;
+            output += `${commentText.text}\n\n`;
+          }
+        }
+
+        output += "\n---\n\n";
+      } catch (e) {
+        output += `_Could not fetch details: ${e.message}_\n\n`;
+      }
+    }
+
+    if (linkedIssues.length > maxLinkedToFetch) {
+      output += `\n_...and ${linkedIssues.length - maxLinkedToFetch} more linked issues_\n`;
+    }
+  }
+
+  // Find and fetch referenced Jira tickets from text (URLs and ticket keys)
+  const referencedKeys = findJiraTicketKeys(allText, issueKey);
+
+  // Exclude already fetched tickets (linked issues, subtasks, parent)
+  const alreadyFetched = new Set();
+  alreadyFetched.add(issueKey);
+  if (fields.parent) alreadyFetched.add(fields.parent.key);
+  if (fields.subtasks) fields.subtasks.forEach(s => alreadyFetched.add(s.key));
+  if (fields.issuelinks) {
+    fields.issuelinks.forEach(link => {
+      if (link.outwardIssue) alreadyFetched.add(link.outwardIssue.key);
+      if (link.inwardIssue) alreadyFetched.add(link.inwardIssue.key);
+    });
+  }
+
+  const ticketsToFetch = referencedKeys.filter(key => !alreadyFetched.has(key));
+
+  if (ticketsToFetch.length > 0) {
+    output += `\n## Referenced Tickets (${ticketsToFetch.length})\n\n`;
+    output += `_Auto-detected from description/comments_\n\n`;
+
+    const maxReferencedToFetch = 10;
+    for (let i = 0; i < Math.min(ticketsToFetch.length, maxReferencedToFetch); i++) {
+      const refKey = ticketsToFetch[i];
+
+      try {
+        const refIssue = await fetchJira(`/issue/${refKey}?expand=renderedFields`);
+        const rf = refIssue.fields;
+
+        output += `### ${refKey}: ${rf.summary || ""}\n`;
+        output += `Status: ${rf.status?.name || "Unknown"} | `;
+        output += `Type: ${rf.issuetype?.name || "Unknown"} | `;
+        output += `Priority: ${rf.priority?.name || "None"}\n`;
+        output += `Assignee: ${rf.assignee?.displayName || "Unassigned"}\n\n`;
+
+        // Get FULL description (no truncation)
+        const refDesc = extractText(rf.description, []);
+        if (refDesc.text && refDesc.text.trim()) {
+          output += `#### Description\n${refDesc.text}\n`;
+        }
+
+        // Get comments from referenced ticket
+        if (rf.comment?.comments?.length > 0) {
+          output += `\n#### Comments (${rf.comment.comments.length})\n`;
+          for (const comment of rf.comment.comments) {
+            const author = comment.author?.displayName || "Unknown";
+            const created = new Date(comment.created).toLocaleString();
+            const commentText = extractText(comment.body, []);
+            output += `**${author}** - ${created}\n`;
+            output += `${commentText.text}\n\n`;
+          }
+        }
+
+        // Check for Figma links in referenced ticket
+        const refFigmaUrls = findFigmaUrls(refDesc.text);
+        if (refFigmaUrls.length > 0) {
+          output += `**Figma:** ${refFigmaUrls.join(", ")}\n`;
+          allText += " " + refDesc.text;
+        }
+
+        output += "\n---\n\n";
+      } catch (e) {
+        output += `### ${refKey}\n_Could not fetch: ${e.message}_\n\n`;
+      }
+    }
+
+    if (ticketsToFetch.length > maxReferencedToFetch) {
+      output += `_...and ${ticketsToFetch.length - maxReferencedToFetch} more referenced tickets_\n`;
+    }
+  }
+
+  // Find and fetch Figma designs
+  const figmaDesigns = [];
+  if (fetchFigma && figmaConfig) {
+    // Combine URLs from regex search AND embedded links
+    const textUrls = findFigmaUrls(allText);
+    const embeddedFigmaUrls = allUrls.filter(u => u && u.includes("figma.com"));
+    const allFigmaUrls = [...new Set([...textUrls, ...embeddedFigmaUrls])]; // dedupe
+
+    if (allFigmaUrls.length > 0) {
+      output += `\n## Figma Designs (${allFigmaUrls.length})\n\n`;
+
+      for (const url of allFigmaUrls) {
+        const design = await fetchFigmaDesign(url);
+        if (design && design.error) {
+          output += `- ${url}\n`;
+          output += `  **Error:** ${design.error}\n\n`;
+        } else if (design && design.name) {
+          output += `### ${design.name}${design.nodeName ? ` - ${design.nodeName}` : ""}\n`;
+          output += `- URL: ${url}\n`;
+          output += `- Last Modified: ${design.lastModified}\n`;
+          if (design.images && design.images.length > 0) {
+            output += `- Exported ${design.images.length} image(s):\n`;
+            for (const img of design.images) {
+              output += `  - ${img.name}: ${img.path}\n`;
+            }
+            figmaDesigns.push(design);
+          }
+          output += "\n";
+        } else {
+          output += `- ${url} (could not fetch)\n\n`;
+        }
+      }
+    }
+  }
+
+  return { text: output, jiraImages: downloadedImages, figmaDesigns };
+}
+
+async function searchTickets(jql, maxResults = 10) {
+  const data = await fetchJira(`/search?jql=${encodeURIComponent(jql)}&maxResults=${maxResults}`);
+
+  let output = `# Search Results (${data.total} total, showing ${data.issues.length})\n\n`;
+
+  for (const issue of data.issues) {
+    const f = issue.fields;
+    output += `- **${issue.key}**: ${f.summary}\n`;
+    output += `  Status: ${f.status?.name} | Assignee: ${f.assignee?.displayName || "Unassigned"}\n\n`;
+  }
+
+  return output;
+}
+
+// ============ MCP SERVER ============
+
+const server = new Server(
+  { name: "jira-mcp", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "jira_get_ticket",
+        description: "Fetch a Jira ticket by its key (e.g., MODS-12115). Returns full details including description, comments, attachments, and linked Figma designs.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            issueKey: {
+              type: "string",
+              description: "The Jira issue key (e.g., MODS-12115)",
+            },
+            downloadImages: {
+              type: "boolean",
+              description: "Download image attachments (default: true)",
+            },
+            fetchFigma: {
+              type: "boolean",
+              description: "Fetch linked Figma designs and export images (default: true)",
+            },
+          },
+          required: ["issueKey"],
+        },
+      },
+      {
+        name: "jira_search",
+        description: "Search Jira tickets using JQL. Examples: 'project = MODS AND status = Open'",
+        inputSchema: {
+          type: "object",
+          properties: {
+            jql: { type: "string", description: "JQL query string" },
+            maxResults: { type: "number", description: "Max results (default 10)" },
+          },
+          required: ["jql"],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    if (name === "jira_get_ticket") {
+      const downloadImages = args.downloadImages !== false;
+      const fetchFigma = args.fetchFigma !== false;
+      const result = await getTicket(args.issueKey, downloadImages, fetchFigma);
+
+      const content = [{ type: "text", text: result.text }];
+
+      // Add Jira images
+      for (const imagePath of result.jiraImages) {
+        try {
+          const imageData = fs.readFileSync(imagePath);
+          const ext = path.extname(imagePath).toLowerCase();
+          const mimeType = ext === ".png" ? "image/png" :
+                          ext === ".gif" ? "image/gif" :
+                          ext === ".webp" ? "image/webp" : "image/jpeg";
+          content.push({
+            type: "image",
+            data: imageData.toString("base64"),
+            mimeType: mimeType,
+          });
+        } catch (e) { /* skip */ }
+      }
+
+      // Add Figma images (now supports multiple images per design)
+      for (const design of result.figmaDesigns) {
+        if (design.images && design.images.length > 0) {
+          for (const img of design.images) {
+            if (img.buffer) {
+              content.push({
+                type: "image",
+                data: img.buffer.toString("base64"),
+                mimeType: "image/png",
+              });
+            }
+          }
+        }
+      }
+
+      return { content };
+    } else if (name === "jira_search") {
+      const result = await searchTickets(args.jql, args.maxResults || 10);
+      return { content: [{ type: "text", text: result }] };
+    } else {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: `Error: ${error.message}` }],
+      isError: true,
+    };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@rui.branco/jira-mcp",
+  "version": "1.0.0",
+  "description": "Jira MCP server for Claude Code - fetch tickets, search with JQL, and get Figma designs",
+  "main": "index.js",
+  "bin": {
+    "jira-mcp": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "setup.js"
+  ],
+  "scripts": {
+    "setup": "node setup.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "jira",
+    "claude",
+    "claude-code",
+    "atlassian"
+  ],
+  "author": "Rui Branco",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rui-branco/jira-mcp.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "node-fetch": "^2.7.0"
+  }
+}

package/setup.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+const readline = require("readline");
+const fs = require("fs");
+const path = require("path");
+
+const configDir = path.join(process.env.HOME, ".config/jira-mcp");
+const configPath = path.join(configDir, "config.json");
+
+// Check for command line arguments
+const args = process.argv.slice(2);
+if (args.length >= 3) {
+  // Non-interactive mode: node setup.js <email> <token> <baseUrl>
+  const [email, token, baseUrl] = args;
+
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+
+  fs.writeFileSync(
+    configPath,
+    JSON.stringify({ email, token, baseUrl: baseUrl.replace(/\/$/, "") }, null, 2)
+  );
+  console.log(`Config saved to ${configPath}`);
+  process.exit(0);
+}
+
+// Interactive mode
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+function ask(question) {
+  return new Promise((resolve) => {
+    rl.question(question, resolve);
+  });
+}
+
+async function setup() {
+  console.log("\n=== Jira MCP Setup ===\n");
+  console.log("To get your Jira API token:");
+  console.log("1. Go to https://id.atlassian.com/manage-profile/security/api-tokens");
+  console.log("2. Click 'Create API token'");
+  console.log("3. Copy the token\n");
+
+  const email = await ask("Jira email: ");
+  const token = await ask("Jira API token: ");
+  const baseUrl = await ask("Jira base URL (e.g., https://company.atlassian.net): ");
+
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+
+  fs.writeFileSync(
+    configPath,
+    JSON.stringify({ email, token, baseUrl: baseUrl.replace(/\/$/, "") }, null, 2)
+  );
+  console.log(`\nConfig saved to ${configPath}`);
+
+  // Check for Figma MCP
+  const figmaConfigPath = path.join(process.env.HOME, ".config/figma-mcp/config.json");
+  if (fs.existsSync(figmaConfigPath)) {
+    console.log("\n[OK] Figma MCP detected - Figma links in tickets will be fetched automatically");
+  } else {
+    console.log("\n[INFO] Figma MCP not installed - Figma links won't be fetched");
+    console.log("To enable Figma integration, install figma-mcp");
+  }
+
+  console.log("\n=== Setup Complete ===");
+  console.log("\nAdd this to your Claude Code config (~/.claude.json):\n");
+  console.log(`"mcpServers": {
+  "jira": {
+    "type": "stdio",
+    "command": "node",
+    "args": ["${path.join(configDir, "server/index.js")}"]
+  }
+}`);
+
+  rl.close();
+}
+
+setup().catch((e) => {
+  console.error("Setup failed:", e.message);
+  rl.close();
+  process.exit(1);
+});