@stubbedev/atlassian-mcp 0.2.12 → 0.3.0

package/README.md

@@ -28,7 +28,8 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **s
 | Tool | Description |
 |---|---|
 | `jira_search` | Discover resources: `issues`, `projects`, `issue_types`, `boards`, `sprints`, `board_overview`, or `users` via `resource` param |
-| `jira_get` | Full details for one issue: summary, description, status, sprint, transitions, and comments |
+| `jira_get` | Full details for one issue: summary, description, status, sprint, transitions, comments, and attachment list |
+| `jira_get_attachment` | Fetch a Jira attachment by ID; images are auto-resized via sharp and returned inline so the model can see them, text/JSON inline, larger/binary files via `saveTo` |
 | `jira_mutate` | Create, update, transition, comment, link, add to sprint, or log work — all in one call |
 | `jira_comment` | Add, update, or delete a comment on an issue (`action`: `add` / `update` / `delete`) |
 
@@ -37,7 +38,8 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **s
 | Tool | Description |
 |---|---|
 | `bitbucket_search` | Discover resources: `pull_requests` (default), `repos`, or `branches` via `resource` param; `mine=true` for your inbox |
-| `bitbucket_get_pr` | Full PR details: metadata, commits, comments, blockers, build status, and optional diff |
+| `bitbucket_get_pr` | Full PR details: metadata, commits, comments, blockers, build status, optional diff, and any attachments referenced from the description or comments |
+| `bitbucket_get_attachment` | Fetch a repo attachment by ID (images auto-resized inline via sharp; text inline; binary/large via `saveTo`) |
 | `bitbucket_mutate` | Create/update a PR, or perform lifecycle actions: `approve`, `unapprove`, `merge`, `decline` |
 | `bitbucket_comment` | Add, update, or delete a PR comment; for code changes use `suggestion` so Bitbucket shows Apply suggestion (no trailing text after a suggestion block) |
 | `bitbucket_get_file` | Raw file content from Bitbucket at a branch, tag, or commit |
@@ -239,6 +241,10 @@ npm install
 
 Then use `node /path/to/atlassian-mcp/dist/index.js` instead of the `npx` command in the configs above.
 
