@stubbedev/atlassian-mcp 0.3.10 → 0.4.0

package/README.md

@@ -29,7 +29,7 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **s
 |---|---|
 | `jira_search` | Discover resources: `issues`, `projects`, `issue_types`, `boards`, `sprints`, `board_overview`, `versions`, or `users` via `resource` param |
 | `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_get_attachment` | Fetch a Jira attachment by ID. Images, videos, animated images (GIF/APNG/animated WebP), audio, and PDFs are all decoded inline so the model can see/hear them. Text/JSON inline. Oversized or non-renderable attachments are auto-saved to a temp file and the path is returned. `saveTo=/absolute/path` streams the original to disk |
 | `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`) |
 | `jira_version` | Manage fix versions/releases (`action`: `create` / `update` / `release` / `archive` / `delete`) |
@@ -40,7 +40,7 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **s
 |---|---|
 | `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, 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_get_attachment` | Fetch a repo attachment by ID. Same decoding pipeline as `jira_get_attachment` (images, videos, animated images, audio, PDFs). Oversized or non-renderable attachments are auto-saved to a temp file and the path is returned; `saveTo` streams the original to disk |
 | `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 |
@@ -248,9 +248,36 @@ npm install
 
 Then use `node /path/to/atlassian-mcp/dist/index.js` instead of the `npx` command in the configs above.
 
-### Native dependency: `sharp`
+### Attachment decoding pipeline
 
-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`.
+The attachment tools (`jira_get_attachment`, `bitbucket_get_attachment`) decode binary attachments into model-readable content before returning them:
+
+| Input | What gets returned | How |
+| --- | --- | --- |
+| Static images (PNG/JPEG/WebP/AVIF/SVG…) | Resized image content blocks | `sharp` (long edge ≤ `maxDimension`, default 1568) |
+| Animated images (GIF/APNG/animated WebP) | N sampled frames as image content blocks | `ffmpeg-static` + `sharp` (default 6 frames @ 768 px) |
+| Video (mp4/webm/mov/…) | N sampled frames as image content blocks | `ffmpeg-static` + `sharp`. Uniform or scene-change sampling. Re-call with `start`, `end`, `frames`, `mode`, `sceneThreshold` to zoom in |
+| Audio (mp3/wav/ogg/…) | MCP audio content block | passthrough |
+| PDFs | Extracted text — or rasterized pages if text is empty (scanned PDFs) | `unpdf` + `@napi-rs/canvas` |
+| Text-like (json/xml/yaml/…) | Text content block | passthrough |
+| Everything else (or oversized) | Auto-saved to a temp file; path is returned | `os.tmpdir()` with `atlmcp-` prefix |
+
+Auto-saved files are periodically pruned by TTL and total-size quota — see *Environment overrides* below.
+
+### Native dependencies
+
+- [`sharp`](https://sharp.pixelplumbing.com/) — image decode/resize. Ships prebuilt binaries for glibc Linux (x64/arm64), macOS, Windows. Alpine / musl users may need `npm install --cpu=x64 --os=linux --libc=musl sharp`.
+- [`ffmpeg-static`](https://www.npmjs.com/package/ffmpeg-static) + [`ffprobe-static`](https://www.npmjs.com/package/ffprobe-static) — video/audio decode. ~80 MB bundled binary per platform. Override with env vars (below) if you have system ffmpeg.
+- [`@napi-rs/canvas`](https://www.npmjs.com/package/@napi-rs/canvas) + [`unpdf`](https://www.npmjs.com/package/unpdf) — PDF text extraction and page rasterization.
+
+### Environment overrides
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `ATLASSIAN_MCP_FFMPEG_PATH` | Path to `ffmpeg` binary. Overrides `ffmpeg-static`. Use this if you have system ffmpeg or `ffmpeg-static` doesn't ship for your platform (Alpine/musl, some ARM variants). | bundled `ffmpeg-static` |
+| `ATLASSIAN_MCP_FFPROBE_PATH` | Path to `ffprobe` binary. Overrides `ffprobe-static`. | bundled `ffprobe-static` |
+| `ATLASSIAN_MCP_TMP_TTL_DAYS` | Auto-saved attachments older than this are pruned. | `7` |
+| `ATLASSIAN_MCP_TMP_MAX_BYTES` | Total-size quota for auto-saved attachments in `os.tmpdir()`. When exceeded, oldest are evicted. | `1073741824` (1 GB) |
 
 ---
 

package/dist/attachment.js

@@ -1,6 +1,8 @@
 import sharp from 'sharp';
-import { writeFile } from 'fs/promises';
-import { resolve as resolvePath } from 'path';
+import { writeFile, readdir, stat, rm } from 'fs/promises';
+import { resolve as resolvePath, join as joinPath } from 'path';
+import { tmpdir } from 'os';
+import { processVideo, DEFAULT_VIDEO_FRAMES, DEFAULT_VIDEO_MAX_DIMENSION, DEFAULT_VIDEO_QUALITY, MAX_VIDEO_SOURCE_BYTES, } from './video.js';
 export const MAX_INLINE_BYTES = 10 * 1024 * 1024;
 export const DEFAULT_MAX_DIMENSION = 1568;
 export const DEFAULT_JPEG_QUALITY = 85;
@@ -26,7 +28,6 @@ export function isTextMime(mimeType) {
     ].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 };
     }
@@ -53,6 +54,138 @@ async function processImage(buffer, mimeType, opts) {
     const data = await pipeline.jpeg({ quality: opts.quality, mozjpeg: true }).toBuffer();
     return { data, mimeType: 'image/jpeg', resized: needsResize };
 }
+function sanitizeFilename(name) {
+    return name.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 80) || 'attachment';
+}
+// --- Auto-saved temp file retention --------------------------------------
+// Auto-saved attachments accumulate in os.tmpdir() with prefix `atlmcp-`.
+// We prune on each save (with a 1h cooldown) using two policies:
+//   1. TTL: delete files whose mtime is older than ATLASSIAN_MCP_TMP_TTL_DAYS.
+//   2. Quota: if total size of remaining `atlmcp-*` files exceeds
+//      ATLASSIAN_MCP_TMP_MAX_BYTES, evict oldest-mtime-first until under cap.
+// Both knobs default to sane values if unset. Cleanup runs *before* the new
+// write so we never delete the file we're about to create.
+const TMP_PREFIX = 'atlmcp-';
+const TMP_PRUNE_COOLDOWN_MS = 60 * 60 * 1000;
+const tmpTtlMs = (() => {
+    const days = parseFloat(process.env.ATLASSIAN_MCP_TMP_TTL_DAYS ?? '');
+    return (Number.isFinite(days) && days > 0 ? days : 7) * 24 * 60 * 60 * 1000;
+})();
+const tmpMaxBytes = (() => {
+    const v = parseInt(process.env.ATLASSIAN_MCP_TMP_MAX_BYTES ?? '', 10);
+    return Number.isFinite(v) && v > 0 ? v : 1024 * 1024 * 1024;
+})();
+let lastPruneAt = 0;
+async function pruneTmpFiles() {
+    const now = Date.now();
+    if (now - lastPruneAt < TMP_PRUNE_COOLDOWN_MS)
+        return;
+    lastPruneAt = now;
+    const dir = tmpdir();
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return;
+    }
+    const survivors = [];
+    for (const name of entries) {
+        if (!name.startsWith(TMP_PREFIX))
+            continue;
+        const p = joinPath(dir, name);
+        try {
+            const st = await stat(p);
+            if (!st.isFile())
+                continue;
+            if (now - st.mtimeMs > tmpTtlMs) {
+                await rm(p, { force: true });
+                continue;
+            }
+            survivors.push({ path: p, size: st.size, mtime: st.mtimeMs });
+        }
+        catch { /* ignore — file may have vanished mid-scan */ }
+    }
+    let total = survivors.reduce((s, c) => s + c.size, 0);
+    if (total > tmpMaxBytes) {
+        survivors.sort((a, b) => a.mtime - b.mtime);
+        for (const c of survivors) {
+            if (total <= tmpMaxBytes)
+                break;
+            try {
+                await rm(c.path, { force: true });
+                total -= c.size;
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+async function autoSaveOversized(id, filename, buffer) {
+    await pruneTmpFiles();
+    const path = joinPath(tmpdir(), `${TMP_PREFIX}${id}-${sanitizeFilename(filename)}`);
+    await writeFile(path, buffer);
+    return path;
+}
+async function isAnimatedImage(buffer) {
+    try {
+        const meta = await sharp(buffer, { failOn: 'none', animated: true }).metadata();
+        return (meta.pages ?? 1) > 1;
+    }
+    catch {
+        return false;
+    }
+}
+async function buildVideoResult(id, header, buffer, opts) {
+    let result;
+    try {
+        result = await processVideo(buffer, {
+            frames: opts.frames,
+            start: opts.start,
+            end: opts.end,
+            mode: opts.mode,
+            sceneThreshold: opts.sceneThreshold,
+        });
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `${header}\nFailed to process ${opts.sourceLabel}: ${err.message}. Pass saveTo=/absolute/path to write the original to disk.`,
+                }],
+        };
+    }
+    if (result.frames.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `${header}\nNo frames extracted from ${opts.sourceLabel}. Pass saveTo=/absolute/path to write the original to disk.`,
+                }],
+        };
+    }
+    const m = result.meta;
+    const tsNote = result.approximateTimestamps ? ' (timestamps approximate)' : '';
+    const summary = [
+        `Attachment #${id}: ${header}`,
+        `Duration: ${m.duration.toFixed(1)}s, ${m.width}×${m.height} @ ${m.fps.toFixed(1)}fps, codec ${m.codec}`,
+        `Sampled ${result.frames.length} frame(s) via ${result.mode} mode from ${result.effectiveStart.toFixed(1)}s–${result.effectiveEnd.toFixed(1)}s at ${opts.maxDimension}px / q${opts.quality}${result.dedupApplied ? ' (mpdecimate enabled)' : ''}${tsNote}.`,
+        `Re-call with start=<sec> end=<sec> frames=<n> or mode=scenes to refine.`,
+    ].join('\n');
+    // Parallel sharp re-encode.
+    const encoded = await Promise.all(result.frames.map((f) => sharp(f.data, { failOn: 'none' })
+        .rotate()
+        .resize({ width: opts.maxDimension, height: opts.maxDimension, fit: 'inside', withoutEnlargement: true })
+        .jpeg({ quality: opts.quality, mozjpeg: true })
+        .toBuffer()));
+    const content = [{ type: 'text', text: summary }];
+    for (let i = 0; i < result.frames.length; i++) {
+        const f = result.frames[i];
+        const data = encoded[i];
+        const tsPrefix = f.approximate ? '~' : '';
+        content.push({ type: 'text', text: `Frame ${i + 1} @ ${tsPrefix}${f.timestampSec.toFixed(2)}s (${formatBytes(data.length)}):` });
+        content.push({ type: 'image', data: data.toString('base64'), mimeType: 'image/jpeg' });
+    }
+    return { content };
+}
 export async function buildAttachmentResult(args) {
     const { id, filename, mimeType, buffer, saveTo } = args;
     const sizeLabel = formatBytes(buffer.length);
@@ -64,13 +197,26 @@ export async function buildAttachmentResult(args) {
     }
     const mt = mimeType.toLowerCase();
     if (mt.startsWith('image/')) {
+        // Animated images (GIF/APNG/animated WebP) get routed to the video pipeline so the LLM sees motion.
+        if (await isAnimatedImage(buffer)) {
+            if (buffer.length > MAX_VIDEO_SOURCE_BYTES) {
+                const path = await autoSaveOversized(id, filename, buffer);
+                return { content: [{ type: 'text', text: `${header}\nAnimated image exceeds ${formatBytes(MAX_VIDEO_SOURCE_BYTES)} processing cap. Original saved to ${path}.` }] };
+            }
+            return buildVideoResult(id, header, buffer, {
+                maxDimension: args.maxDimension ?? DEFAULT_VIDEO_MAX_DIMENSION,
+                quality: args.quality ?? DEFAULT_VIDEO_QUALITY,
+                frames: args.frames ?? DEFAULT_VIDEO_FRAMES,
+                start: args.start,
+                end: args.end,
+                mode: args.mode ?? 'uniform',
+                sceneThreshold: args.sceneThreshold,
+                sourceLabel: 'animated 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 path = await autoSaveOversized(id, filename, buffer);
+            return { content: [{ type: 'text', text: `${header}\nImage exceeds ${formatBytes(MAX_INLINE_BYTES)} inline cap. Original saved to ${path}.` }] };
         }
         const maxDimension = args.maxDimension ?? DEFAULT_MAX_DIMENSION;
         const quality = args.quality ?? DEFAULT_JPEG_QUALITY;
@@ -97,13 +243,108 @@ export async function buildAttachmentResult(args) {
             };
         }
     }
+    if (mt.startsWith('video/')) {
+        if (buffer.length > MAX_VIDEO_SOURCE_BYTES) {
+            const path = await autoSaveOversized(id, filename, buffer);
+            return { content: [{ type: 'text', text: `${header}\nVideo exceeds ${formatBytes(MAX_VIDEO_SOURCE_BYTES)} processing cap. Original saved to ${path}.` }] };
+        }
+        return buildVideoResult(id, header, buffer, {
+            maxDimension: args.maxDimension ?? DEFAULT_VIDEO_MAX_DIMENSION,
+            quality: args.quality ?? DEFAULT_VIDEO_QUALITY,
+            frames: args.frames ?? DEFAULT_VIDEO_FRAMES,
+            start: args.start,
+            end: args.end,
+            mode: args.mode ?? 'uniform',
+            sceneThreshold: args.sceneThreshold,
+            sourceLabel: 'video',
+        });
+    }
+    if (mt.startsWith('audio/')) {
+        if (buffer.length > MAX_INLINE_BYTES) {
+            const path = await autoSaveOversized(id, filename, buffer);
+            return { content: [{ type: 'text', text: `${header}\nAudio exceeds ${formatBytes(MAX_INLINE_BYTES)} inline cap. Original saved to ${path}.` }] };
+        }
+        return {
+            content: [
+                { type: 'text', text: `Attachment #${id}: ${header}` },
+                { type: 'audio', data: buffer.toString('base64'), mimeType: mt },
+            ],
+        };
+    }
+    if (mt === 'application/pdf') {
+        if (buffer.length > MAX_INLINE_BYTES) {
+            const path = await autoSaveOversized(id, filename, buffer);
+            return { content: [{ type: 'text', text: `${header}\nPDF exceeds ${formatBytes(MAX_INLINE_BYTES)} inline cap. Original saved to ${path}.` }] };
+        }
+        try {
+            const { extractText, getDocumentProxy, definePDFJSModule, renderPageAsImage } = await import('unpdf');
+            const pdf = await getDocumentProxy(new Uint8Array(buffer));
+            const { totalPages, text } = await extractText(pdf, { mergePages: true });
+            const body = (typeof text === 'string' ? text : text.join('\n\n')).trim();
+            // Empty/sparse text → likely scanned PDF. Rasterize first few pages so the model can see them.
+            const RASTER_THRESHOLD = 20;
+            const MAX_RASTER_PAGES = 3;
+            if (body.length < RASTER_THRESHOLD && totalPages > 0) {
+                try {
+                    await definePDFJSModule(() => import('pdfjs-dist'));
+                    // unpdf requires an explicit canvasImport in Node so @napi-rs/canvas can be loaded lazily.
+                    // NodeNext ESM types differ between two synthesized views of @napi-rs/canvas; cast through any.
+                    const renderOpts = { width: 0, canvasImport: () => import('@napi-rs/canvas') };
+                    const pageCount = Math.min(totalPages, MAX_RASTER_PAGES);
+                    const maxDimension = args.maxDimension ?? DEFAULT_MAX_DIMENSION;
+                    const quality = args.quality ?? DEFAULT_JPEG_QUALITY;
+                    const rasterized = await Promise.all(Array.from({ length: pageCount }, (_, i) => renderPageAsImage(new Uint8Array(buffer), i + 1, { ...renderOpts, width: maxDimension }).then(async (ab) => {
+                        const png = Buffer.from(ab);
+                        return sharp(png, { failOn: 'none' })
+                            .resize({ width: maxDimension, height: maxDimension, fit: 'inside', withoutEnlargement: true })
+                            .jpeg({ quality, mozjpeg: true })
+                            .toBuffer();
+                    })));
+                    const content = [{
+                            type: 'text',
+                            text: `Attachment #${id}: ${header}\nNo extractable text found (likely scanned). Rasterized first ${pageCount} of ${totalPages} page(s):`,
+                        }];
+                    for (let i = 0; i < rasterized.length; i++) {
+                        content.push({ type: 'text', text: `Page ${i + 1} (${formatBytes(rasterized[i].length)}):` });
+                        content.push({ type: 'image', data: rasterized[i].toString('base64'), mimeType: 'image/jpeg' });
+                    }
+                    return { content };
+                }
+                catch (rasterErr) {
+                    const path = await autoSaveOversized(id, filename, buffer);
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `${header}\nNo extractable text and rasterization failed: ${rasterErr.message}. Original saved to ${path}.`,
+                            }],
+                    };
+                }
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Attachment #${id}: ${header}\nExtracted text from ${totalPages} page(s):\n\n${body}`,
+                    }],
+            };
+        }
+        catch (err) {
+            const path = await autoSaveOversized(id, filename, buffer);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `${header}\nFailed to extract PDF text: ${err.message}. Original saved to ${path}.`,
+                    }],
+            };
+        }
+    }
     if (isTextMime(mt) && buffer.length <= MAX_INLINE_BYTES) {
         return { content: [{ type: 'text', text: `Attachment #${id}: ${header}\n\n${buffer.toString('utf-8')}` }] };
     }
