@atlassian-dc-mcp/jira 0.26.0 → 0.28.0

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/__tests__/response-body.test.ts

@@ -0,0 +1,43 @@
+import { getResponseBody } from '../jira-client/core/request.js';
+
+function jsonResponse(status: number, body: string): Response {
+  return {
+    status,
+    headers: new Headers({ 'Content-Type': 'application/json' }),
+    text: async () => body,
+    json: async () => JSON.parse(body),
+  } as unknown as Response;
+}
+
+describe('getResponseBody', () => {
+  const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+  afterEach(() => {
+    errorSpy.mockClear();
+  });
+
+  afterAll(() => {
+    errorSpy.mockRestore();
+  });
+
+  it('returns undefined for an empty JSON body without logging (e.g. POST /issueLink)', async () => {
+    const result = await getResponseBody(jsonResponse(201, ''));
+
+    expect(result).toBeUndefined();
+    expect(errorSpy).not.toHaveBeenCalled();
+  });
+
+  it('parses a non-empty JSON body', async () => {
+    const result = await getResponseBody(jsonResponse(200, '{"id":"1158012"}'));
+
+    expect(result).toEqual({ id: '1158012' });
+    expect(errorSpy).not.toHaveBeenCalled();
+  });
+
+  it('returns undefined for a 204 No Content response (e.g. DELETE /issueLink)', async () => {
+    const result = await getResponseBody(jsonResponse(204, ''));
+
+    expect(result).toBeUndefined();
+    expect(errorSpy).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);
@@ -117,4 +117,79 @@ server.tool(
   }
 );
 
+server.tool(
+  "jira_getIssueLinkTypes",
+  `Get the list of available issue link types (e.g. Blocks, Relates, Duplicate) in the ${jiraInstanceType}. Use this to discover valid link type names before calling jira_linkIssues.`,
+  jiraToolSchemas.getIssueLinkTypes,
+  async () => {
+    const result = await jiraService.getIssueLinkTypes();
+    return formatToolResponse(result);
+  }
+);
+
+server.tool(
+  "jira_linkIssues",
+  `Create a link between two JIRA issues in the ${jiraInstanceType}. Use jira_getIssueLinkTypes to find valid link type names.`,
+  jiraToolSchemas.linkIssues,
+  async (params) => {
+    const result = await jiraService.linkIssues(params);
+    return formatToolResponse(result);
+  }
+);
+
+server.tool(
+  "jira_unlinkIssues",
+  `Delete an existing link between two JIRA issues in the ${jiraInstanceType}. Requires the issue link id (found in the 'issuelinks' field of an issue).`,
+  jiraToolSchemas.unlinkIssues,
+  async ({ linkId }) => {
+    const result = await jiraService.unlinkIssues(linkId);
+    return formatToolResponse(result);
+  }
+);
+
+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-client/core/request.ts

@@ -257,7 +257,11 @@ export const getResponseBody = async (response: Response): Promise<any> => {
                 const jsonTypes = ['application/json', 'application/problem+json']
                 const isJSON = jsonTypes.some(type => contentType.toLowerCase().startsWith(type));
                 if (isJSON) {
-                    return await response.json();
+                    // Some endpoints (e.g. POST /issueLink) return a success status with
+                    // Content-Type: application/json but an empty body; parsing that as JSON
+                    // throws. Read the text first and only parse when there is something to parse.
+                    const text = await response.text();
+                    return text ? JSON.parse(text) : undefined;
                 } else {
                     return await response.text();
                 }

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 { 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,134 @@ 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(),
+      'Error getting issue link types'
+    );
+  }
+
+  async linkIssues(params: {
+    inwardIssueKey: string;
+    outwardIssueKey: string;
+    linkType: string;
+    comment?: string;
+  }) {
+    return handleApiOperation(() => {
+      return IssueLinkService.linkIssues({
+        type: { name: params.linkType },
+        inwardIssue: { key: params.inwardIssueKey },
+        outwardIssue: { key: params.outwardIssueKey },
+        ...(params.comment ? { comment: { body: params.comment } } : {}),
+      });
+    }, 'Error linking issues');
+  }
+
+  async unlinkIssues(linkId: string) {
+    return handleApiOperation(
+      () => IssueLinkService.deleteIssueLink(linkId),
+      'Error unlinking issues'
+    );
+  }
+
   async validateSetup(): Promise<void> {
     await MyselfService.getUser();
   }
@@ -236,5 +378,31 @@ export const jiraToolSchemas = {
     transitionId: z.string().describe("The ID of the transition to perform. Use jira_getTransitions to find available transitions and their IDs."),
     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"),
+    outwardIssueKey: z.string().describe("Key of the outward issue (the one the outward link description applies to, e.g. the issue that 'blocks'). Example: PROJ-456"),
+    linkType: z.string().describe("Name of the issue link type to apply (e.g. 'Blocks', 'Relates', 'Duplicate'). Use jira_getIssueLinkTypes to discover valid names for this JIRA installation."),
+    comment: z.string().optional().describe("Optional comment added to the inward issue when the link is created, in JIRA Wiki Markup.")
+  },
+  unlinkIssues: {
+    linkId: z.string().describe("The id of the issue link to delete. Link ids can be found in the 'issuelinks' field of an issue (retrieve it via jira_getIssue with the 'issuelinks' field).")
   }
 };