+### Native dependency: `sharp`
+
+Image attachments are downscaled and re-encoded with [`sharp`](https://sharp.pixelplumbing.com/) before being returned to the model so they fit in context. Sharp ships prebuilt binaries for glibc Linux (x64/arm64), macOS, and Windows — no extra setup needed on those. Alpine / musl users may need `npm install --cpu=x64 --os=linux --libc=musl sharp`.
+
 ---
 
 ## Releases (Maintainers)

package/dist/attachment.js

@@ -0,0 +1,109 @@
+import sharp from 'sharp';
+import { writeFile } from 'fs/promises';
+import { resolve as resolvePath } from 'path';
+export const MAX_INLINE_BYTES = 10 * 1024 * 1024;
+export const DEFAULT_MAX_DIMENSION = 1568;
+export const DEFAULT_JPEG_QUALITY = 85;
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+export function isTextMime(mimeType) {
+    const mt = mimeType.toLowerCase();
+    if (mt.startsWith('text/'))
+        return true;
+    return [
+        'application/json',
+        'application/xml',
+        'application/javascript',
+        'application/x-yaml',
+        'application/yaml',
+        'application/x-sh',
+        'application/sql',
+    ].some((m) => mt === m || mt.startsWith(`${m};`));
+}
+async function processImage(buffer, mimeType, opts) {
+    // SVG: pass through. Sharp can rasterize but the LLM benefits more from the source markup.
+    if (mimeType.toLowerCase() === 'image/svg+xml') {
+        return { data: buffer, mimeType, resized: false };
+    }
+    const img = sharp(buffer, { failOn: 'none' }).rotate();
+    const meta = await img.metadata();
+    const width = meta.width ?? 0;
+    const height = meta.height ?? 0;
+    const longEdge = Math.max(width, height);
+    const needsResize = longEdge > opts.maxDimension;
+    let pipeline = img;
+    if (needsResize) {
+        pipeline = pipeline.resize({
+            width: width >= height ? opts.maxDimension : undefined,
+            height: height > width ? opts.maxDimension : undefined,
+            fit: 'inside',
+            withoutEnlargement: true,
+        });
+    }
+    const hasAlpha = meta.hasAlpha ?? false;
+    if (hasAlpha) {
+        const data = await pipeline.png({ compressionLevel: 9 }).toBuffer();
+        return { data, mimeType: 'image/png', resized: needsResize };
+    }
+    const data = await pipeline.jpeg({ quality: opts.quality, mozjpeg: true }).toBuffer();
+    return { data, mimeType: 'image/jpeg', resized: needsResize };
+}
+export async function buildAttachmentResult(args) {
+    const { id, filename, mimeType, buffer, saveTo } = args;
+    const sizeLabel = formatBytes(buffer.length);
+    const header = `${filename} — ${mimeType}, ${sizeLabel}`;
+    if (saveTo) {
+        const path = resolvePath(saveTo);
+        await writeFile(path, buffer);
+        return { content: [{ type: 'text', text: `Saved attachment #${id} (${header}) to ${path}` }] };
+    }
+    const mt = mimeType.toLowerCase();
+    if (mt.startsWith('image/')) {
+        if (buffer.length > MAX_INLINE_BYTES) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `${header}\nAttachment #${id} exceeds the ${formatBytes(MAX_INLINE_BYTES)} input cap. Pass saveTo=/absolute/path to write it to disk.`,
+                    }],
+            };
+        }
+        const maxDimension = args.maxDimension ?? DEFAULT_MAX_DIMENSION;
+        const quality = args.quality ?? DEFAULT_JPEG_QUALITY;
+        try {
+            const processed = await processImage(buffer, mimeType, { maxDimension, quality });
+            const resizedNote = processed.resized
+                ? ` (resized to ${maxDimension}px long edge, re-encoded to ${formatBytes(processed.data.length)})`
+                : processed.data.length < buffer.length
+                    ? ` (re-encoded to ${formatBytes(processed.data.length)})`
+                    : '';
+            return {
+                content: [
+                    { type: 'text', text: `Attachment #${id}: ${header}${resizedNote}` },
+                    { type: 'image', data: processed.data.toString('base64'), mimeType: processed.mimeType },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `${header}\nFailed to process image: ${err.message}. Pass saveTo to write the original to disk.`,
+                    }],
+            };
+        }
+    }
+    if (isTextMime(mt) && buffer.length <= MAX_INLINE_BYTES) {
+        return { content: [{ type: 'text', text: `Attachment #${id}: ${header}\n\n${buffer.toString('utf-8')}` }] };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: `${header}\nAttachment #${id} is${buffer.length > MAX_INLINE_BYTES ? ` larger than ${formatBytes(MAX_INLINE_BYTES)} or` : ''} not inline-renderable. Pass saveTo=/absolute/path to write it to disk.`,
+            }],
+    };
+}

package/dist/bitbucket.js

@@ -1,5 +1,26 @@
 import { execSync } from 'child_process';
+import { buildAttachmentResult } from './attachment.js';
 const EMOJI_RE = /\p{Extended_Pictographic}/u;
