@atlassian-dc-mcp/jira 0.27.0 → 0.28.0

package/src/__tests__/jira-download.test.ts

@@ -0,0 +1,111 @@
+import type { AttachmentGatewaySide } from '@atlassian-dc-mcp/common';
+import { JiraService } from '../jira-service.js';
+import { AttachmentService, IssueService } from '../jira-client/index.js';
+
+const DISABLED_DOWNLOAD: AttachmentGatewaySide = { enabled: false, roots: [], maxBytes: 25 * 1024 * 1024 };
+
+jest.mock('../jira-client/index.js', () => ({
+  AttachmentService: {
+    getAttachment: jest.fn(),
+  },
+  IssueService: {
+    getIssue: jest.fn(),
+  },
+  MyselfService: {},
+  SearchService: {},
+  OpenAPI: { BASE: '', TOKEN: '', VERSION: '' },
+}));
+
+function mockFetchText(text: string) {
+  global.fetch = jest.fn().mockResolvedValue({
+    ok: true,
+    status: 200,
+    statusText: 'OK',
+    headers: { get: () => 'text/plain' },
+    arrayBuffer: async () => Buffer.from(text),
+  }) as unknown as typeof fetch;
+}
+
+describe('JiraService.downloadAttachments', () => {
+  let service: JiraService;
+
+  beforeEach(() => {
+    service = new JiraService('test-host', 'test-token', undefined, () => 25);
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => jest.restoreAllMocks());
+
+  it('downloads a single attachment by id using its content URL', async () => {
+    (AttachmentService.getAttachment as jest.Mock).mockResolvedValue({
+      id: '10001',
+      filename: 'report.pdf',
+      mimeType: 'application/pdf',
+      content: 'https://test-host/secure/attachment/10001/report.pdf',
+    });
+    mockFetchText('pdf-bytes');
+
+    const result = await service.downloadAttachments({ attachmentId: '10001', returnContent: 'text', downloadSide: DISABLED_DOWNLOAD });
+
+    expect(AttachmentService.getAttachment).toHaveBeenCalledWith('10001');
+    expect(global.fetch).toHaveBeenCalledWith(
+      'https://test-host/secure/attachment/10001/report.pdf',
+      expect.objectContaining({ headers: expect.objectContaining({ Authorization: 'Bearer test-token' }) }),
+    );
+    expect(result.success).toBe(true);
+    expect(result.data).toMatchObject({ count: 1 });
+    expect(result.data!.attachments[0]).toMatchObject({ filename: 'report.pdf', content: 'pdf-bytes' });
+  });
+
+  it('downloads all attachments on an issue', async () => {
+    (IssueService.getIssue as jest.Mock).mockResolvedValue({
+      fields: {
+        attachment: [
+          { id: '1', filename: 'a.txt', content: 'https://test-host/a' },
+          { id: '2', filename: 'b.txt', content: 'https://test-host/b' },
+        ],
+      },
+    });
+    mockFetchText('x');
+
+    const result = await service.downloadAttachments({ issueKey: 'PROJ-1', downloadSide: DISABLED_DOWNLOAD });
+
+    expect(IssueService.getIssue).toHaveBeenCalledWith('PROJ-1', undefined, ['attachment']);
+    expect(result.success).toBe(true);
+    expect(result.data!.count).toBe(2);
+  });
+
+  it('filters issue attachments by filename', async () => {
+    (IssueService.getIssue as jest.Mock).mockResolvedValue({
+      fields: {
+        attachment: [
+          { id: '1', filename: 'a.txt', content: 'https://test-host/a' },
+          { id: '2', filename: 'b.txt', content: 'https://test-host/b' },
+        ],
+      },
+    });
+    mockFetchText('x');
+
+    const result = await service.downloadAttachments({ issueKey: 'PROJ-1', filename: 'b.txt', downloadSide: DISABLED_DOWNLOAD });
+
+    expect(result.success).toBe(true);
+    expect(result.data!.count).toBe(1);
+    expect(result.data!.attachments[0].filename).toBe('b.txt');
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('fails when neither attachmentId nor issueKey is provided', async () => {
+    const result = await service.downloadAttachments({ downloadSide: DISABLED_DOWNLOAD });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('attachmentId or issueKey');
+  });
+
+  it('fails when an issue has no matching attachment', async () => {
+    (IssueService.getIssue as jest.Mock).mockResolvedValue({ fields: { attachment: [] } });
+
+    const result = await service.downloadAttachments({ issueKey: 'PROJ-1', filename: 'x.txt', downloadSide: DISABLED_DOWNLOAD });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('No attachment named "x.txt"');
+  });
+});

package/src/__tests__/jira-upload.test.ts

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { AttachmentGatewaySide } from '@atlassian-dc-mcp/common';
+import { JiraService } from '../jira-service.js';
+import { IssueService } from '../jira-client/index.js';
+
+jest.mock('../jira-client/index.js', () => ({
+  AttachmentService: {},
+  IssueService: {
+    addAttachment: jest.fn(),
+  },
+  MyselfService: {},
+  SearchService: {},
+  OpenAPI: { BASE: '', TOKEN: '', VERSION: '' },
+}));
+
+describe('JiraService.uploadAttachment', () => {
+  let service: JiraService;
+  let root: string;
+  const uploadSide = (): AttachmentGatewaySide => ({ enabled: true, roots: [fs.realpathSync(root)], maxBytes: 1024 });
+
+  beforeEach(() => {
+    service = new JiraService('test-host', 'test-token', undefined, () => 25);
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'dc-mcp-jup-'));
+    jest.clearAllMocks();
+    (IssueService.addAttachment as jest.Mock).mockResolvedValue([{ id: '1', filename: 'a.txt' }]);
+  });
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+    jest.restoreAllMocks();
+  });
+
+  it('uploads a file resolved within the upload root', async () => {
+    fs.writeFileSync(path.join(root, 'a.txt'), 'hello');
+
+    const result = await service.uploadAttachment('PROJ-1', 'a.txt', uploadSide());
+
+    expect(result.success).toBe(true);
+    expect(IssueService.addAttachment).toHaveBeenCalledTimes(1);
+    const [issueKey, formData] = (IssueService.addAttachment as jest.Mock).mock.calls[0];
+    expect(issueKey).toBe('PROJ-1');
+    expect(formData.file.name).toBe('a.txt');
+  });
+
+  it('rejects an absolute path outside the root', async () => {
+    const result = await service.uploadAttachment('PROJ-1', '/etc/passwd', uploadSide());
+    expect(result.success).toBe(false);
+    expect(IssueService.addAttachment).not.toHaveBeenCalled();
+  });
+
+  it('rejects a symlink inside the root', async () => {
+    const target = path.join(root, 'real.txt');
+    fs.writeFileSync(target, 'secret');
+    fs.symlinkSync(target, path.join(root, 'link.txt'));
+
+    const result = await service.uploadAttachment('PROJ-1', 'link.txt', uploadSide());
+    expect(result.success).toBe(false);
+    expect(IssueService.addAttachment).not.toHaveBeenCalled();
+  });
+
+  it('rejects a file over the size limit', async () => {
+    fs.writeFileSync(path.join(root, 'big.txt'), 'x'.repeat(2048));
+
+    const result = await service.uploadAttachment('PROJ-1', 'big.txt', uploadSide());
+    expect(result.success).toBe(false);
+    expect(IssueService.addAttachment).not.toHaveBeenCalled();
+  });
+});