+    const path = await autoSaveOversized(id, filename, buffer);
     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.`,
+                text: `${header}\nAttachment #${id} is not inline-renderable. Original saved to ${path}.`,
             }],
     };
 }

package/dist/bitbucket.js

@@ -1,5 +1,10 @@
 import { execSync } from 'child_process';
-import { buildAttachmentResult } from './attachment.js';
+import { createWriteStream } from 'fs';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
+import { resolve as resolvePath } from 'path';
+import { buildAttachmentResult, formatBytes } from './attachment.js';
+import { MAX_VIDEO_SOURCE_BYTES } from './video.js';
 const EMOJI_RE = /\p{Extended_Pictographic}/u;
 const ATTACHMENT_REF_RE = /!?\[([^\]]*)\]\(attachment:(\d+)\)/g;
 function collectAttachmentRefs(input, source, out) {
@@ -893,28 +898,53 @@ export class BitbucketClient {
         if (!id)
             throw new Error('attachmentId is required.');
         const url = `${this.baseUrl}/rest/api/1.0${this.rp(projectKey, repoSlug)}/attachments/${encodeURIComponent(id)}`;
+        const fetchTimeoutMs = args.saveTo ? 300_000 : 60_000;
         const res = await fetch(url, {
             method: 'GET',
             headers: { Authorization: this.headers.Authorization },
-            signal: AbortSignal.timeout(60_000),
+            signal: AbortSignal.timeout(fetchTimeoutMs),
         });
         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();
+        const declaredLength = parseInt(res.headers.get('content-length') ?? '0', 10);
+        // saveTo path: stream directly to disk so we never buffer the whole attachment in memory.
+        if (args.saveTo) {
+            const path = resolvePath(args.saveTo);
+            if (!res.body)
+                throw new Error(`Attachment #${id} response has no body.`);
+            await pipeline(Readable.fromWeb(res.body), createWriteStream(path));
+            const sizeLabel = declaredLength > 0 ? formatBytes(declaredLength) : 'unknown size';
+            return { content: [{ type: 'text', text: `Saved attachment #${id} (${filename} — ${mimeType}, ${sizeLabel}) to ${path}` }] };
+        }
+        if (declaredLength > MAX_VIDEO_SOURCE_BYTES) {
+            try {
+                await res.body?.cancel();
+            }
+            catch { /* ignore */ }
+            throw new Error(`Attachment #${id} is ${formatBytes(declaredLength)}, exceeds the ${formatBytes(MAX_VIDEO_SOURCE_BYTES)} inline cap. Pass saveTo=/absolute/path to stream it to disk.`);
+        }
+        const buffer = Buffer.from(await res.arrayBuffer());
+        if (buffer.length > MAX_VIDEO_SOURCE_BYTES) {
+            throw new Error(`Attachment #${id} downloaded ${formatBytes(buffer.length)}, exceeds the ${formatBytes(MAX_VIDEO_SOURCE_BYTES)} inline cap. Pass saveTo=/absolute/path to stream it to disk.`);
+        }
         return buildAttachmentResult({
             id,
             filename,
             mimeType,
             buffer,
-            saveTo: args.saveTo,
             maxDimension: args.maxDimension,
             quality: args.quality,
+            frames: args.frames,
+            start: args.start,
+            end: args.end,
+            mode: args.mode,
+            sceneThreshold: args.sceneThreshold,
         });
     }
     async fetchFileText(projectKey, repoSlug, filePath) {

package/dist/index.js

@@ -125,6 +125,32 @@ function normalizeJiraMutateArgs(args) {
     }
     return out;
 }
+function validateAttachmentArgs(a) {
+    if (a.frames !== undefined && (typeof a.frames !== 'number' || !Number.isFinite(a.frames) || a.frames < 1 || a.frames > 60)) {
+        throw new McpError(ErrorCode.InvalidParams, 'frames must be a number between 1 and 60.');
+    }
+    if (a.start !== undefined && (typeof a.start !== 'number' || !Number.isFinite(a.start) || a.start < 0)) {
+        throw new McpError(ErrorCode.InvalidParams, 'start must be a non-negative number of seconds.');
+    }
+    if (a.end !== undefined && (typeof a.end !== 'number' || !Number.isFinite(a.end) || a.end <= 0)) {
+        throw new McpError(ErrorCode.InvalidParams, 'end must be a positive number of seconds.');
+    }
+    if (typeof a.start === 'number' && typeof a.end === 'number' && a.end <= a.start) {
+        throw new McpError(ErrorCode.InvalidParams, 'end must be greater than start.');
+    }
+    if (a.mode !== undefined && a.mode !== 'uniform' && a.mode !== 'scenes') {
+        throw new McpError(ErrorCode.InvalidParams, 'mode must be "uniform" or "scenes".');
+    }
+    if (a.maxDimension !== undefined && (typeof a.maxDimension !== 'number' || !Number.isFinite(a.maxDimension) || a.maxDimension < 64 || a.maxDimension > 4096)) {
+        throw new McpError(ErrorCode.InvalidParams, 'maxDimension must be a number between 64 and 4096.');
+    }
+    if (a.quality !== undefined && (typeof a.quality !== 'number' || !Number.isFinite(a.quality) || a.quality < 1 || a.quality > 100)) {
+        throw new McpError(ErrorCode.InvalidParams, 'quality must be a number between 1 and 100.');
+    }
+    if (a.sceneThreshold !== undefined && (typeof a.sceneThreshold !== 'number' || !Number.isFinite(a.sceneThreshold) || a.sceneThreshold <= 0 || a.sceneThreshold > 1)) {
+        throw new McpError(ErrorCode.InvalidParams, 'sceneThreshold must be a number in (0, 1].');
+    }
+}
 const JIRA_WIKI_MARKUP_HINT = 'Use Jira wiki markup (Atlassian renderer syntax), not GitHub/CommonMark markdown.';
 function issueTypePrefix(issueType) {
     const t = issueType.toLowerCase();
@@ -308,14 +334,19 @@ 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.',
+                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; text/JSON/XML come back as text. Videos AND animated images (GIF/APNG/animated WebP) are decoded with ffmpeg: by default 6 frames are sampled uniformly across the whole clip (768 px / q65, mpdecimate to drop near-duplicates) — re-call with start/end/frames or mode=scenes to refine. Audio is returned as an MCP audio block. PDFs return extracted text. Anything still too large or non-renderable is automatically saved to a temp file and the path is returned. 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).' },
+                        maxDimension: { type: 'number', description: 'Max long-edge size in pixels for inline images (default 1568 for images, 768 for video frames).' },
+                        quality: { type: 'number', description: 'JPEG quality for re-encoded inline images (1-100, default 85 for images, 65 for video frames). Ignored for images with alpha (encoded as PNG).' },
+                        frames: { type: 'number', description: 'Video/animated-image only: number of frames to sample (default 6, range 1-60). Higher = more detail + more context.' },
+                        start: { type: 'number', description: 'Video/animated-image only: start of sample window in seconds (default 0). Use with end/frames to zoom into a moment of interest after a coarse first pass.' },
+                        end: { type: 'number', description: 'Video/animated-image only: end of sample window in seconds (default full duration). Must be greater than start.' },
+                        mode: { type: 'string', enum: ['uniform', 'scenes'], description: 'Video/animated-image only: "uniform" samples N frames evenly (default); "scenes" uses ffmpeg scene-change detection, better for screencasts/narrative content.' },
+                        sceneThreshold: { type: 'number', description: 'Video/animated-image only: scene-change sensitivity in 0-1 (default 0.3). Only used when mode=scenes. Lower = more frames, higher = fewer.' },
                     },
                     required: ['attachmentId'],
                 },
