@aaronsb/jira-cloud-mcp 0.9.0 → 0.10.0

package/build/client/jira-client.js

@@ -1131,6 +1131,47 @@ export class JiraClient {
             jql: result.jql || '',
         };
     }
+    // ── Attachment Operations ────────────────────────────────
+    async getAttachmentInfo(attachmentId) {
+        const meta = await this.client.issueAttachments.getAttachment(attachmentId);
+        return {
+            id: meta.id?.toString() ?? attachmentId,
+            filename: meta.filename ?? 'unnamed',
+            mimeType: meta.mimeType ?? 'application/octet-stream',
+            size: meta.size ?? 0,
+            created: meta.created ?? '',
+            author: meta.author?.displayName ?? 'Unknown',
+            url: meta.content ?? '',
+        };
+    }
+    async downloadAttachment(attachmentId) {
+        const content = await this.client.issueAttachments.getAttachmentContent(attachmentId);
+        // jira.js generic defaults to Buffer; ensure we return Buffer even if runtime type differs
+        return Buffer.isBuffer(content) ? content : Buffer.from(content);
+    }
+    async uploadAttachment(issueKey, filename, content, mimeType) {
+        const result = await this.client.issueAttachments.addAttachment({
+            issueIdOrKey: issueKey,
+            attachment: {
+                filename,
+                file: content,
+                mimeType,
+            },
+        });
+        const att = Array.isArray(result) ? result[0] : result;
+        return {
+            id: att.id?.toString() ?? '',
+            filename: att.filename ?? filename,
+            mimeType: att.mimeType ?? mimeType,
+            size: att.size ?? content.length,
+            created: att.created ?? new Date().toISOString(),
+            author: att.author?.displayName ?? 'Unknown',
+            url: att.content ?? '',
+        };
+    }
+    async deleteAttachment(attachmentId) {
+        await this.client.issueAttachments.removeAttachment(attachmentId);
+    }
     async deleteFilter(filterId) {
         await this.client.filters.deleteFilter(filterId);
     }

package/build/handlers/media-handler.js