+const ATTACHMENT_REF_RE = /!?\[([^\]]*)\]\(attachment:(\d+)\)/g;
+function collectAttachmentRefs(input, source, out) {
+    if (!input)
+        return;
+    ATTACHMENT_REF_RE.lastIndex = 0;
+    let match;
+    while ((match = ATTACHMENT_REF_RE.exec(input)) !== null) {
+        const id = match[2];
+        if (!out.has(id)) {
+            out.set(id, { id, filename: match[1] || '(unnamed)', source });
+        }
+    }
+}
+function collectFromCommentTree(comment, out) {
+    if (comment.deleted)
+        return;
+    collectAttachmentRefs(comment.text, `comment #${comment.id}`, out);
+    for (const reply of comment.comments ?? [])
+        collectFromCommentTree(reply, out);
+}
 function safeExec(cmd) {
     try {
         return execSync(cmd, { encoding: 'utf-8' }).trim();
@@ -466,6 +487,8 @@ export class BitbucketClient {
         if (!pr)
             return text('Pull request not found.');
         const sections = [];
+        const attachmentRefs = new Map();
+        collectAttachmentRefs(pr.description, 'description', attachmentRefs);
         const reviewers = pr.reviewers.map((r) => `${r.user.displayName}${r.approved ? ' ✓' : ''}`).join(', ');
         const url = pr.links?.self?.[0]?.href;
         const header = [
@@ -521,6 +544,8 @@ export class BitbucketClient {
                     sections.push(`Comments:\n(no ${commentsState} BLOCKER comments)`);
                 }
                 else {
+                    for (const comment of data.values)
+                        collectFromCommentTree(comment, attachmentRefs);
                     const blocks = data.values.flatMap((comment) => formatCommentThread(comment));
                     sections.push(`Comments (${data.values.length} BLOCKER thread(s))${pageHint(data)}:\n\n${blocks.join('\n\n')}`);
                 }
@@ -531,6 +556,8 @@ export class BitbucketClient {
                     const matchesState = commentMatchesState(comment, commentsState);
                     return matchesState && commentMatchesSeverity(comment, commentsSeverity);
                 });
+                for (const comment of comments)
+                    collectFromCommentTree(comment, attachmentRefs);
                 if (comments.length === 0) {
                     sections.push('Comments:\n(no matching comments)');
                 }
@@ -541,6 +568,14 @@ export class BitbucketClient {
                 }
             }
         }
+        if (attachmentRefs.size > 0) {
+            const lines = [`Attachments referenced: ${attachmentRefs.size}`];
+            for (const ref of attachmentRefs.values()) {
+                lines.push(`  #${ref.id} ${ref.filename} — in ${ref.source}`);
+            }
+            lines.push('Use bitbucket_get_attachment with attachmentId to view contents.');
+            sections.push(lines.join('\n'));
+        }
         if (includeDiff) {
             const data = await this.request('GET', `${this.rp(projectKey, repoSlug)}/pull-requests/${prId}/diff`);
             sections.push(`Diff:\n${data ? formatDiff(data, args.diffMaxChars ?? 8000) : '(no diff found)'}`);
@@ -779,6 +814,36 @@ export class BitbucketClient {
         }
         return text(content);
     }
+    async getAttachment(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const id = String(args.attachmentId ?? '').trim();
+        if (!id)
+            throw new Error('attachmentId is required.');
+        const url = `${this.baseUrl}/rest/api/1.0${this.rp(projectKey, repoSlug)}/attachments/${encodeURIComponent(id)}`;
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: { Authorization: this.headers.Authorization },
+            signal: AbortSignal.timeout(60_000),
+        });
+        if (!res.ok) {
+            const errText = await res.text();
+            throw new Error(formatBitbucketError(res.status, 'GET', `${this.rp(projectKey, repoSlug)}/attachments/${id}`, parseBitbucketErrorDetails(errText)));
+        }
+        const buffer = Buffer.from(await res.arrayBuffer());
+        const contentDisposition = res.headers.get('content-disposition') ?? '';
+        const filenameMatch = contentDisposition.match(/filename\*?=(?:UTF-8'')?"?([^";]+)"?/i);
+        const filename = filenameMatch ? decodeURIComponent(filenameMatch[1]) : `attachment-${id}`;
+        const mimeType = (res.headers.get('content-type') ?? 'application/octet-stream').split(';')[0].trim();
+        return buildAttachmentResult({
+            id,
+            filename,
+            mimeType,
+            buffer,
+            saveTo: args.saveTo,
+            maxDimension: args.maxDimension,
+            quality: args.quality,
+        });
+    }
     async fetchFileText(projectKey, repoSlug, filePath) {
         try {
             const encoded = filePath.split('/').map(encodeURIComponent).join('/');

package/dist/index.js

@@ -170,7 +170,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             },
             {
                 name: 'jira_get',
-                description: 'Full details for one Jira issue: summary, description, status, assignee, sprint, available transitions, and recent comments. Use when asked to "show me FOO-123", "what does this ticket say", "get the details for this issue", or after discovering a key from get_dev_context or jira_search.',
+                description: 'Full details for one Jira issue: summary, description, status, assignee, sprint, available transitions, recent comments, and a list of attachments (filename, size, mime type, attachment ID). Use when asked to "show me FOO-123", "what does this ticket say", "get the details for this issue", or after discovering a key from get_dev_context or jira_search. To view an attachment\'s contents (e.g. an image), call jira_get_attachment with the attachment ID surfaced here.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -246,6 +246,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     },
                 },
             },