@@ -490,7 +521,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             },
             {
                 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.',
+                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. Videos AND animated images (GIF/APNG/animated WebP) are decoded with ffmpeg: by default 6 frames are sampled uniformly across the whole clip (768 px / q65, mpdecimate to drop near-duplicates) — re-call with start/end/frames or mode=scenes to refine. Audio is returned as an MCP audio block. PDFs return extracted text. Oversized/non-renderable attachments are auto-saved to a temp file and the path is returned.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -500,8 +531,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                         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).' },
+                        maxDimension: { type: 'number', description: 'Max long-edge size in pixels for inline images (default 1568 for images, 768 for video frames).' },
+                        quality: { type: 'number', description: 'JPEG quality for re-encoded inline images (1-100, default 85 for images, 65 for video frames). Ignored for images with alpha (encoded as PNG).' },
+                        frames: { type: 'number', description: 'Video/animated-image only: number of frames to sample (default 6, range 1-60).' },
+                        start: { type: 'number', description: 'Video/animated-image only: start of sample window in seconds (default 0). Use with end/frames to zoom in.' },
+                        end: { type: 'number', description: 'Video/animated-image only: end of sample window in seconds (default full duration). Must be greater than start.' },
+                        mode: { type: 'string', enum: ['uniform', 'scenes'], description: 'Video/animated-image only: "uniform" samples N frames evenly (default); "scenes" uses scene-change detection.' },
+                        sceneThreshold: { type: 'number', description: 'Video/animated-image only: scene-change sensitivity in 0-1 (default 0.3). Only used when mode=scenes. Lower = more frames, higher = fewer.' },
                     },
                     required: ['attachmentId'],
                 },