@@ -0,0 +1,130 @@
+/**
+ * Handler for manage_jira_media tool.
+ * See ADR-211: Attachment and Workspace Management.
+ */
+import * as fs from 'node:fs/promises';
+import { mediaNextSteps } from '../utils/next-steps.js';
+import { ensureWorkspaceDir, formatSize, resolveWorkspacePath, ensureParentDir, verifyPathSafety, sanitizeFilename, } from '../workspace/index.js';
+export async function handleMediaRequest(client, args) {
+    switch (args.operation) {
+        case 'list': {
+            if (!args.issueKey) {
+                return { content: [{ type: 'text', text: 'issueKey is required for list operation' }], isError: true };
+            }
+            const attachments = await client.getIssueAttachments(args.issueKey);
+            if (attachments.length === 0) {
+                let text = `No attachments on ${args.issueKey}.`;
+                text += mediaNextSteps('list', { issueKey: args.issueKey });
+                return { content: [{ type: 'text', text }] };
+            }
+            const lines = attachments.map(a => `- ${a.filename} | ${a.mimeType} | ${formatSize(a.size)} | id:${a.id} | ${a.author} | ${a.created}`);
+            let text = `Attachments on ${args.issueKey} (${attachments.length}):\n${lines.join('\n')}`;
+            text += mediaNextSteps('list', { issueKey: args.issueKey });
+            return { content: [{ type: 'text', text }] };
+        }
+        case 'upload': {
+            if (!args.issueKey || !args.filename || !args.mediaType) {
+                return {
+                    content: [{ type: 'text', text: 'issueKey, filename, and mediaType are required for upload' }],
+                    isError: true,
+                };
+            }
+            let buffer;
+            if (args.workspaceFile) {
+                const filePath = resolveWorkspacePath(args.workspaceFile);
+                await verifyPathSafety(filePath);
+                try {
+                    buffer = await fs.readFile(filePath);
+                }
+                catch {
+                    return { content: [{ type: 'text', text: `Workspace file not found: ${args.workspaceFile}` }], isError: true };
+                }
+            }
+            else if (args.content) {
+                buffer = Buffer.from(args.content, 'base64');
+            }
+            else {
+                return {
+                    content: [{ type: 'text', text: 'Either content (base64) or workspaceFile is required for upload' }],
+                    isError: true,
+                };
+            }
+            const safeFilename = sanitizeFilename(args.filename);
+            const attachment = await client.uploadAttachment(args.issueKey, safeFilename, buffer, args.mediaType);
+            let text = `Uploaded: ${attachment.filename} | ${attachment.mimeType} | ${formatSize(attachment.size)} | id:${attachment.id}`;
+            text += mediaNextSteps('upload', { issueKey: args.issueKey });
+            return { content: [{ type: 'text', text }] };
+        }
+        case 'delete': {
+            if (!args.attachmentId) {
+                return { content: [{ type: 'text', text: 'attachmentId is required for delete operation' }], isError: true };
+            }
+            await client.deleteAttachment(args.attachmentId);
+            return { content: [{ type: 'text', text: `Permanently deleted attachment ${args.attachmentId} from Jira. This cannot be undone.` }] };
+        }
+        case 'view': {
+            if (!args.attachmentId) {
+                return { content: [{ type: 'text', text: 'attachmentId is required for view operation' }], isError: true };
+            }
+            const info = await client.getAttachmentInfo(args.attachmentId);
+            if (!info.mimeType.startsWith('image/')) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `${info.filename} | ${info.mimeType} | ${formatSize(info.size)}\n\nNot an image — cannot display inline. Use download to fetch raw content.`,
+                        }],
+                };
+            }
+            const MAX_IMAGE_SIZE = 5 * 1024 * 1024; // 5MB
+            if (info.size > MAX_IMAGE_SIZE) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `${info.filename} | ${info.mimeType} | ${formatSize(info.size)}\n\nImage too large to display inline (${(info.size / 1024 / 1024).toFixed(1)}MB, max 5MB). Use download instead.`,
+                        }],
+                };
+            }
+            const bytes = await client.downloadAttachment(args.attachmentId);
+            return {
+                content: [
+                    { type: 'text', text: `${info.filename} | ${info.mimeType}` },
+                    { type: 'image', data: bytes.toString('base64'), mimeType: info.mimeType },
+                ],
+            };
+        }
+        case 'get_info': {
+            if (!args.attachmentId) {
+                return { content: [{ type: 'text', text: 'attachmentId is required for get_info operation' }], isError: true };
+            }
+            const attachInfo = await client.getAttachmentInfo(args.attachmentId);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `${attachInfo.filename} | ${attachInfo.mimeType} | ${formatSize(attachInfo.size)} | id:${attachInfo.id} | ${attachInfo.author} | ${attachInfo.created}`,
+                    }],
+            };
+        }
+        case 'download': {
+            if (!args.attachmentId) {
+                return { content: [{ type: 'text', text: 'attachmentId is required for download operation' }], isError: true };
+            }
+            const dlInfo = await client.getAttachmentInfo(args.attachmentId);
+            const dlBytes = await client.downloadAttachment(args.attachmentId);
+            const status = await ensureWorkspaceDir();
+            if (!status.valid) {
+                return { content: [{ type: 'text', text: `Workspace invalid: ${status.warning}` }], isError: true };
+            }
+            const dlFilename = args.filename || sanitizeFilename(dlInfo.filename);
+            const dlPath = resolveWorkspacePath(dlFilename);
+            await verifyPathSafety(dlPath);
+            await ensureParentDir(dlPath);
+            await fs.writeFile(dlPath, dlBytes);
+            let text = `Downloaded: ${dlFilename} | ${dlInfo.mimeType} | ${formatSize(dlBytes.length)}\nPath: ${dlPath}`;
+            text += `\n\nUse manage_workspace read or manage_jira_media upload with workspaceFile:"${dlFilename}" to use it.`;
+            text += mediaNextSteps('download', {});
+            return { content: [{ type: 'text', text }] };
+        }
+        default:
+            return { content: [{ type: 'text', text: `Unknown media operation: ${args.operation}` }], isError: true };
+    }
+}

package/build/handlers/workspace-handler.js