+            {
+                name: 'jira_get_attachment',
+                description: 'Fetch a Jira attachment by ID and return its contents inline. Images are auto-resized (long edge ≤1568 px by default) and re-encoded so they fit in context, then returned as image content blocks (so you can see them); text/JSON/XML come back as text. For binary types (PDF, zip, office docs) or files larger than 10 MB, pass saveTo=/absolute/path to write the original file to disk and then read it locally. For screenshots of code or other detail-heavy images, raise maxDimension. Use jira_get first to discover attachment IDs.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        attachmentId: { type: 'string', description: 'Numeric attachment ID from jira_get output' },
+                        saveTo: { type: 'string', description: 'Optional absolute path to save the original (un-resized) file to disk instead of returning inline' },
+                        maxDimension: { type: 'number', description: 'Max long-edge size in pixels for inline images (default 1568). Larger images are downscaled with sharp.' },
+                        quality: { type: 'number', description: 'JPEG quality for re-encoded inline images (1-100, default 85). Ignored for images with alpha (encoded as PNG).' },
+                    },
+                    required: ['attachmentId'],
+                },
+            },
             {
                 name: 'jira_comment',
                 description: `Add, update, or delete a comment on a Jira issue. Use when asked to "edit my comment on FOO-123", "delete comment 12345", or "update that comment". action defaults to "add". Can only edit/delete your own comments. ${JIRA_WIKI_MARKUP_HINT}`,
@@ -286,7 +300,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             },
             {
                 name: 'bitbucket_get_pr',
-                description: 'Full details for one PR: metadata, commits, open comments, blockers, and optional diff. Use when asked to "review this PR", "show me the review comments", "what\'s blocking the merge", or after get_dev_context surfaces a prId. IMPORTANT: The PR branch is often not the locally checked-out branch. Do NOT read files with local tools (Read, git_get_diff, etc.) for PR context — use bitbucket_get_file with the PR\'s source branch instead. The response includes a "Viewing as" line — if it says "you are the author", do NOT add review comments or a summary unless explicitly asked; just answer questions about the PR. If it says "you are a reviewer", default to posting inline comments for suggested changes and a final summary comment.',
+                description: 'Full details for one PR: metadata, commits, open comments, blockers, optional diff, and any attachments referenced from the description or comments (with attachment ID + filename). Use when asked to "review this PR", "show me the review comments", "what\'s blocking the merge", or after get_dev_context surfaces a prId. IMPORTANT: The PR branch is often not the locally checked-out branch. Do NOT read files with local tools (Read, git_get_diff, etc.) for PR context — use bitbucket_get_file with the PR\'s source branch instead. To view an attachment\'s contents, call bitbucket_get_attachment with the surfaced attachment ID. The response includes a "Viewing as" line — if it says "you are the author", do NOT add review comments or a summary unless explicitly asked; just answer questions about the PR. If it says "you are a reviewer", default to posting inline comments for suggested changes and a final summary comment.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -393,6 +407,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     required: ['path'],
                 },
             },