package/src/index.ts

@@ -1,6 +1,6 @@
-import { connectServer, createMcpServer, formatToolResponse, initializeRuntimeConfig } from '@atlassian-dc-mcp/common';
+import { connectServer, createMcpServer, formatToolResponse, initializeRuntimeConfig, resolveAttachmentGateway } from '@atlassian-dc-mcp/common';
 import { JiraService, jiraToolSchemas } from './jira-service.js';
-import { getDefaultPageSize, getJiraRuntimeConfig } from './config.js';
+import { getDefaultPageSize, getJiraRuntimeConfig, JIRA_PRODUCT } from './config.js';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
@@ -147,4 +147,49 @@ server.tool(
   }
 );
 
+const attachmentGateway = resolveAttachmentGateway(JIRA_PRODUCT);
+
+// Filesystem-reading upload is only registered when the operator explicitly enables it.
+if (attachmentGateway.upload.enabled) {
+  server.tool(
+    "jira_uploadAttachment",
+    `Upload a local file as an attachment to a JIRA issue in the ${jiraInstanceType}. The file must live under the server-configured upload directory; the path is given relative to that directory.`,
+    jiraToolSchemas.uploadAttachment,
+    async ({ issueKey, sourcePath, filename }) => {
+      const result = await jiraService.uploadAttachment(issueKey, sourcePath, attachmentGateway.upload, filename);
+      return formatToolResponse(result);
+    }
+  );
+}
+
+// Download always returns content inline (no filesystem access). Saving to disk is
+// only offered when the operator enables it, and is confined to the configured directory.
+const downloadSaveEnabled = attachmentGateway.download.enabled;
+server.tool(
+  "jira_downloadAttachment",
+  `Download attachment(s) from a JIRA issue in the ${jiraInstanceType}, by issue key (optionally filtered by filename) or by a single attachment id. Returns the file content inline (base64 or text). Useful for inspecting a file or moving it elsewhere (e.g. re-uploading to a Confluence page).${downloadSaveEnabled ? ' Can also save into the server-configured download directory; existing files are never overwritten.' : ' Saving to local disk is disabled on this server.'}`,
+  { ...jiraToolSchemas.downloadAttachment, ...(downloadSaveEnabled ? jiraToolSchemas.downloadAttachmentSaveFields : {}) },
+  async ({ issueKey, attachmentId, filename, returnContent, maxInlineBytes, save, saveName }: {
+    issueKey?: string;
+    attachmentId?: string;
+    filename?: string;
+    returnContent?: 'none' | 'base64' | 'text';
+    maxInlineBytes?: number;
+    save?: boolean;
+    saveName?: string;
+  }) => {
+    const result = await jiraService.downloadAttachments({
+      issueKey,
+      attachmentId,
+      filename,
+      save,
+      saveName,
+      returnContent,
+      maxInlineBytes,
+      downloadSide: attachmentGateway.download,
+    });
+    return formatToolResponse(result);
+  }
+);
+
 await connectServer(server);

