@stubbedev/atlassian-mcp 0.2.12 → 0.3.1

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();
@@ -216,6 +237,9 @@ export class BitbucketClient {
         this.currentUsernameCache = username;
         return username;
     }
+    async whoami() {
+        return this.getCurrentUsername();
+    }
     /** Returns a URL-safe `/projects/.../repos/...` prefix for REST paths. */
     rp(projectKey, repoSlug) {
         return `/projects/${encodeURIComponent(projectKey)}/repos/${encodeURIComponent(repoSlug)}`;
@@ -466,6 +490,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 +547,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 +559,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 +571,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 +817,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/context.js

@@ -9,6 +9,27 @@ function safeExec(cmd, cwd) {
         return '';
     }
 }
+/** Top recent committers from the last `lookback` commits, ranked by count. */
+export function getTopCommitters(repoPath, lookback = 50, top = 5) {
+    const raw = safeExec(`git log -n ${lookback} --format=%aN%x09%aE`, repoPath);
+    if (!raw)
+        return [];
+    const counts = new Map();
+    for (const line of raw.split('\n')) {
+        const [name, email] = line.split('\t');
+        if (!name)
+            continue;
+        const key = (email || name).toLowerCase();
+        const existing = counts.get(key);
+        if (existing)
+            existing.commits++;
+        else
+            counts.set(key, { name, email: email ?? '', commits: 1 });
+    }
+    return [...counts.values()]
+        .sort((a, b) => b.commits - a.commits)
+        .slice(0, top);
+}
 /**
  * Unified developer context: git state + linked Jira issues + open PR for current branch.
  * Either jira or bitbucket may be null when only one product is configured.
@@ -20,6 +41,8 @@ export async function getDevContext(args, jira, bitbucket) {
     const remote = safeExec('git remote get-url origin', repoPath) || '(no remote)';
     const recentCommits = safeExec('git log --oneline -5', repoPath) || '(none)';
     const status = safeExec('git status --short', repoPath) || '(clean)';
+    const committers = getTopCommitters(repoPath, 50, 5);
+    const parsed = bitbucket?.isRemoteForThisInstance(remote) ? parseBitbucketRemote(remote) : null;
     // Upstream ahead/behind
     const upstream = safeExec('git rev-parse --abbrev-ref @{u}', repoPath);
     let upstreamLine = '';
@@ -35,18 +58,40 @@ export async function getDevContext(args, jira, bitbucket) {
             upstreamLine = `${upstream}${parts.length ? ` (${parts.join(', ')})` : ' (up to date)'}`;
         }
     }
-    sections.push([
+    // Identity — best-effort, parallel
+    const [jiraMe, bbMe] = await Promise.all([
+        jira ? jira.whoami().catch(() => null) : Promise.resolve(null),
+        bitbucket ? bitbucket.whoami().catch(() => null) : Promise.resolve(null),
+    ]);
+    const youParts = [];
+    if (jiraMe)
+        youParts.push(`Jira ${jiraMe.name ?? jiraMe.key ?? '(unknown)'}${jiraMe.displayName ? ` "${jiraMe.displayName}"` : ''}`);
+    if (bbMe)
+        youParts.push(`Bitbucket ${bbMe}`);
+    const headerLines = [
         `Repository: ${repoPath}`,
         `Branch:     ${branch}`,
         ...(upstreamLine ? [`Upstream:   ${upstreamLine}`] : []),
         `Remote:     ${remote}`,
-        '',
-        'Recent commits:',
-        recentCommits,
-        '',
-        'Working tree:',
-        status,
-    ].join('\n'));
+        ...(parsed ? [`Bitbucket:  ${parsed.projectKey}/${parsed.repoSlug}`] : []),
+        ...(youParts.length ? [`You:        ${youParts.join(' · ')}`] : []),
+    ];
+    if (committers.length) {
+        headerLines.push('');
+        headerLines.push('Top recent committers (last 50):');
+        for (const c of committers) {
+            const ident = c.email ? `${c.name} <${c.email}>` : c.name;
+            headerLines.push(`  ${c.commits.toString().padStart(3)} — ${ident}`);
+        }
+        headerLines.push('  (look up usernames via jira_search resource=users / bitbucket_search resource=users — do NOT shell out to git/gh/bb)');
+    }
+    headerLines.push('');
+    headerLines.push('Recent commits:');
+    headerLines.push(recentCommits);
+    headerLines.push('');
+    headerLines.push('Working tree:');
+    headerLines.push(status);
+    sections.push(headerLines.join('\n'));
     // Jira — fetch overview for any tickets referenced in the branch name (parallel)
     const jiraKeys = jira ? [...new Set(branch.match(JIRA_KEY_RE) ?? [])] : [];
     const jiraResults = await Promise.all(jiraKeys.map(async (key) => {
@@ -66,7 +111,6 @@ export async function getDevContext(args, jira, bitbucket) {
     }));
     sections.push(...jiraResults);
     // Bitbucket — find the open PR for this branch (only if remote points to this instance)
-    const parsed = bitbucket?.isRemoteForThisInstance(remote) ? parseBitbucketRemote(remote) : null;
     if (parsed) {
         try {
             const pr = await bitbucket.findOpenPrForBranch(parsed.projectKey, parsed.repoSlug, branch);

package/dist/index.js

@@ -12,7 +12,7 @@ import { loadConfig } from './config.js';
 import { JiraClient } from './jira.js';
 import { BitbucketClient, parseBitbucketRemote } from './bitbucket.js';
 import { getContext, getDiff, createBranch, checkRemoteBranch, checkoutRemoteBranch } from './git.js';
-import { getDevContext } from './context.js';
+import { getDevContext, getTopCommitters } from './context.js';
 function currentGitRemote() {
     try {
         return execFileSync('git', ['remote', 'get-url', 'origin'], { encoding: 'utf-8' }).trim();
@@ -21,6 +21,14 @@ function currentGitRemote() {
         return '';
     }
 }
+function currentGitBranch() {
+    try {
+        return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return '';
+    }
+}
 function remoteMatchesBitbucketInstance(remote, bitbucketUrl) {
     if (!remote)
         return false;
@@ -39,7 +47,57 @@ const bitbucket = (config.bitbucket && remoteMatchesBitbucketInstance(_remote, c
 if (config.bitbucket && !bitbucket) {
     console.error(`[atlassian-mcp] Bitbucket configured but remote "${_remote || '(none)'}" does not match ${config.bitbucket.url} — Bitbucket tools disabled for this repo.`);
 }
-const server = new Server({ name: 'atlassian-mcp', version: _pkg.version }, { capabilities: { tools: {} } });
+async function buildInstructions() {
+    const branch = currentGitBranch();
+    const isGitRepo = branch !== '';
+    const jiraKeys = isGitRepo ? [...new Set(branch.match(/\b[A-Z][A-Z0-9]+-\d+\b/g) ?? [])] : [];
+    const parsed = bitbucket && _remote ? parseBitbucketRemote(_remote) : null;
+    const committers = isGitRepo ? getTopCommitters(process.cwd(), 50, 5) : [];
+    const [jiraMe, bbMe] = await Promise.all([
+        jira ? jira.whoami().catch(() => null) : Promise.resolve(null),
+        bitbucket ? bitbucket.whoami().catch(() => null) : Promise.resolve(null),
+    ]);
+    const lines = [];
+    lines.push('# atlassian-mcp');
+    lines.push('');
+    lines.push('Self-hosted Jira + Bitbucket Server tooling. Prefer these tools over shelling out to `git log`, `gh`, or any `bitbucket`/`bb` CLI for anything that touches tickets, PRs, reviewers, comments, or user lookups.');
+    lines.push('');
+    lines.push('## Configured services');
+    lines.push(`- Jira:      ${jira ? config.jira.url : '(not configured)'}${jiraMe ? ` — you are ${jiraMe.name ?? jiraMe.key ?? '?'}${jiraMe.displayName ? ` "${jiraMe.displayName}"` : ''}` : ''}`);
+    lines.push(`- Bitbucket: ${bitbucket ? config.bitbucket.url : (config.bitbucket ? `${config.bitbucket.url} — DISABLED for this cwd (remote does not match)` : '(not configured)')}${bbMe ? ` — you are ${bbMe}` : ''}`);
+    lines.push('');
+    if (isGitRepo) {
+        lines.push('## Current repo');
+        lines.push(`- Branch: ${branch} (may have changed since startup — re-run \`get_dev_context\` to refresh)`);
+        lines.push(`- Remote: ${_remote || '(none)'}`);
+        if (parsed)
+            lines.push(`- Bitbucket repo: ${parsed.projectKey}/${parsed.repoSlug}`);
+        if (jiraKeys.length)
+            lines.push(`- Jira keys in branch: ${jiraKeys.join(', ')}`);
+    }
+    else {
+        lines.push('## Current repo');
+        lines.push('- Not a git repository.');
+    }
+    if (committers.length) {
+        lines.push('');
+        lines.push('## Recent committers in this repo (last 50 commits)');
+        for (const c of committers) {
+            const ident = c.email ? `${c.name} <${c.email}>` : c.name;
+            lines.push(`- ${c.commits}× ${ident}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Use these tools — do NOT shell out');
+    lines.push('- "What am I working on / what\'s the status / show me the context" → call `get_dev_context` first. It returns branch state, linked Jira tickets, the open PR, and reviewer status in one shot.');
+    lines.push('- Looking up a person\'s username (for reviewers, assignees, mentions) → ALWAYS use `bitbucket_search resource=users` or `jira_search resource=users`. NEVER use `git log`/`git shortlog`/`gh api`/`bb`/any bitbucket CLI to discover who someone is — those return commit-author strings, not Bitbucket/Jira usernames, and the wrong identifier breaks reviewer assignment.');
+    lines.push('- Reading a Jira ticket → `jira_get` (single) or `jira_search` (many). Mutating → `jira_mutate`.');
+    lines.push('- Reading a PR → `bitbucket_get_pr`. Creating/updating/merging → `bitbucket_mutate`. Commenting → `bitbucket_comment`.');
+    lines.push('- Starting work on a ticket (branch + status transition + README) → `start_work`. Closing it (merge + transition) → `complete_work`.');
+    return lines.join('\n');
+}
+const _instructions = await buildInstructions();
+const server = new Server({ name: 'atlassian-mcp', version: _pkg.version }, { capabilities: { tools: {} }, instructions: _instructions });
 server.onerror = (error) => console.error('[MCP Error]', error);
 function normalizeBitbucketArgs(args) {
     const src = (args && typeof args === 'object') ? args : {};
@@ -170,7 +228,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 +304,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 +358,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 +465,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 +771,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 +875,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) {
@@ -148,6 +149,9 @@ export class JiraClient {
         this.currentUserCache = me;
         return me;
     }
+    async whoami() {
+        return this.getCurrentUser();
+    }
     async getIssueLinkingEnabled() {
         if (this.issueLinkingEnabled !== undefined)
             return this.issueLinkingEnabled;
@@ -397,7 +401,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 +455,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 +729,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.1",
   "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",