@stubbedev/atlassian-mcp 0.2.11 → 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();
@@ -371,6 +392,24 @@ export class BitbucketClient {
         });
         return text(`${data.values.length} user(s)${pageHint(data)}:\n${lines.join('\n')}`);
     }
+    async searchUsersRaw(args) {
+        const params = new URLSearchParams();
+        if (args.query)
+            params.set('filter', args.query);
+        params.set('limit', String(args.limit ?? 50));
+        let path;
+        if (args.projectKey && args.repoSlug) {
+            path = `${this.rp(args.projectKey, args.repoSlug)}/permissions/users?${params}`;
+        }
+        else if (args.projectKey) {
+            path = `/projects/${encodeURIComponent(args.projectKey)}/permissions/users?${params}`;
+        }
+        else {
+            path = `/users?${params}`;
+        }
+        const data = await this.request('GET', path);
+        return (data?.values ?? []).map((entry) => entry.user ?? entry);
+    }
     async listPullRequests(args) {
         const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
         const { state = 'OPEN', fromBranch, text: searchText, limit = 25, start = 0 } = args;
@@ -448,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 = [
@@ -503,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')}`);
                 }
@@ -513,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)');
                 }
@@ -523,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)'}`);
@@ -761,6 +814,46 @@ 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('/');
+            const content = await this.requestText(`${this.rp(projectKey, repoSlug)}/raw/${encoded}`);
+            return content;
+        }
+        catch {
+            return null;
+        }
+    }
     async getPrComments(args) {
         const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
         const limit = args.limit ?? 50;

package/dist/index.js

@@ -132,18 +132,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         ...(jira ? [
             {
                 name: 'start_work',
-                description: 'Start working on a Jira ticket: fetches the ticket, creates a local git branch with an auto-generated name (e.g. feature/FOO-123-add-payment-gateway), and optionally transitions the ticket. Use when told "make a branch for FOO-123", "start working on this ticket", "check out a branch for this issue", or "begin work on FOO-123".',
+                description: 'Start working on a Jira ticket end-to-end: resolves the ticket (by key or free-text search with a picker when multiple match), creates a local branch with an auto-generated name, fetches the project README from Bitbucket so you have commit/PR conventions in context, and prints a ready-to-use next-steps summary. Use when told "make a branch for FOO-123", "start working on this ticket", "I want to work on the login bug", or "begin work on the payment gateway story". If issueKey is omitted, provide query for free-text search.',
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        issueKey: { type: 'string', description: 'Jira issue key, e.g. FOO-123' },
+                        issueKey: { type: 'string', description: 'Jira issue key, e.g. FOO-123 (provide this OR query)' },
+                        query: { type: 'string', description: 'Free-text search when issueKey is unknown — shows a picker if multiple tickets match' },
                         repoPath: { type: 'string', description: 'Local repo path (defaults to cwd)' },
                         baseBranch: { type: 'string', description: 'Branch to base off (default: master)' },
                         branchName: { type: 'string', description: 'Override the generated branch name' },
                         transitionName: { type: 'string', description: 'Jira transition to apply, e.g. "In Progress" (optional)' },
                         push: { type: 'boolean', description: 'Push branch to remote after creation (default false)', default: false },
                     },
-                    required: ['issueKey'],
                 },
             },
             {
@@ -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: {
@@ -332,6 +346,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                                 fromBranch: { type: 'string', description: 'Source branch (defaults to current branch)' },
                                 toBranch: { type: 'string', description: 'Target branch (default: master)' },
                                 reviewers: { type: 'array', items: { type: 'string' }, description: 'Reviewer usernames. Use bitbucket_search resource=users to look up valid usernames before setting this.' },
+                                pickReviewers: { type: 'boolean', description: 'Show an interactive reviewer picker before creating the PR (lists users with repo access)' },
                             },
                             required: ['title'],
                         },
@@ -392,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.',
@@ -462,8 +495,69 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (!jira)
                     throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
                 const a = args;
-                const fields = await jira.getIssueFields(a.issueKey);
-                const branchName = a.branchName ?? slugifyBranchName(a.issueKey, fields.summary, fields.type);
+                if (!a.issueKey && !a.query) {
+                    throw new Error('Provide issueKey (e.g. FOO-123) or query (free-text search).');
+                }
+                // Resolve issueKey from free-text query if not provided directly
+                let issueKey = a.issueKey;
+                if (!issueKey && a.query) {
+                    const candidates = await jira.findIssues(a.query, 10);
+                    if (candidates.length === 0) {
+                        return { content: [{ type: 'text', text: `No Jira tickets found for: "${a.query}"` }] };
+                    }
+                    if (candidates.length === 1) {
+                        issueKey = candidates[0].key;
+                    }
+                    else {
+                        // Multiple matches — present a picker
+                        const pickerMessage = [
+                            `Found ${candidates.length} tickets matching "${a.query}". Which one do you want to work on?`,
+                            ...candidates.map((c, i) => `${i + 1}. [${c.key}] ${c.summary} (${c.status})`),
+                        ].join('\n');
+                        try {
+                            const pickerResult = await server.elicitInput({
+                                message: pickerMessage,
+                                requestedSchema: {
+                                    type: 'object',
+                                    properties: {
+                                        ticket: {
+                                            type: 'string',
+                                            title: 'Select a ticket',
+                                            oneOf: [
+                                                ...candidates.map((c) => ({ const: c.key, title: `[${c.key}] ${c.summary}` })),
+                                                { const: '__cancel__', title: 'Cancel' },
+                                            ],
+                                        },
+                                    },
+                                    required: ['ticket'],
+                                },
+                            });
+                            if (pickerResult.action === 'cancel' ||
+                                pickerResult.action === 'decline' ||
+                                pickerResult.content?.ticket === '__cancel__') {
+                                return { content: [{ type: 'text', text: 'Cancelled.' }] };
+                            }
+                            issueKey = pickerResult.content?.ticket;
+                            if (!issueKey || issueKey === '__cancel__') {
+                                return { content: [{ type: 'text', text: 'Cancelled.' }] };
+                            }
+                        }
+                        catch {
+                            // Client doesn't support elicitation — list options and ask caller to retry with issueKey
+                            const list = candidates.map((c) => `  • ${c.key} — ${c.summary} (${c.status})`).join('\n');
+                            return {
+                                content: [{
+                                        type: 'text',
+                                        text: `Found ${candidates.length} tickets matching "${a.query}":\n${list}\n\nRe-run start_work with the desired issueKey.`,
+                                    }],
+                            };
+                        }
+                    }
+                }
+                if (!issueKey)
+                    throw new Error('Could not resolve issue key.');
+                const fields = await jira.getIssueFields(issueKey);
+                const branchName = a.branchName ?? slugifyBranchName(issueKey, fields.summary, fields.type);
                 const repoPath = a.repoPath ?? process.cwd();
                 // Check if branch already exists on remote before creating
                 const remote = checkRemoteBranch(branchName, repoPath);
@@ -475,7 +569,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     const contextLines = [authorLine, commitLine].filter(Boolean).join('\n');
                     const message = [
                         `Branch "${branchName}" already exists on remote.`,
-                        `Ticket: ${a.issueKey} — ${fields.summary}`,
+                        `Ticket: ${issueKey} — ${fields.summary}`,
                         contextLines,
                     ].filter(Boolean).join('\n');
                     try {
@@ -509,7 +603,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             if (chosen === 'cancel') {
                                 return { content: [{ type: 'text', text: 'Cancelled.' }] };
                             }
-                            // new_name — instruct the model to re-run with a custom name
                             return {
                                 content: [{
                                         type: 'text',
@@ -517,11 +610,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                     }],
                             };
                         }
-                        // Fallback: unknown action
                         return { content: [{ type: 'text', text: 'Cancelled.' }] };
                     }
                     catch {
-                        // Client doesn't support elicitation — fall back to informational text
                         return {
                             content: [{
                                     type: 'text',
@@ -543,21 +634,52 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     push: a.push ?? false,
                 });
                 const lines = [
-                    `Ticket:  ${a.issueKey} — ${fields.summary}`,
+                    `Ticket:  ${issueKey} — ${fields.summary}`,
                     `Status:  ${fields.status}`,
                     branchResult.content[0].text,
                 ];
                 if (a.transitionName) {
                     try {
-                        await jira.mutateIssue({ issueKey: a.issueKey, transitionName: a.transitionName });
+                        await jira.mutateIssue({ issueKey, transitionName: a.transitionName });
                         lines.push(`Jira:    transitioned → ${a.transitionName}`);
                     }
                     catch (err) {
                         lines.push(`Jira:    could not transition — ${err.message}`);
                     }
                 }
-                if (bitbucket)
-                    lines.push(``, `Next: push commits then use bitbucket_mutate to open a PR.`);
+                // Fetch README from Bitbucket for project conventions
+                if (bitbucket) {
+                    try {
+                        const remoteUrl = (() => {
+                            try {
+                                return execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: repoPath, encoding: 'utf-8' }).trim();
+                            }
+                            catch {
+                                return '';
+                            }
+                        })();
+                        const parsed = parseBitbucketRemote(remoteUrl);
+                        if (parsed) {
+                            const readme = await bitbucket.fetchFileText(parsed.projectKey, parsed.repoSlug, 'README.md');
+                            if (readme) {
+                                const maxLen = 4000;
+                                const truncated = readme.length > maxLen ? readme.slice(0, maxLen) + '\n... (truncated)' : readme;
+                                lines.push('');
+                                lines.push('Project conventions (from README.md):');
+                                lines.push('────────────────────────────────────');
+                                lines.push(truncated);
+                                lines.push('────────────────────────────────────');
+                                lines.push('Follow the conventions above when writing commit messages and the PR description.');
+                            }
+                        }
+                    }
+                    catch { /* README fetch is best-effort */ }
+                    lines.push('');
+                    lines.push('Next steps:');
+                    lines.push('  1. Make your changes and commit following the project conventions.');
+                    lines.push('  2. Use bitbucket_mutate (create) to open a PR — the Jira summary and ticket key make a good title/description starting point.');
+                    lines.push('  3. Add reviewers: bitbucket_search resource=users to find colleagues, or pass pickReviewers=true in create to get an interactive picker.');
+                }
                 return { content: [{ type: 'text', text: lines.join('\n') }] };
             }
             // Jira