package/src/jira-service.ts

@@ -1,6 +1,17 @@
+import { File } from 'node:buffer';
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
 import { z } from 'zod';
-import { handleApiOperation, resolveOpenApiBase } from '@atlassian-dc-mcp/common';
-import { IssueLinkService, IssueLinkTypeService, IssueService, MyselfService, OpenAPI, SearchService } from './jira-client/index.js';
+import {
+  downloadAttachment,
+  handleApiOperation,
+  resolveDownloadDestination,
+  resolveOpenApiBase,
+  resolveUploadSource,
+  type AttachmentContentEncoding,
+  type AttachmentGatewaySide,
+} from '@atlassian-dc-mcp/common';
+import { AttachmentService, IssueLinkService, IssueLinkTypeService, IssueService, MyselfService, OpenAPI, SearchService } from './jira-client/index.js';
 import { request as __request } from './jira-client/core/request.js';
 import type { StringList } from './jira-client/models/StringList.js';
 import { getDefaultPageSize, getMissingConfig, JIRA_PRODUCT } from './config.js';
@@ -28,6 +39,7 @@ function resolveToken(token: string | (() => string | undefined), missingTokenMe
 
 export class JiraService {
   private readonly getPageSize: () => number;
+  private readonly tokenProvider: string | (() => string | undefined);
 
   constructor(
     host: string | undefined,
@@ -43,6 +55,8 @@ export class JiraService {
     });
     OpenAPI.TOKEN = resolveToken(token, 'Missing required environment variable: JIRA_API_TOKEN');
     OpenAPI.VERSION = '2';
+    OpenAPI.HEADERS = { 'X-Atlassian-Token': 'no-check' };
+    this.tokenProvider = token;
     this.getPageSize = getPageSize;
   }
 
@@ -177,6 +191,104 @@ export class JiraService {
     }, 'Error transitioning issue');
   }
 