@@ -0,0 +1,214 @@
+/**
+ * Handler for manage_workspace tool.
+ * See ADR-211: Attachment and Workspace Management.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { ensureWorkspaceDir, formatSize, resolveWorkspacePath, ensureParentDir, verifyPathSafety, } from '../workspace/index.js';
+const TEXT_INLINE_LIMIT = 100 * 1024; // 100KB
+const IMAGE_INLINE_LIMIT = 5 * 1024 * 1024; // 5MB
+const IMAGE_EXTENSIONS = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.bmp': 'image/bmp',
+    '.ico': 'image/x-icon',
+};
+const TEXT_EXTENSIONS = new Set([
+    '.txt', '.md', '.json', '.xml', '.csv', '.html', '.htm',
+    '.yaml', '.yml', '.toml', '.ini', '.cfg', '.conf', '.log',
+    '.js', '.ts', '.py', '.rb', '.sh', '.bash', '.zsh',
+    '.css', '.scss', '.less', '.svg',
+]);
+export async function handleWorkspaceRequest(args) {
+    switch (args.operation) {
+        case 'list':
+            return handleList();
+        case 'read':
+            return handleRead(args);
+        case 'write':
+            return handleWrite(args);
+        case 'delete':
+            return handleDelete(args);
+        case 'mkdir':
+            return handleMkdir(args);
+        case 'move':
+            return handleMove(args);
+        default:
+            return { content: [{ type: 'text', text: `Unknown workspace operation: ${args.operation}` }], isError: true };
+    }
+}
+async function handleList() {
+    const status = await ensureWorkspaceDir();
+    if (!status.valid) {
+        return { content: [{ type: 'text', text: `Workspace invalid: ${status.warning}` }], isError: true };
+    }
+    const lines = [`Workspace: ${status.path}\n`];
+    await listRecursive(status.path, status.path, lines, 0);
+    if (lines.length === 1) {
+        return { content: [{ type: 'text', text: `Workspace: ${status.path}\n\n(empty — no files staged)` }] };
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+}
+const MAX_LIST_DEPTH = 10;
+async function listRecursive(rootDir, dir, lines, depth) {
+    if (depth >= MAX_LIST_DEPTH) {
+        lines.push(`${'  '.repeat(depth + 1)}(truncated — max depth ${MAX_LIST_DEPTH})`);
+        return;
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const indent = '  '.repeat(depth + 1);
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.isSymbolicLink())
+            continue; // skip symlinks to prevent loops
+        try {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                lines.push(`${indent}${entry.name}/`);
+                await listRecursive(rootDir, fullPath, lines, depth + 1);
+            }
+            else if (entry.isFile()) {
+                const stat = await fs.stat(fullPath);
+                lines.push(`${indent}${entry.name}  (${formatSize(stat.size)}, ${stat.mtime.toISOString().slice(0, 16)})`);
+            }
+        }
+        catch {
+            // Skip entries we can't stat
+        }
+    }
+}
+async function handleRead(args) {
+    if (!args.filename) {
+        return { content: [{ type: 'text', text: 'filename is required for read operation' }], isError: true };
+    }
+    const filePath = resolveWorkspacePath(args.filename);
+    await verifyPathSafety(filePath);
+    let stat;
+    try {
+        stat = await fs.stat(filePath);
+    }
+    catch {
+        return { content: [{ type: 'text', text: `File not found in workspace: ${args.filename}` }], isError: true };
+    }
+    const ext = path.extname(args.filename).toLowerCase();
+    const isText = TEXT_EXTENSIONS.has(ext);
+    const imageMime = IMAGE_EXTENSIONS[ext];
+    // Inline text
+    if (isText && stat.size <= TEXT_INLINE_LIMIT) {
+        const content = await fs.readFile(filePath, 'utf-8');
+        return { content: [{ type: 'text', text: `File: ${args.filename} (${formatSize(stat.size)})\nPath: ${filePath}\n\n${content}` }] };
+    }
+    // Inline image
+    if (imageMime && stat.size <= IMAGE_INLINE_LIMIT) {
+        const bytes = await fs.readFile(filePath);
+        return {
+            content: [
+                { type: 'text', text: `File: ${args.filename} | ${formatSize(stat.size)}\nPath: ${filePath}` },
+                { type: 'image', data: bytes.toString('base64'), mimeType: imageMime },
+            ],
+        };
+    }
+    // Too large or unsupported — path reference only
+    const label = imageMime ? 'image (too large to display inline)' : isText ? 'text' : 'binary';
+    return {
+        content: [{
+                type: 'text',
+                text: `File: ${args.filename} | ${formatSize(stat.size)} | ${label}\nPath: ${filePath}\n\nUse manage_jira_media upload with workspaceFile to upload, or manage_workspace delete to remove.`,
+            }],
+    };
+}
+async function handleWrite(args) {
+    if (!args.filename) {
+        return { content: [{ type: 'text', text: 'filename is required for write operation' }], isError: true };
+    }
+    if (!args.content) {
+        return { content: [{ type: 'text', text: 'content (base64-encoded) is required for write operation' }], isError: true };
+    }
+    const status = await ensureWorkspaceDir();
+    if (!status.valid) {
+        return { content: [{ type: 'text', text: `Workspace invalid: ${status.warning}` }], isError: true };
+    }
+    const filePath = resolveWorkspacePath(args.filename);
+    await verifyPathSafety(filePath);
+    await ensureParentDir(filePath);
+    const buffer = Buffer.from(args.content, 'base64');
+    await fs.writeFile(filePath, buffer);
+    return {
+        content: [{
+                type: 'text',
+                text: `Written: ${args.filename} (${formatSize(buffer.length)})\nPath: ${filePath}`,
+            }],
+    };
+}
+async function handleDelete(args) {
+    if (!args.filename) {
+        return { content: [{ type: 'text', text: 'filename is required for delete operation' }], isError: true };
+    }
+    const filePath = resolveWorkspacePath(args.filename);
+    await verifyPathSafety(filePath);
+    try {
+        const stat = await fs.stat(filePath);
+        if (stat.isDirectory()) {
+            await fs.rm(filePath, { recursive: true });
+            return { content: [{ type: 'text', text: `Deleted local directory: ${args.filename} (Jira attachments unaffected)` }] };
+        }
+        await fs.unlink(filePath);
+    }
+    catch {
+        return { content: [{ type: 'text', text: `File not found in workspace: ${args.filename}` }], isError: true };
+    }
+    return { content: [{ type: 'text', text: `Deleted local file: ${args.filename} (Jira attachments unaffected)` }] };
+}
+async function handleMkdir(args) {
+    if (!args.filename) {
+        return { content: [{ type: 'text', text: 'filename (directory path) is required for mkdir operation' }], isError: true };
+    }
+    const status = await ensureWorkspaceDir();
+    if (!status.valid) {
+        return { content: [{ type: 'text', text: `Workspace invalid: ${status.warning}` }], isError: true };
+    }
+    const dirPath = resolveWorkspacePath(args.filename);
+    await verifyPathSafety(dirPath);
+    await fs.mkdir(dirPath, { recursive: true, mode: 0o755 });
+    return {
+        content: [{
+                type: 'text',
+                text: `Created: ${args.filename}/\nPath: ${dirPath}`,
+            }],
+    };
+}
+async function handleMove(args) {
+    if (!args.filename) {
+        return { content: [{ type: 'text', text: 'filename (source path) is required for move operation' }], isError: true };
+    }
+    if (!args.destination) {
+        return { content: [{ type: 'text', text: 'destination path is required for move operation' }], isError: true };
+    }
+    const srcPath = resolveWorkspacePath(args.filename);
+    await verifyPathSafety(srcPath);
+    const destPath = resolveWorkspacePath(args.destination);
+    await verifyPathSafety(destPath);
+    try {
+        await fs.stat(srcPath);
+    }
+    catch {
+        return { content: [{ type: 'text', text: `Source not found in workspace: ${args.filename}` }], isError: true };
+    }
+    await ensureParentDir(destPath);
+    await fs.rename(srcPath, destPath);
+    return {
+        content: [{
+                type: 'text',
+                text: `Moved: ${args.filename} -> ${args.destination}\nPath: ${destPath}`,
+            }],
+    };
+}

package/build/index.js

@@ -11,14 +11,17 @@ import { handleAnalysisRequest } from './handlers/analysis-handler.js';
 import { handleBoardRequest } from './handlers/board-handlers.js';
 import { handleFilterRequest } from './handlers/filter-handlers.js';
 import { handleIssueRequest } from './handlers/issue-handlers.js';
+import { handleMediaRequest } from './handlers/media-handler.js';
 import { handlePlanRequest } from './handlers/plan-handler.js';
 import { handleProjectRequest } from './handlers/project-handlers.js';
 import { createQueueHandler } from './handlers/queue-handler.js';
 import { setupResourceHandlers } from './handlers/resource-handlers.js';
 import { handleSprintRequest } from './handlers/sprint-handlers.js';
+import { handleWorkspaceRequest } from './handlers/workspace-handler.js';
 import { promptDefinitions } from './prompts/prompt-definitions.js';
 import { getPrompt } from './prompts/prompt-messages.js';
 import { toolSchemas } from './schemas/tool-schemas.js';
+import { normalizeArgs } from './utils/normalize-args.js';
 // Jira credentials from environment variables
 const JIRA_EMAIL = process.env.JIRA_EMAIL;
 const JIRA_API_TOKEN = process.env.JIRA_API_TOKEN;
@@ -160,6 +163,8 @@ class JiraServer {
                     manage_jira_sprint: handleSprintRequest,
                     manage_jira_filter: handleFilterRequest,
                     analyze_jira_issues: (client, req) => handleAnalysisRequest(client, req, this.graphqlClient, this.cache),
+                    manage_jira_media: (client, req) => handleMediaRequest(client, normalizeArgs(req.params.arguments ?? {})),
+                    manage_workspace: (_client, req) => handleWorkspaceRequest(normalizeArgs(req.params.arguments ?? {})),
                 };
                 const handlers = {
                     ...toolHandlers,

package/build/schemas/tool-schemas.js

@@ -490,6 +490,72 @@ export const toolSchemas = {
             required: [],
         },
     },
+    manage_jira_media: {
+        name: 'manage_jira_media',
+        description: 'Manage file attachments on Jira issues (remote). Operations here affect Jira — delete permanently removes an attachment from the issue for all users. Use manage_workspace for local file staging. Downloads copy from Jira to workspace; uploads copy from workspace to Jira.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                operation: {
+                    type: 'string',
+                    enum: ['list', 'upload', 'download', 'view', 'get_info', 'delete'],
+                    description: 'Operation to perform. list: attachments on an issue. upload: copy file from workspace to Jira issue. download: copy attachment from Jira to local workspace. view: display image inline. get_info: attachment metadata. delete: permanently remove attachment from Jira (affects all users).',
+                },
+                issueKey: {
+                    type: 'string',
+                    description: 'Issue key (e.g., PROJ-123). Required for list and upload.',
+                },
+                attachmentId: {
+                    type: 'string',
+                    description: 'Attachment ID. Required for download, view, get_info, delete.',
+                },
+                filename: {
+                    type: 'string',
+                    description: 'Filename for upload (required) or download (optional override).',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Base64-encoded file content for upload. Alternative to workspaceFile.',
+                },
+                mediaType: {
+                    type: 'string',
+                    description: 'MIME type (e.g., "image/png", "application/pdf"). Required for upload.',
+                },
+                workspaceFile: {
+                    type: 'string',
+                    description: 'Filename in workspace to upload. Alternative to content. Use manage_workspace list to see staged files.',
+                },
+            },
+            required: ['operation'],
+        },
+    },
+    manage_workspace: {
+        name: 'manage_workspace',
+        description: 'Manage files in the local workspace staging area (local only — no Jira impact). Files downloaded via manage_jira_media land here. Delete only removes the local copy. Use manage_jira_media to affect attachments on Jira issues.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                operation: {
+                    type: 'string',
+                    enum: ['list', 'read', 'write', 'delete', 'mkdir', 'move'],
+                    description: 'Operation to perform. list: show staged files. read: display file content. write: stage base64 content. delete: remove local file only (does not affect Jira). mkdir: create directory. move: rename/relocate file.',
+                },
+                filename: {
+                    type: 'string',
+                    description: 'Filename or path within workspace. Supports nesting with / separators.',
+                },
+                destination: {
+                    type: 'string',
+                    description: 'Destination path for move operation.',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Base64-encoded content for write operation.',
+                },
+            },
+            required: ['operation'],
+        },
+    },
     queue_jira_operations: {
         name: 'queue_jira_operations',
         description: 'Execute multiple Jira operations in a single call. Operations run sequentially with result references ($0.key) and per-operation error strategies (bail/continue). Powerful for analysis pipelines: create a filter, then run multiple analyze_jira_issues calls against $0.filterId with different groupBy/compute — all in one call.',
@@ -503,7 +569,7 @@ export const toolSchemas = {
                         properties: {
                             tool: {
                                 type: 'string',
-                                enum: ['manage_jira_issue', 'manage_jira_filter', 'manage_jira_sprint', 'manage_jira_project', 'manage_jira_board', 'analyze_jira_issues'],
+                                enum: ['manage_jira_issue', 'manage_jira_filter', 'manage_jira_sprint', 'manage_jira_project', 'manage_jira_board', 'analyze_jira_issues', 'manage_jira_media', 'manage_workspace'],
                                 description: 'Which tool to call.',
                             },
                             args: {

package/build/utils/next-steps.js

@@ -18,7 +18,7 @@ export function issueNextSteps(operation, issueKey) {
             steps.push({ description: 'Transition to a new status', tool: 'manage_jira_issue', example: { operation: 'transition', issueKey, expand: ['transitions'] } }, { description: 'Add to a sprint', tool: 'manage_jira_sprint', example: { operation: 'manage_issues', sprintId: '<id>', add: [issueKey] } }, { description: 'Link to a related issue', tool: 'manage_jira_issue', example: { operation: 'link', issueKey, linkedIssueKey: '<key>', linkType: 'relates to' } }, { description: 'Read jira://custom-fields to discover available custom fields for this instance' });
             break;
         case 'get':
-            steps.push({ description: 'Update fields', tool: 'manage_jira_issue', example: { operation: 'update', issueKey } }, { description: 'Add a comment', tool: 'manage_jira_issue', example: { operation: 'comment', issueKey, comment: '<text>' } }, { description: 'View available transitions', tool: 'manage_jira_issue', example: { operation: 'get', issueKey, expand: ['transitions'] } });
+            steps.push({ description: 'Update fields', tool: 'manage_jira_issue', example: { operation: 'update', issueKey } }, { description: 'Add a comment', tool: 'manage_jira_issue', example: { operation: 'comment', issueKey, comment: '<text>' } }, { description: 'View available transitions', tool: 'manage_jira_issue', example: { operation: 'get', issueKey, expand: ['transitions'] } }, { description: 'Manage attachments (upload, download, view)', tool: 'manage_jira_media', example: { operation: 'list', issueKey } });
             break;
         case 'update':
             steps.push({ description: 'View the updated issue', tool: 'manage_jira_issue', example: { operation: 'get', issueKey } }, { description: 'Transition to a new status', tool: 'manage_jira_issue', example: { operation: 'get', issueKey, expand: ['transitions'] } }, { description: 'Read jira://custom-fields to discover available custom fields for this instance' });
@@ -207,6 +207,21 @@ export function goalNextSteps(operation, goalKey, workItemCount) {
     }
     return steps.length > 0 ? formatSteps(steps) : '';
 }
+export function mediaNextSteps(operation, context) {
+    const steps = [];
+    switch (operation) {
+        case 'list':
+            steps.push({ description: 'Download an attachment to workspace', tool: 'manage_jira_media', example: { operation: 'download', attachmentId: '<id>' } }, { description: 'View an image attachment inline', tool: 'manage_jira_media', example: { operation: 'view', attachmentId: '<id>' } }, { description: 'Upload a file to this issue', tool: 'manage_jira_media', example: { operation: 'upload', issueKey: context.issueKey, filename: '<name>', mediaType: '<mime>', workspaceFile: '<staged file>' } });
+            break;
+        case 'upload':
+            steps.push({ description: 'List attachments on this issue', tool: 'manage_jira_media', example: { operation: 'list', issueKey: context.issueKey } }, { description: 'View the issue', tool: 'manage_jira_issue', example: { operation: 'get', issueKey: context.issueKey } });
+            break;
+        case 'download':
+            steps.push({ description: 'View staged files in workspace', tool: 'manage_workspace', example: { operation: 'list' } }, { description: 'Upload to another issue', tool: 'manage_jira_media', example: { operation: 'upload', issueKey: '<target issue>', workspaceFile: '<filename>', mediaType: '<mime>', filename: '<filename>' } }, { description: 'Read the downloaded file', tool: 'manage_workspace', example: { operation: 'read', filename: '<filename>' } });
+            break;
+    }
+    return steps.length > 0 ? formatSteps(steps) : '';
+}
 export function analysisNextSteps(jql, issueKeys, truncated = false, groupBy, filterSource) {
     const steps = [];
     if (issueKeys.length > 0) {

package/build/workspace/index.js

@@ -0,0 +1 @@
+export { checkWorkspaceStatus, dataDir, ensureParentDir, ensureWorkspaceDir, formatSize, getWorkspaceDir, resolveWorkspacePath, sanitizeFilename, sanitizePath, validateWorkspaceDir, verifyPathSafety, } from './workspace.js';

package/build/workspace/workspace.js

@@ -0,0 +1,187 @@
+/**
+ * Workspace directory — safe sandbox for file staging operations.
+ *
+ * All file operations (attachment download, upload, media staging) are jailed
+ * to this directory. Prevents agents from accidentally operating on home
+ * directories, document folders, or cloud sync mount points.
+ *
+ * See ADR-211: Attachment and Workspace Management.
+ */
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+const APP_NAME = 'jira-cloud-mcp';
+// ── XDG Paths ──────────────────────────────────────────────
+export function dataDir() {
+    const base = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share');
+    return path.join(base, APP_NAME);
+}
+// ── Forbidden Paths ────────────────────────────────────────
+/** Paths that must never be used as the workspace root. */
+const FORBIDDEN_PATHS = [
+    () => process.env.HOME ?? '',
+    () => process.env.USERPROFILE ?? '',
+    () => process.env.HOME ? path.join(process.env.HOME, 'Documents') : '',
+    () => process.env.HOME ? path.join(process.env.HOME, 'Desktop') : '',
+    () => process.env.HOME ? path.join(process.env.HOME, 'Downloads') : '',
+    () => process.env.USERPROFILE ? path.join(process.env.USERPROFILE, 'Documents') : '',
+    () => process.env.USERPROFILE ? path.join(process.env.USERPROFILE, 'Desktop') : '',
+    () => process.env.USERPROFILE ? path.join(process.env.USERPROFILE, 'Downloads') : '',
+];
+/** Path substrings that indicate a cloud sync mount. */
+const CLOUD_SYNC_PATTERNS = [
+    'google-drive',
+    'Google Drive',
+    'GoogleDrive',
+    'gdrive',
+    'My Drive',
+    'OneDrive',
+    'onedrive',
+    'Dropbox',
+    'dropbox',
+    'iCloud Drive',
+    'iCloudDrive',
+];
+// ── Workspace Directory ────────────────────────────────────
+/** Get the workspace directory path, respecting env overrides. */
+export function getWorkspaceDir() {
+    const configured = process.env.WORKSPACE_DIR;
+    if (configured && !configured.includes('${')) {
+        return configured;
+    }
+    return path.join(dataDir(), 'workspace');
+}
+/**
+ * Validate workspace dir is safe. Throws if it IS a protected directory.
+ * Being a subdirectory OF a protected directory is fine.
+ */
+export function validateWorkspaceDir(dir) {
+    const resolved = path.resolve(dir);
+    for (const getForbidden of FORBIDDEN_PATHS) {
+        const forbidden = getForbidden();
+        if (forbidden && path.resolve(forbidden) === resolved) {
+            throw new Error(`Workspace directory cannot be ${resolved} — use a subdirectory like ${getWorkspaceDir()}`);
+        }
+    }
+    for (const pattern of CLOUD_SYNC_PATTERNS) {
+        if (resolved.toLowerCase().includes(pattern.toLowerCase())) {
+            throw new Error(`Workspace directory cannot be inside a cloud sync mount (${resolved}) — this could cause sync conflicts`);
+        }
+    }
+    if (resolved === '/' || resolved === 'C:\\') {
+        throw new Error('Workspace directory cannot be the filesystem root');
+    }
+}
+/** Check workspace directory status without throwing. */
+export function checkWorkspaceStatus() {
+    const dir = getWorkspaceDir();
+    try {
+        validateWorkspaceDir(dir);
+        return { path: dir, valid: true };
+    }
+    catch (err) {
+        return { path: dir, valid: false, warning: err.message };
+    }
+}
+/** Ensure the workspace directory exists and is validated. */
+export async function ensureWorkspaceDir() {
+    const status = checkWorkspaceStatus();
+    if (status.valid) {
+        await fs.mkdir(status.path, { recursive: true, mode: 0o755 });
+    }
+    return status;
+}
+// ── Filename Sanitization ──────────────────────────────────
+/**
+ * Sanitize a single filename segment (no separators).
+ * Strips null bytes, control characters, path separators, and dangerous chars.
+ */
+export function sanitizeFilename(filename) {
+    return filename
+        // Remove null bytes and control characters
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\x00-\x1f\x7f]/g, '')
+        // Remove path separators
+        .replace(/[/\\]/g, '_')
+        // Remove other dangerous characters
+        .replace(/[<>:"|?*]/g, '_')
+        // Collapse multiple underscores
+        .replace(/_+/g, '_')
+        // Remove leading dots (hidden files) and trailing dots/spaces
+        .replace(/^\.+/, '')
+        .replace(/[. ]+$/, '')
+        || 'unnamed';
+}
+/**
+ * Sanitize a workspace path that may contain directory separators.
+ * Each path segment is sanitized individually, preserving the directory structure.
+ * Empty segments and traversal attempts (e.g. '..') are removed.
+ */
+export function sanitizePath(filePath) {
+    // Normalize separators to forward slash, split into segments
+    const segments = filePath
+        .replace(/\\/g, '/')
+        .split('/')
+        .map(seg => sanitizeFilename(seg))
+        // Drop segments that sanitized to 'unnamed' (e.g. '..' → '' → 'unnamed').
+        // Only keep 'unnamed' if the entire input was empty (fallback sentinel).
+        .filter(seg => seg !== 'unnamed' || filePath.trim() === '');
+    if (segments.length === 0)
+        return 'unnamed';
+    return segments.join(path.sep);
+}
+// ── Path Resolution ────────────────────────────────────────
+/**
+ * Resolve a file path within the workspace directory.
+ * Supports nested paths (e.g. 'projects/report.csv').
+ * Prevents path traversal and sanitizes each path segment.
+ */
+export function resolveWorkspacePath(filePath) {
+    const dir = getWorkspaceDir();
+    // Use sanitizePath for nested paths, sanitizeFilename for flat filenames
+    const sanitized = filePath.includes('/') || filePath.includes('\\')
+        ? sanitizePath(filePath)
+        : sanitizeFilename(filePath);
+    const resolved = path.resolve(dir, sanitized);
+    const resolvedDir = path.resolve(dir);
+    if (!resolved.startsWith(resolvedDir + path.sep) && resolved !== resolvedDir) {
+        throw new Error(`Path traversal detected: "${filePath}" resolves outside workspace directory`);
+    }
+    return resolved;
+}
+/**
+ * Ensure parent directories exist for a workspace path.
+ * Call after resolveWorkspacePath to create intermediate dirs.
+ */
+export async function ensureParentDir(filePath) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true, mode: 0o755 });
+}
+// ── Formatting ─────────────────────────────────────────────
+/** Format byte count as human-readable size. */
+export function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+// ── Path Safety ────────────────────────────────────────────
+/**
+ * Verify a file path is safe after symlink resolution.
+ * Must be called before any fs operation on a workspace path.
+ */
+export async function verifyPathSafety(filePath) {
+    const dir = path.resolve(getWorkspaceDir());
+    try {
+        const real = await fs.realpath(filePath);
+        if (!real.startsWith(dir + path.sep) && real !== dir) {
+            throw new Error(`Symlink escape detected: "${filePath}" resolves to "${real}" outside workspace`);
+        }
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaronsb/jira-cloud-mcp",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "mcpName": "io.github.aaronsb/jira-cloud",
   "description": "Model Context Protocol (MCP) server for Jira Cloud - enables AI assistants to interact with Jira",
   "type": "module",