mcp-jira-stdio 1.7.1 → 1.8.0

package/dist/index.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import axios from 'axios';
 import { z } from 'zod';
+import FormData from 'form-data';
 import mdToAdf from 'md-to-adf';
 
 var __create = Object.create;
@@ -440,7 +441,7 @@ var require_package2 = __commonJS({
   "package.json"(exports$1, module) {
     module.exports = {
       name: "mcp-jira-stdio",
-      version: "1.7.1",
+      version: "1.8.0",
       description: "Model Context Protocol (MCP) server for Jira API integration",
       author: "graslt",
       license: "MIT",
@@ -491,6 +492,7 @@ var require_package2 = __commonJS({
       dependencies: {
         "@modelcontextprotocol/sdk": "^1.17.1",
         axios: "^1.7.0",
+        "form-data": "^4.0.5",
         "md-to-adf": "^0.5.0",
         zod: "^3.22.4"
       },
@@ -548,6 +550,13 @@ var ERROR_MESSAGES = {
   NETWORK_ERROR: "Network error occurred while connecting to Jira.",
   VALIDATION_ERROR: "Input validation failed."
 };
+var ATTACHMENT_CONFIG = {
+  MAX_FILE_SIZE: 50 * 1024 * 1024,
+  // 50 MB - Jira attachment size limit
+  MAX_BASE64_SIZE: 10 * 1024 * 1024,
+  // 10 MB for base64 content (token limit warning)
+  ALLOWED_PROTOCOLS: ["http:", "https:"]
+};
 var TOOL_NAMES = {
   GET_VISIBLE_PROJECTS: "jira_get_visible_projects",
   GET_ISSUE: "jira_get_issue",
@@ -565,7 +574,10 @@ var TOOL_NAMES = {
   GET_CREATE_META: "jira_get_create_meta",
   GET_CUSTOM_FIELDS: "jira_get_custom_fields",
   CREATE_ISSUE_LINK: "jira_create_issue_link",
-  GET_COMMENTS: "jira_get_comments"
+  GET_COMMENTS: "jira_get_comments",
+  ADD_ATTACHMENT: "jira_add_attachment",
+  GET_ATTACHMENTS: "jira_get_attachments",
+  DELETE_ATTACHMENT: "jira_delete_attachment"
 };
 
 // src/utils/logger.ts
@@ -605,6 +617,7 @@ function createLogger(scope) {
 
 // src/utils/jira-auth.ts
 var jiraClient = null;
+var jiraMultipartClient = null;
 var log = createLogger("jira-auth");
 function validateAuth() {
   const baseUrl = process.env.JIRA_BASE_URL;
@@ -707,6 +720,96 @@ async function makeJiraRequest(config, retryConfig = {
   }
   throw lastError;
 }
+function getMultipartClient() {
+  if (jiraMultipartClient) {
+    return jiraMultipartClient;
+  }
+  const auth = validateAuth();
+  jiraMultipartClient = axios.create({
+    baseURL: `${auth.baseUrl}${JIRA_CONFIG.BASE_PATH}`,
+    timeout: JIRA_CONFIG.DEFAULT_TIMEOUT,
+    headers: {
+      Accept: "application/json",
+      "X-Atlassian-Token": "no-check"
+    },
+    auth: {
+      username: auth.email,
+      password: auth.apiToken
+    }
+  });
+  jiraMultipartClient.interceptors.request.use(
+    (config) => {
+      log.debug(
+        `Multipart Request: ${config.method?.toUpperCase()} ${config.baseURL}${config.url}`
+      );
+      return config;
+    },
+    (error) => {
+      log.error("Multipart request error:", error);
+      return Promise.reject(error);
+    }
+  );
+  jiraMultipartClient.interceptors.response.use(
+    (response) => {
+      log.debug(`Multipart Response: ${response.status} ${response.config.url}`);
+      return response;
+    },
+    (error) => {
+      log.error(`Jira API multipart error: ${error.response?.status} ${error.config?.url}`);
+      if (error.response?.status === 401) {
+        throw new Error(ERROR_MESSAGES.INVALID_CREDENTIALS);
+      } else if (error.response?.status === 404) {
+        throw new Error("Resource not found or insufficient permissions");
+      } else if (error.response?.status === 429) {
+        throw new Error(ERROR_MESSAGES.RATE_LIMIT_EXCEEDED);
+      } else if (!error.response) {
+        throw new Error(ERROR_MESSAGES.NETWORK_ERROR);
+      }
+      return Promise.reject(error);
+    }
+  );
+  return jiraMultipartClient;
+}
+async function makeMultipartRequest(url, formData, retryConfig = {
+  maxRetries: JIRA_CONFIG.MAX_RETRIES,
+  retryDelay: JIRA_CONFIG.RETRY_DELAY
+}) {
+  const client = getMultipartClient();
+  let lastError;
+  for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
+    try {
+      const response = await client.post(url, formData, {
+        headers: {
+          ...formData.getHeaders()
+        }
+      });
+      return response.data;
+    } catch (error) {
+      lastError = error;
+      if (error.response?.status === 401 || error.response?.status === 403 || error.response?.status === 404 || error.response?.status >= 400 && error.response?.status < 500 && error.response?.status !== 429) {
+        break;
+      }
+      if (attempt === retryConfig.maxRetries) {
+        break;
+      }
+      const retryAfterHeader = error.response?.headers?.["retry-after"];
+      let delayMs = 0;
+      if (retryAfterHeader) {
+        const seconds = Number(retryAfterHeader);
+        delayMs = !Number.isNaN(seconds) ? seconds * 1e3 : retryConfig.retryDelay;
+      } else {
+        const base = retryConfig.retryDelay * Math.pow(2, attempt);
+        const jitter = Math.floor(Math.random() * (retryConfig.retryDelay / 2));
+        delayMs = base + jitter;
+      }
+      log.warn(
+        `Retrying multipart request in ${delayMs}ms (attempt ${attempt + 1}/${retryConfig.maxRetries})`
+      );
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+  throw lastError;
+}
 function validateInput(schema, input) {
   try {
     return schema.parse(input);
@@ -855,6 +958,33 @@ var GetCommentsInputSchema = z.object({
   orderBy: z.enum(["created", "-created", "+created"]).optional().describe('Sort order for comments: "created" (oldest first), "-created" (newest first)'),
   startAt: z.number().min(0).optional().describe("Index of first comment to return (for pagination)")
 });
+var AddAttachmentInputSchema = z.object({
+  issueKey: z.string().describe("Issue key to add attachment to (e.g., PROJECT-123)").refine((v) => isValidIssueKey(v), "Invalid issue key format"),
+  filename: z.string().min(1).describe("Name of the file to attach"),
+  // Option 1: Remote URL (efficient - ~60 tokens)
+  fileUrl: z.string().url().optional().describe(
+    "URL to download file from (efficient for remote files, ~60 tokens). Upload large files to Dropbox/S3/imgur first, then use URL."
+  ),
+  // Option 2: Base64 content (for small files or backwards compatibility)
+  content: z.string().optional().describe(
+    "Base64-encoded or plain text content. WARNING: HIGH token cost (~330k tokens for 1MB file). Use fileUrl for large files or upload to cloud storage first."
+  ),
+  isBase64: z.boolean().optional().default(true).describe(
+    "Whether content is base64-encoded (default: true). Set to false for plain text files."
+  )
+}).refine(
+  (data) => {
+    const sources = [data.fileUrl, data.content].filter(Boolean);
+    return sources.length === 1;
+  },
+  { message: "Exactly one of fileUrl or content must be provided" }
+);
+var GetAttachmentsInputSchema = z.object({
+  issueKey: z.string().describe("Issue key to get attachments for (e.g., PROJECT-123)").refine((v) => isValidIssueKey(v), "Invalid issue key format")
+});
+var DeleteAttachmentInputSchema = z.object({
+  attachmentId: z.string().min(1).describe("ID of the attachment to delete")
+});
 function ensureAdfDescription(desc, format = "markdown") {
   if (!desc) return desc;
   if (typeof desc === "object") return desc;
@@ -1334,6 +1464,63 @@ async function createIssueLink(fromIssue, toIssue, linkType) {
   };
   await makeJiraRequest(config);
 }
+async function addAttachment(issueKey, filename, content, isBase64 = true) {
+  const formData = new FormData();
+  let fileBuffer;
+  if (isBase64) {
+    fileBuffer = Buffer.from(content, "base64");
+  } else {
+    fileBuffer = Buffer.from(content, "utf-8");
+  }
+  formData.append("file", fileBuffer, {
+    filename,
+    contentType: "application/octet-stream"
+  });
+  return await makeMultipartRequest(`/issue/${issueKey}/attachments`, formData);
+}
+async function addAttachmentFromUrl(issueKey, fileUrl, filename) {
+  const axios2 = (await import('axios')).default;
+  const urlObj = new URL(fileUrl);
+  if (urlObj.hostname === "localhost" || urlObj.hostname.startsWith("127.")) {
+    throw new Error("Cannot download from localhost (SSRF protection)");
+  }
+  if (urlObj.hostname.startsWith("192.168.") || urlObj.hostname.startsWith("10.")) {
+    throw new Error("Cannot download from private network (SSRF protection)");
+  }
+  if (urlObj.hostname.startsWith("172.")) {
+    const parts = urlObj.hostname.split(".");
+    const secondOctet = parts[1] ? parseInt(parts[1]) : 0;
+    if (secondOctet >= 16 && secondOctet <= 31) {
+      throw new Error("Cannot download from private network (SSRF protection)");
+    }
+  }
+  const response = await axios2.get(fileUrl, {
+    responseType: "arraybuffer",
+    maxContentLength: 50 * 1024 * 1024,
+    // 50 MB limit
+    timeout: 3e4
+    // 30 seconds
+  });
+  const fileBuffer = Buffer.from(response.data);
+  const formData = new FormData();
+  formData.append("file", fileBuffer, {
+    filename,
+    contentType: response.headers["content-type"] || "application/octet-stream"
+  });
+  return await makeMultipartRequest(`/issue/${issueKey}/attachments`, formData);
+}
+async function getAttachments(issueKey) {
+  const issue = await getIssue(issueKey, { fields: ["attachment"] });
+  const attachments = issue.fields.attachment || [];
+  return attachments;
+}
+async function deleteAttachment(attachmentId) {
+  const config = {
+    method: "DELETE",
+    url: `/attachment/${attachmentId}`
+  };
+  await makeJiraRequest(config);
+}
 
 // src/utils/redaction.ts
 function isRedactionEnabled() {
@@ -1814,6 +2001,67 @@ ${fieldsList}`
     ]
   };
 }
+function formatFileSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function formatAttachmentResponse(attachment, issueKey) {
+  const authorName = attachment.author?.displayName || "Unknown";
+  const createdDate = attachment.created ? new Date(attachment.created).toISOString() : "N/A";
+  return {
+    content: [
+      {
+        type: "text",
+        text: `**Attachment uploaded successfully to ${issueKey}**
+
+**Filename:** ${attachment.filename}
+**ID:** ${attachment.id}
+**Size:** ${formatFileSize(attachment.size)}
+**MIME Type:** ${attachment.mimeType}
+**Author:** ${authorName}
+**Created:** ${createdDate}
+**Download URL:** ${attachment.content}
+${attachment.thumbnail ? `**Thumbnail:** ${attachment.thumbnail}` : ""}
+
+\u{1F4A1} **Tip:** To embed this image in a comment or description, use: \`!${attachment.filename}!\` or \`!${attachment.filename}|thumbnail!\``
+      }
+    ]
+  };
+}
+function formatAttachmentsListResponse(attachments, issueKey) {
+  if (!attachments || attachments.length === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `No attachments found for issue ${issueKey}.`
+        }
+      ]
+    };
+  }
+  const attachmentsList = attachments.map((attachment) => {
+    const authorName = attachment.author?.displayName || "Unknown";
+    const createdDate = attachment.created ? new Date(attachment.created).toISOString() : "N/A";
+    const thumbnailInfo = attachment.thumbnail ? " (has thumbnail)" : "";
+    return `\u2022 **${attachment.filename}** (ID: ${attachment.id})
+  Size: ${formatFileSize(attachment.size)} | Type: ${attachment.mimeType}${thumbnailInfo}
+  Author: ${authorName} | Created: ${createdDate}
+  URL: ${attachment.content}`;
+  }).join("\n\n");
+  return {
+    content: [
+      {
+        type: "text",
+        text: `**Attachments for ${issueKey}** (${attachments.length} attachment${attachments.length !== 1 ? "s" : ""}):
+
+${attachmentsList}
+
+\u{1F4A1} **Tip:** To embed an image in a comment or description, use: \`!filename.png!\` or \`!filename.png|thumbnail!\``
+      }
+    ]
+  };
+}
 
 // src/utils/error-handler.ts
 var log2 = createLogger("error-handler");
@@ -2740,6 +2988,148 @@ async function handleGetComments(input) {
   }
 }
 
+// src/tools/add-attachment.ts
+var log20 = createLogger("tool:add-attachment");
+var addAttachmentTool = {
+  name: TOOL_NAMES.ADD_ATTACHMENT,
+  description: `Uploads an attachment (image, document, etc.) to a Jira issue.
+
+**EFFICIENT METHOD (recommended for large files):**
+- fileUrl: Provide URL to remote file - MINIMAL tokens (~60 tokens)
+  Example: Upload to Dropbox/S3/imgur first, then provide URL
+
+**DIRECT METHOD (for small files):**
+- content: Base64 encoded content - WARNING: HIGH token cost (~330,000 tokens for 1MB file)
+  Only suitable for small files (< 500 KB)
+
+Returns attachment metadata including ID and download URL. To reference the image in a comment or description, use wiki markup: !filename.png! or !filename.png|thumbnail!`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      issueKey: {
+        type: "string",
+        description: "Issue key to add attachment to (e.g., PROJECT-123)"
+      },
+      filename: {
+        type: "string",
+        description: "Name of the file to attach (e.g., screenshot.png, document.pdf)",
+        minLength: 1
+      },
+      fileUrl: {
+        type: "string",
+        description: "URL to download file from (efficient for remote files, ~60 tokens). Upload large files to Dropbox/S3/imgur first, then use URL.",
+        format: "uri"
+      },
+      content: {
+        type: "string",
+        description: "Base64-encoded or plain text content. WARNING: HIGH token cost (~330k tokens for 1MB file). Use fileUrl for large files or upload to cloud storage first."
+      },
+      isBase64: {
+        type: "boolean",
+        description: "Whether content is base64-encoded (default: true). Set to false for plain text files.",
+        default: true
+      }
+    },
+    required: ["issueKey", "filename"]
+  }
+};
+async function handleAddAttachment(input) {
+  try {
+    const validated = validateInput(AddAttachmentInputSchema, input);
+    const { issueKey, filename, fileUrl, content, isBase64 } = validated;
+    log20.info(`Adding attachment "${filename}" to issue ${issueKey}...`);
+    let attachments;
+    if (fileUrl) {
+      log20.info("Using URL method (efficient - ~60 tokens)");
+      attachments = await addAttachmentFromUrl(issueKey, fileUrl, filename);
+    } else if (content) {
+      if (content.length > ATTACHMENT_CONFIG.MAX_BASE64_SIZE) {
+        log20.warn(
+          `Large base64 content detected (${content.length} chars = ~${Math.round(content.length / 4)} tokens). Consider uploading to cloud storage and using fileUrl instead.`
+        );
+      }
+      log20.info("Using base64 content method (HIGH token cost for large files)");
+      attachments = await addAttachment(issueKey, filename, content, isBase64);
+    } else {
+      throw new Error("No file source provided (fileUrl or content required)");
+    }
+    if (!attachments || attachments.length === 0) {
+      throw new Error("Failed to upload attachment - no attachment returned from Jira");
+    }
+    log20.info(`Added attachment "${filename}" to ${issueKey}`);
+    return formatAttachmentResponse(attachments[0], issueKey);
+  } catch (error) {
+    log20.error("Error in handleAddAttachment:", error);
+    return handleError(error);
+  }
+}
+
+// src/tools/get-attachments.ts
+var log21 = createLogger("tool:get-attachments");
+var getAttachmentsTool = {
+  name: TOOL_NAMES.GET_ATTACHMENTS,
+  description: "Lists all attachments on a Jira issue. Returns attachment metadata including filename, size, MIME type, author, and download URL.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      issueKey: {
+        type: "string",
+        description: "Issue key to get attachments for (e.g., PROJECT-123)"
+      }
+    },
+    required: ["issueKey"]
+  }
+};
+async function handleGetAttachments(input) {
+  try {
+    const validated = validateInput(GetAttachmentsInputSchema, input);
+    log21.info(`Getting attachments for issue ${validated.issueKey}...`);
+    const attachments = await getAttachments(validated.issueKey);
+    log21.info(`Found ${attachments.length} attachment(s) for ${validated.issueKey}`);
+    return formatAttachmentsListResponse(attachments, validated.issueKey);
+  } catch (error) {
+    log21.error("Error in handleGetAttachments:", error);
+    return handleError(error);
+  }
+}
+
+// src/tools/delete-attachment.ts
+var log22 = createLogger("tool:delete-attachment");
+var deleteAttachmentTool = {
+  name: TOOL_NAMES.DELETE_ATTACHMENT,
+  description: "Deletes an attachment from Jira by its attachment ID. Use jira_get_attachments to find attachment IDs.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      attachmentId: {
+        type: "string",
+        description: "ID of the attachment to delete (can be found using jira_get_attachments)",
+        minLength: 1
+      }
+    },
+    required: ["attachmentId"]
+  }
+};
+async function handleDeleteAttachment(input) {
+  try {
+    const validated = validateInput(DeleteAttachmentInputSchema, input);
+    log22.info(`Deleting attachment ${validated.attachmentId}...`);
+    await deleteAttachment(validated.attachmentId);
+    log22.info(`Deleted attachment ${validated.attachmentId}`);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Successfully deleted attachment ${validated.attachmentId}`
+        }
+      ]
+    };
+  } catch (error) {
+    log22.error("Error in handleDeleteAttachment:", error);
+    return handleError(error);
+  }
+}
+
 // src/index.ts
 if (process.env.NODE_ENV !== "production") {
   try {
@@ -2748,7 +3138,7 @@ if (process.env.NODE_ENV !== "production") {
   } catch {
   }
 }
-var log20 = createLogger("server");
+var log23 = createLogger("server");
 var toolHandlers = /* @__PURE__ */ new Map([
   [TOOL_NAMES.GET_VISIBLE_PROJECTS, handleGetVisibleProjects],
   [TOOL_NAMES.GET_ISSUE, handleGetIssue],
@@ -2766,7 +3156,10 @@ var toolHandlers = /* @__PURE__ */ new Map([
   [TOOL_NAMES.GET_CREATE_META, handleGetCreateMeta],
   [TOOL_NAMES.GET_CUSTOM_FIELDS, handleGetCustomFields],
   [TOOL_NAMES.CREATE_ISSUE_LINK, handleCreateIssueLink],
-  [TOOL_NAMES.GET_COMMENTS, handleGetComments]
+  [TOOL_NAMES.GET_COMMENTS, handleGetComments],
+  [TOOL_NAMES.ADD_ATTACHMENT, handleAddAttachment],
+  [TOOL_NAMES.GET_ATTACHMENTS, handleGetAttachments],
+  [TOOL_NAMES.DELETE_ATTACHMENT, handleDeleteAttachment]
 ]);
 var allTools = [
   getVisibleProjectsTool,
@@ -2785,7 +3178,10 @@ var allTools = [
   getCreateMetaTool,
   getCustomFieldsTool,
   createIssueLinkTool,
-  getCommentsTool
+  getCommentsTool,
+  addAttachmentTool,
+  getAttachmentsTool,
+  deleteAttachmentTool
 ];
 async function main() {
   const isDryRun = (process.env.DRY_RUN || "").toLowerCase() === "1" || (process.env.DRY_RUN || "").toLowerCase() === "true";
@@ -2856,7 +3252,7 @@ async function main() {
   console.error("\u{1F680} Jira MCP server running on stdio");
 }
 main().catch((error) => {
-  log20.error("Fatal error:", error);
+  log23.error("Fatal error:", error);
   process.exit(1);
 });
 //# sourceMappingURL=index.js.map