@@ -800,6 +836,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (!jira)
                     throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
                 const a = args;
+                validateAttachmentArgs(a);
                 return await jira.getAttachment(a);
             }
             case 'jira_comment': {
@@ -911,7 +948,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case 'bitbucket_get_attachment': {
                 if (!bitbucket)
                     throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
-                return await bitbucket.getAttachment(normalizeBitbucketArgs(args));
+                const normalized = normalizeBitbucketArgs(args);
+                validateAttachmentArgs(normalized);
+                return await bitbucket.getAttachment(normalized);
             }
             case 'bitbucket_pr_tasks': {
                 if (!bitbucket)

package/dist/jira.js

@@ -1,5 +1,10 @@
 import { execSync } from 'child_process';
+import { createWriteStream } from 'fs';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
+import { resolve as resolvePath } from 'path';
 import { buildAttachmentResult, formatBytes } from './attachment.js';
+import { MAX_VIDEO_SOURCE_BYTES } from './video.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) {
@@ -794,6 +799,28 @@ export class JiraClient {
         const meta = await this.request('GET', `/attachment/${encodeURIComponent(id)}`);
         if (!meta)
             throw new Error(`Attachment ${id} not found.`);
+        // saveTo path: stream response directly to disk to bypass the in-memory size cap and avoid double-buffering.
+        if (args.saveTo) {
+            const path = resolvePath(args.saveTo);
+            const res = await fetch(meta.content, {
+                method: 'GET',
+                headers: { Authorization: this.headers.Authorization },
+                signal: AbortSignal.timeout(300_000),
+            });
+            if (!res.ok) {
+                const errText = await res.text();
+                throw new Error(formatJiraError(res.status, 'GET', meta.content, parseJiraErrorDetails(errText)));
+            }
+            if (!res.body)
+                throw new Error(`Attachment #${id} response has no body.`);
+            await pipeline(Readable.fromWeb(res.body), createWriteStream(path));
+            const sizeLabel = meta.size ? formatBytes(meta.size) : 'unknown size';
+            return { content: [{ type: 'text', text: `Saved attachment #${id} (${meta.filename} — ${meta.mimeType ?? 'application/octet-stream'}, ${sizeLabel}) to ${path}` }] };
+        }
+        // Inline path enforces the 250 MB cap so we don't OOM on accidental huge fetches.
+        if (meta.size && meta.size > MAX_VIDEO_SOURCE_BYTES) {
+            throw new Error(`Attachment #${id} is ${formatBytes(meta.size)}, exceeds the ${formatBytes(MAX_VIDEO_SOURCE_BYTES)} inline cap. Pass saveTo=/absolute/path to stream it to disk.`);
+        }
         const res = await fetch(meta.content, {
             method: 'GET',
             headers: { Authorization: this.headers.Authorization },
@@ -803,15 +830,30 @@ export class JiraClient {
             const errText = await res.text();
             throw new Error(formatJiraError(res.status, 'GET', meta.content, parseJiraErrorDetails(errText)));
         }
+        const declaredLength = parseInt(res.headers.get('content-length') ?? '0', 10);
+        if (declaredLength > MAX_VIDEO_SOURCE_BYTES) {
+            try {
+                await res.body?.cancel();
+            }
+            catch { /* ignore */ }
+            throw new Error(`Attachment #${id} is ${formatBytes(declaredLength)}, exceeds the ${formatBytes(MAX_VIDEO_SOURCE_BYTES)} inline cap. Pass saveTo=/absolute/path to stream it to disk.`);
+        }
         const buffer = Buffer.from(await res.arrayBuffer());
+        if (buffer.length > MAX_VIDEO_SOURCE_BYTES) {
+            throw new Error(`Attachment #${id} downloaded ${formatBytes(buffer.length)}, exceeds the ${formatBytes(MAX_VIDEO_SOURCE_BYTES)} inline cap. Pass saveTo=/absolute/path to stream it to disk.`);
+        }
         return buildAttachmentResult({
             id,
             filename: meta.filename,
             mimeType: meta.mimeType ?? 'application/octet-stream',
             buffer,
-            saveTo: args.saveTo,
             maxDimension: args.maxDimension,
             quality: args.quality,
+            frames: args.frames,
+            start: args.start,
+            end: args.end,
+            mode: args.mode,
+            sceneThreshold: args.sceneThreshold,
         });
     }
     async transitionIssue(args) {

package/dist/video.js

@@ -0,0 +1,211 @@
+import { spawn } from 'node:child_process';
+import { writeFile, readdir, readFile, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+// ffmpeg-static / ffprobe-static ship no types; declare just enough to import.
+// @ts-ignore - no @types
+import ffmpegPathImport from 'ffmpeg-static';
+// @ts-ignore - no @types
+import ffprobeStaticImport from 'ffprobe-static';
+const FFMPEG = process.env.ATLASSIAN_MCP_FFMPEG_PATH ||
+    ffmpegPathImport ||
+    null;
+const FFPROBE = process.env.ATLASSIAN_MCP_FFPROBE_PATH ||
+    ffprobeStaticImport?.path ||
+    null;
+export const DEFAULT_VIDEO_FRAMES = 6;
+export const DEFAULT_VIDEO_MAX_DIMENSION = 768;
+export const DEFAULT_VIDEO_QUALITY = 65;
+export const MAX_VIDEO_SOURCE_BYTES = 250 * 1024 * 1024;
+export const VIDEO_FRAMES_MIN = 1;
+export const VIDEO_FRAMES_MAX = 60;
+export const DEFAULT_SCENE_THRESHOLD = 0.3;
+function run(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        const stdoutChunks = [];
+        let stderr = '';
+        proc.stdout.on('data', (c) => stdoutChunks.push(c));
+        proc.stderr.on('data', (c) => (stderr += c.toString()));
+        proc.on('error', reject);
+        proc.on('close', (code) => resolve({ stdout: Buffer.concat(stdoutChunks), stderr, code: code ?? 0 }));
+    });
+}
+async function probeVideo(filePath) {
+    if (!FFPROBE)
+        throw new Error('ffprobe binary unavailable. Set ATLASSIAN_MCP_FFPROBE_PATH or install ffprobe-static.');
+    const { stdout, stderr, code } = await run(FFPROBE, [
+        '-v', 'error',
+        '-select_streams', 'v:0',
+        '-show_entries', 'stream=width,height,r_frame_rate,codec_name,duration,nb_frames,nb_read_frames:format=duration',
+        '-count_frames', // populate nb_read_frames for containers without nb_frames (e.g. GIF)
+        '-of', 'json',
+        filePath,
+    ]);
+    if (code !== 0)
+        throw new Error(`ffprobe failed (${code}): ${stderr.trim() || 'unknown error'}`);
+    const json = JSON.parse(stdout.toString('utf-8'));
+    const stream = json.streams?.[0];
+    if (!stream)
+        throw new Error('No video stream found.');
+    const rate = stream.r_frame_rate ?? '0/1';
+    const [num, den] = rate.split('/').map((s) => parseFloat(s));
+    const fps = Number.isFinite(num) && Number.isFinite(den) && den > 0 ? num / den : 0;
+    // duration fallback chain: format.duration → stream.duration → nb_frames/fps → 0
+    const formatDuration = parseFloat(json.format?.duration ?? '');
+    const streamDuration = parseFloat(stream.duration ?? '');
+    const frameCount = parseInt(stream.nb_frames ?? stream.nb_read_frames ?? '', 10);
+    const fromFrames = Number.isFinite(frameCount) && frameCount > 0 && fps > 0 ? frameCount / fps : 0;
+    const duration = [formatDuration, streamDuration, fromFrames].find((v) => Number.isFinite(v) && v > 0) ?? 0;
+    return {
+        duration,
+        width: stream.width ?? 0,
+        height: stream.height ?? 0,
+        fps,
+        codec: stream.codec_name ?? 'unknown',
+    };
+}
+// Quick content-derived cache key. Hashes head+tail+length to avoid full-buffer scan on large videos.
+function quickHash(buf) {
+    const h = createHash('sha1');
+    const HEAD = 1024 * 1024;
+    h.update(buf.subarray(0, Math.min(buf.length, HEAD)));
+    if (buf.length > HEAD * 2)
+        h.update(buf.subarray(buf.length - HEAD));
+    h.update(String(buf.length));
+    return h.digest('hex');
+}
+const VIDEO_CACHE = new Map();
+const VIDEO_CACHE_MAX = 16;
+function cacheGet(key) {
+    const hit = VIDEO_CACHE.get(key);
+    if (!hit)
+        return undefined;
+    // refresh LRU order
+    VIDEO_CACHE.delete(key);
+    VIDEO_CACHE.set(key, hit);
+    return hit;
+}
+function cacheSet(key, value) {
+    if (VIDEO_CACHE.size >= VIDEO_CACHE_MAX) {
+        const oldest = VIDEO_CACHE.keys().next().value;
+        if (oldest !== undefined)
+            VIDEO_CACHE.delete(oldest);
+    }
+    VIDEO_CACHE.set(key, value);
+}
+// Parse pts_time from ffmpeg showinfo stderr. Returns timestamps in input order.
+function parseShowinfoTimestamps(stderr) {
+    const out = [];
+    const re = /Parsed_showinfo[^\]]*\][^\n]*pts_time:([\d.]+)/g;
+    let m;
+    while ((m = re.exec(stderr)) !== null) {
+        const v = parseFloat(m[1]);
+        if (Number.isFinite(v))
+            out.push(v);
+    }
+    return out;
+}
+export async function processVideo(buffer, opts = {}) {
+    if (!FFMPEG)
+        throw new Error('ffmpeg binary unavailable. Set ATLASSIAN_MCP_FFMPEG_PATH or install ffmpeg-static.');
+    const frames = Math.max(VIDEO_FRAMES_MIN, Math.min(opts.frames ?? DEFAULT_VIDEO_FRAMES, VIDEO_FRAMES_MAX));
+    const dedup = opts.dedup ?? true;
+    const mode = opts.mode ?? 'uniform';
+    const sceneThreshold = Math.max(0.01, Math.min(opts.sceneThreshold ?? DEFAULT_SCENE_THRESHOLD, 1));
+    const cacheKey = `${quickHash(buffer)}:${frames}:${opts.start ?? 'a'}:${opts.end ?? 'z'}:${dedup}:${mode}:${sceneThreshold}`;
+    const cached = cacheGet(cacheKey);
+    if (cached)
+        return cached;
+    const dir = await mkdtemp(join(tmpdir(), 'atlmcp-video-'));
+    const input = join(dir, 'input');
+    try {
+        await writeFile(input, buffer);
+        const meta = await probeVideo(input);
+        const start = Math.max(0, opts.start ?? 0);
+        const endRaw = opts.end ?? meta.duration;
+        const end = Math.min(meta.duration > 0 ? meta.duration : endRaw, endRaw);
+        if (end <= start)
+            throw new Error(`Invalid window: start=${start}s end=${end}s (duration=${meta.duration}s).`);
+        const window = end - start;
+        const extractWithMode = async (curMode, useDedup) => {
+            const vfParts = [];
+            if (curMode === 'scenes') {
+                // Threshold (default 0.3) sets scene-change sensitivity. Output rate is non-uniform; -frames:v caps count.
+                vfParts.push(`select='gt(scene\\,${sceneThreshold.toFixed(3)})'`);
+            }
+            else {
+                const fps = Math.max(frames / window, 0.001);
+                vfParts.push(`fps=${fps}`);
+            }
+            if (useDedup)
+                vfParts.push(`mpdecimate=hi=64*12:lo=64*5:frac=0.33`);
+            vfParts.push('showinfo');
+            const vf = vfParts.join(',');
+            const args = [
+                '-hide_banner', '-loglevel', 'info',
+                '-ss', start.toFixed(3),
+                '-to', end.toFixed(3),
+                '-i', input,
+                '-vf', vf,
+                '-frames:v', String(frames),
+                '-fps_mode', 'vfr',
+                '-an', '-sn',
+                '-q:v', '2',
+                join(dir, 'frame-%03d.jpg'),
+            ];
+            const { stderr, code } = await run(FFMPEG, args);
+            if (code !== 0)
+                throw new Error(`ffmpeg failed (${code}): ${stderr.split('\n').filter((l) => /error/i.test(l)).slice(-3).join(' / ').trim() || 'unknown error'}`);
+            const files = (await readdir(dir)).filter((f) => f.startsWith('frame-') && f.endsWith('.jpg')).sort();
+            const ptsTimes = parseShowinfoTimestamps(stderr);
+            // showinfo emits one line per output frame; align by index.
+            const exact = ptsTimes.length === files.length;
+            const out = [];
+            const step = window / Math.max(1, files.length);
+            for (let i = 0; i < files.length; i++) {
+                const data = await readFile(join(dir, files[i]));
+                // pts_time is offset from -ss seek point; add start for wall-clock.
+                const ts = exact ? start + ptsTimes[i] : start + step * (i + 0.5);
+                out.push({ data, timestampSec: ts, approximate: !exact });
+            }
+            return { frames: out, approximate: !exact };
+        };
+        const cleanFrames = async () => {
+            for (const f of await readdir(dir)) {
+                if (f.startsWith('frame-'))
+                    await rm(join(dir, f), { force: true });
+            }
+        };
+        let extracted = await extractWithMode(mode, dedup);
+        let dedupApplied = dedup;
+        let effectiveMode = mode;
+        // Scenes mode with no scene changes detected → fall back to uniform.
+        if (extracted.frames.length === 0 && mode === 'scenes') {
+            await cleanFrames();
+            effectiveMode = 'uniform';
+            extracted = await extractWithMode('uniform', dedup);
+        }
+        // Dedup killed everything → retry without dedup.
+        if (extracted.frames.length === 0 && dedup) {
+            await cleanFrames();
+            extracted = await extractWithMode(effectiveMode, false);
+            dedupApplied = false;
+        }
+        const result = {
+            meta,
+            frames: extracted.frames,
+            effectiveStart: start,
+            effectiveEnd: end,
+            dedupApplied,
+            mode: effectiveMode,
+            approximateTimestamps: extracted.approximate,
+        };
+        cacheSet(cacheKey, result);
+        return result;
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stubbedev/atlassian-mcp",
-  "version": "0.3.10",
+  "version": "0.4.0",
   "description": "MCP server for self-hosted Jira and Bitbucket",
   "license": "MIT",
   "type": "module",
@@ -27,8 +27,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@napi-rs/canvas": "^0.1.100",
     "dotenv": "^17.4.2",
-    "sharp": "^0.34.5"
+    "ffmpeg-static": "^5.3.0",
+    "ffprobe-static": "^3.1.0",
+    "pdfjs-dist": "^5.6.205",
+    "sharp": "^0.34.5",
+    "unpdf": "^1.6.2"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",