+  async uploadAttachment(issueKey: string, sourcePath: string, uploadSide: AttachmentGatewaySide, filename?: string) {
+    return handleApiOperation(async () => {
+      const { absolutePath } = await resolveUploadSource({ requestedPath: sourcePath, side: uploadSide });
+      const buffer = await readFile(absolutePath);
+      const name = filename || basename(absolutePath);
+      const file = new File([buffer], name);
+      // IssueService types formData as Blob, but the API expects { file } — getFormData handles File via isBlob()
+      return IssueService.addAttachment(issueKey, { file } as any);
+    }, 'Error uploading attachment');
+  }
+
+  /**
+   * Download attachments from a JIRA issue, or a single attachment by its id.
+   * Exactly one of `attachmentId` or `issueKey` must be provided.
+   * @param params.attachmentId Download a single attachment by its numeric id
+   * @param params.issueKey Download attachments from this issue (optionally filtered by filename)
+   * @param params.filename When using issueKey, download only attachments with this exact filename
+   * @param params.save Whether to write the attachment(s) to the operator-configured download directory
+   * @param params.saveName Optional file name (basename only) when saving a single attachment
+   * @param params.returnContent Whether/how to embed the bytes inline in the response
+   * @param params.maxInlineBytes Inline embedding cap
+   * @param params.downloadSide Resolved download gateway (roots, size limit, enabled flag)
+   */
+  async downloadAttachments(params: {
+    attachmentId?: string;
+    issueKey?: string;
+    filename?: string;
+    save?: boolean;
+    saveName?: string;
+    returnContent?: AttachmentContentEncoding;
+    maxInlineBytes?: number;
+    downloadSide: AttachmentGatewaySide;
+  }) {
+    return handleApiOperation(async () => {
+      if (params.save && !params.downloadSide.enabled) {
+        throw new Error(
+          'Saving attachments to disk is disabled on this server. Enable it with ' +
+            'JIRA_ATTACHMENTS_DOWNLOAD_ENABLED and configure a download directory.',
+        );
+      }
+      const beans = await this.resolveAttachmentBeans(params);
+      const multiple = beans.length > 1;
+      const attachments = [];
+      for (const bean of beans) {
+        const url = bean?.content;
+        if (!url) {
+          throw new Error(`Attachment "${bean?.filename ?? bean?.id}" has no download URL`);
+        }
+        const filename = bean?.filename ?? String(bean?.id ?? 'attachment');
+        let destination: string | undefined;
+        if (params.save) {
+          const requestedName = multiple ? filename : params.saveName ?? filename;
+          destination = await resolveDownloadDestination({ requestedName, side: params.downloadSide });
+        }
+        attachments.push(
+          await downloadAttachment({
+            url,
+            token: this.tokenProvider,
+            filename,
+            mediaType: bean?.mimeType,
+            options: {
+              destination,
+              returnContent: params.returnContent,
+              maxInlineBytes: params.maxInlineBytes,
+              maxDownloadBytes: params.downloadSide.maxBytes,
+            },
+          }),
+        );
+      }
+      return { count: attachments.length, attachments };
+    }, 'Error downloading attachment');
+  }
+
+  private async resolveAttachmentBeans(params: {
+    attachmentId?: string;
+    issueKey?: string;
+    filename?: string;
+  }): Promise<Array<Record<string, any>>> {
+    if (params.attachmentId) {
+      const bean = await AttachmentService.getAttachment(params.attachmentId);
+      return [bean as Record<string, any>];
+    }
+    if (!params.issueKey) {
+      throw new Error('Either attachmentId or issueKey must be provided');
+    }
+    const issue = await IssueService.getIssue(params.issueKey, undefined, toIssueFieldSelection(['attachment']));
+    const all = (((issue as any)?.fields?.attachment) ?? []) as Array<Record<string, any>>;
+    const filtered = params.filename ? all.filter((a) => a?.filename === params.filename) : all;
+    if (filtered.length === 0) {
+      throw new Error(
+        params.filename
+          ? `No attachment named "${params.filename}" found on issue ${params.issueKey}`
+          : `No attachments found on issue ${params.issueKey}`,
+      );
+    }
+    return filtered;
+  }
+
   async getIssueLinkTypes() {
     return handleApiOperation(
       () => IssueLinkTypeService.getIssueLinkTypes(),
@@ -267,6 +379,22 @@ export const jiraToolSchemas = {
     fields: z.record(z.any()).optional().describe("Optional fields required by the transition screen. Use jira_getTransitions to see which fields are available for each transition."),
     customFields: z.record(z.any()).optional().describe("Optional fields merged into the JIRA transition payload. Can be used for update operations such as comments. Example: {'update': {'comment': [{'add': {'body': 'text'}}]}}")
   },
+  uploadAttachment: {
+    issueKey: z.string().describe("JIRA issue key (e.g., PROJ-123)"),
+    sourcePath: z.string().describe("Path to the file to upload, relative to a server-configured attachment upload directory. Absolute paths and '..' segments are rejected; symlinks and non-regular files are refused."),
+    filename: z.string().optional().describe("Override for the attachment filename (defaults to the basename of sourcePath)")
+  },
+  downloadAttachment: {
+    issueKey: z.string().optional().describe("JIRA issue key (e.g., PROJ-123) whose attachment(s) to download. Provide either issueKey or attachmentId."),
+    attachmentId: z.string().optional().describe("Numeric id of a single attachment to download. Provide either attachmentId or issueKey."),
+    filename: z.string().optional().describe("When using issueKey, download only attachments with this exact filename. If omitted, all attachments on the issue are downloaded."),
+    returnContent: z.enum(['none', 'base64', 'text']).optional().describe("Whether to embed the file bytes in the response: 'none' (default), 'base64' for binary, or 'text' for UTF-8 text."),
+    maxInlineBytes: z.number().optional().describe("Maximum bytes to embed inline when returnContent is base64/text. Larger files are omitted from the inline content. Defaults to 1 MiB.")
+  },
+  downloadAttachmentSaveFields: {
+    save: z.boolean().optional().describe("Save the attachment(s) into the server-configured download directory. Requires disk downloads to be enabled on the server."),
+    saveName: z.string().optional().describe("Optional file name (no directories) to use when saving a single attachment; defaults to the attachment's own name. Existing files are never overwritten.")
+  },
   getIssueLinkTypes: {},
   linkIssues: {
     inwardIssueKey: z.string().describe("Key of the inward issue (the one the inward link description applies to, e.g. the issue that 'is blocked by'). Example: PROJ-123"),