@@ -591,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}`);
@@ -636,6 +764,42 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return await bitbucket.declinePr({ ...a, message: a.declineMessage });
                 if (action === 'merge')
                     return await bitbucket.mergePr({ ...a, message: a.mergeMessage, mergeStrategy: a.mergeStrategy });
+                // Handle interactive reviewer picker for PR creation
+                const createArgs = a.create;
+                if (createArgs?.pickReviewers && !a.prId) {
+                    const projectKey = a.projectKey;
+                    const repoSlug = a.repoSlug;
+                    const users = await bitbucket.searchUsersRaw({ projectKey, repoSlug, limit: 30 });
+                    if (users.length > 0) {
+                        // Build boolean checkbox schema — one field per user
+                        // key must be safe for JSON schema property names
+                        const toSchemaKey = (uname) => uname.replace(/[^a-zA-Z0-9]/g, '_');
+                        const userMap = new Map(); // schemaKey -> username
+                        const properties = {};
+                        for (const u of users) {
+                            const key = toSchemaKey(u.name);
+                            userMap.set(key, u.name);
+                            properties[key] = { type: 'boolean', title: `${u.displayName} (${u.name})` };
+                        }
+                        try {
+                            const pickerResult = await server.elicitInput({
+                                message: 'Select reviewers to add to this PR:',
+                                requestedSchema: { type: 'object', properties },
+                            });
+                            if (pickerResult.action === 'accept' && pickerResult.content) {
+                                const selected = [];
+                                for (const [key, username] of userMap) {
+                                    if (pickerResult.content[key] === true)
+                                        selected.push(username);
+                                }
+                                createArgs.reviewers = selected;
+                            }
+                        }
+                        catch {
+                            // elicitation not supported — proceed without reviewer picker
+                        }
+                    }
+                }
                 return await bitbucket.mutatePullRequest(a);
             }
             case 'bitbucket_comment': {
@@ -653,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) {
@@ -285,6 +286,22 @@ export class JiraClient {
         const page = pagination(data.total, startAt, data.issues.length);
         return text(`Found ${data.total} issues${page}:\n${lines.join('\n')}`);
     }
+    async findIssues(query, maxResults = 10) {
+        const jql = buildJQL({ query });
+        const params = new URLSearchParams({
+            jql,
+            maxResults: String(maxResults),
+            startAt: '0',
+            fields: 'summary,status,issuetype',
+        });
+        const data = await this.request('GET', `/search?${params}`);
+        return (data?.issues ?? []).map((i) => ({
+            key: i.key,
+            summary: i.fields.summary,
+            status: i.fields.status.name,
+            type: i.fields.issuetype.name,
+        }));
+    }
     async myIssues(args) {
         return this.searchIssues({
             jql: 'assignee = currentUser() ORDER BY updated DESC',
@@ -381,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.');
@@ -435,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 ?? [];
@@ -701,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.11",
+  "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",