+            {
+                name: 'bitbucket_get_attachment',
+                description: 'Fetch a Bitbucket repo attachment by ID and return its contents inline. Bitbucket Server attachments are repo-scoped and referenced from PR descriptions/comments via attachment:<id> markdown. Use bitbucket_get_pr first to surface attachment IDs. Images are auto-resized (long edge ≤1568 px by default) and re-encoded, then returned as image content blocks; text/JSON/XML as text; binary or >10 MB requires saveTo=/absolute/path.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        projectKey: { type: 'string', description: 'Bitbucket project code (usually auto-detected)' },
+                        project: { type: 'string', description: 'Alias for projectKey' },
+                        repoSlug: { type: 'string', description: 'Repository slug (usually auto-detected)' },
+                        repo: { type: 'string', description: 'Alias for repoSlug' },
+                        attachmentId: { type: 'string', description: 'Numeric attachment ID' },
+                        saveTo: { type: 'string', description: 'Optional absolute path to save the original (un-resized) file to disk instead of returning inline' },
+                        maxDimension: { type: 'number', description: 'Max long-edge size in pixels for inline images (default 1568). Larger images are downscaled with sharp.' },
+                        quality: { type: 'number', description: 'JPEG quality for re-encoded inline images (1-100, default 85). Ignored for images with alpha (encoded as PNG).' },
+                    },
+                    required: ['attachmentId'],
+                },
+            },
             {
                 name: 'bitbucket_pr_tasks',
                 description: 'Manage PR tasks (checklist items). Use when asked to "list the tasks on this PR", "create a task for FOO-123", "mark task #5 as done", or "add a checklist item". Tasks are distinct from comments — they appear as a checklist in the PR sidebar.',
@@ -681,6 +713,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (!jira)
                     throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
                 return await jira.mutateIssue(normalizeJiraMutateArgs(args));
+            case 'jira_get_attachment': {
+                if (!jira)
+                    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+                const a = args;
+                return await jira.getAttachment(a);
+            }
             case 'jira_comment': {
                 if (!jira)
                     throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
@@ -779,6 +817,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (!bitbucket)
                     throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
                 return await bitbucket.getFile(normalizeBitbucketArgs(args));
+            case 'bitbucket_get_attachment': {
+                if (!bitbucket)
+                    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+                return await bitbucket.getAttachment(normalizeBitbucketArgs(args));
+            }
             case 'bitbucket_pr_tasks': {
                 if (!bitbucket)
                     throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);

package/dist/jira.js

@@ -1,4 +1,5 @@
 import { execSync } from 'child_process';
+import { buildAttachmentResult, formatBytes } from './attachment.js';
 const JIRA_KEY_IN_BRANCH_RE = /\b([A-Z][A-Z0-9]+)-\d+\b/;
 const EMOJI_RE = /\p{Extended_Pictographic}/u;
 function text(t) {
@@ -397,7 +398,7 @@ export class JiraClient {
         const includeSprint = args.includeSprint ?? true;
         const commentsMaxResults = args.commentsMaxResults ?? 10;
         const commentsStartAt = args.commentsStartAt ?? 0;
-        const fields = 'summary,description,status,assignee,priority,issuetype,labels,components,parent,fixVersions,issuelinks,subtasks';
+        const fields = 'summary,description,status,assignee,priority,issuetype,labels,components,parent,fixVersions,issuelinks,subtasks,attachment';
         const issue = await this.request('GET', `/issue/${encodeURIComponent(args.issueKey)}?fields=${fields}`);
         if (!issue)
             return text('Issue not found.');
@@ -451,6 +452,14 @@ export class JiraClient {
             lines.push(`Transitions: ${names.length > 0 ? names.join(', ') : '(none)'}`);
         }
         lines.push('', 'Description:', f.description ?? '(no description)');
+        if (f.attachment?.length) {
+            lines.push('', `Attachments: ${f.attachment.length}`);
+            for (const att of f.attachment) {
+                const mt = att.mimeType ?? 'application/octet-stream';
+                lines.push(`  #${att.id} ${att.filename} (${mt}, ${formatBytes(att.size)})`);
+            }
+            lines.push('Use jira_get_attachment with attachmentId to view contents.');
+        }
         if (includeComments) {
             const comments = await this.request('GET', `/issue/${encodeURIComponent(args.issueKey)}/comment?startAt=${commentsStartAt}&maxResults=${commentsMaxResults}`);
             const items = comments?.comments ?? [];
@@ -717,6 +726,33 @@ export class JiraClient {
         const page = data.isLast ? '' : ` (use startAt=${(args.startAt ?? 0) + data.values.length} for next page)`;
         return text(`${data.values.length} board(s)${page}:\n${lines.join('\n')}`);
     }
+    async getAttachment(args) {
+        const id = String(args.attachmentId ?? '').trim();
+        if (!id)
+            throw new Error('attachmentId is required.');
+        const meta = await this.request('GET', `/attachment/${encodeURIComponent(id)}`);
+        if (!meta)
+            throw new Error(`Attachment ${id} not found.`);
+        const res = await fetch(meta.content, {
+            method: 'GET',
+            headers: { Authorization: this.headers.Authorization },
+            signal: AbortSignal.timeout(60_000),
+        });
+        if (!res.ok) {
+            const errText = await res.text();
+            throw new Error(formatJiraError(res.status, 'GET', meta.content, parseJiraErrorDetails(errText)));
+        }
+        const buffer = Buffer.from(await res.arrayBuffer());
+        return buildAttachmentResult({
+            id,
+            filename: meta.filename,
+            mimeType: meta.mimeType ?? 'application/octet-stream',
+            buffer,
+            saveTo: args.saveTo,
+            maxDimension: args.maxDimension,
+            quality: args.quality,
+        });
+    }
     async transitionIssue(args) {
         const transitionId = await this.resolveTransitionId(args.issueKey, args.transitionId, args.transitionName);
         await this.transitionIssueInternal(args.issueKey, transitionId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stubbedev/atlassian-mcp",
-  "version": "0.2.12",
+  "version": "0.3.0",
   "description": "MCP server for self-hosted Jira and Bitbucket",
   "license": "MIT",
   "type": "module",
@@ -27,7 +27,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "dotenv": "^17.4.2"
+    "dotenv": "^17.4.2",
+    "sharp": "^0.34.5"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",