@aaronsb/jira-cloud-mcp 0.9.0 → 0.11.0

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,18 @@ 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 { classifyFieldErrors } from './utils/field-error-classification.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 +164,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,
@@ -243,6 +249,11 @@ class JiraServer {
                         for (const [field, msg] of Object.entries(fieldErrors)) {
                             lines.push(`- \`${field}\`: ${msg}`);
                         }
+                        // Distinguish the failure modes Jira's message conflates (ADR-213 §A5, #49 / #52c).
+                        const guidance = classifyFieldErrors(fieldErrors);
+                        if (guidance.length > 0) {
+                            lines.push('', '**What to do:**', ...guidance);
+                        }
                     }
                     // On create failures, invalidate cache and append required fields guidance
                     const reqArgs = request.params.arguments;

package/build/mcp/markdown-renderer.js

@@ -89,13 +89,10 @@ function stripHtml(html) {
         .replace(/\s+/g, ' ')
         .trim();
 }
-// ============================================================================
-// Issue Rendering
-// ============================================================================
 /**
  * Render a single issue as markdown
  */
-export function renderIssue(issue, transitions) {
+export function renderIssue(issue, transitions, opts = {}) {
     const lines = [];
     lines.push(`# ${issue.key}: ${issue.summary}`);
     lines.push('');
@@ -170,17 +167,33 @@ export function renderIssue(issue, transitions) {
             lines.push(`[${startIdx + i}/${issue.comments.length}] ${comment.author} (${formatDate(comment.created)}): ${truncate(preview, 200)}`);
         }
     }
-    // Custom fields (from catalog discovery)
-    if (issue.customFieldValues && issue.customFieldValues.length > 0) {
+    // Custom fields — progressive reveal (ADR-214). Default is a breadcrumb pointing at the
+    // opt-in expand and the scoped resource; the full dump is gated behind `customFields: 'dump'`.
+    // Zero populated → silent in every mode.
+    const customFieldsMode = opts.customFields ?? 'breadcrumb';
+    const cfs = issue.customFieldValues ?? [];
+    const populatedCount = cfs.length;
+    if (customFieldsMode === 'dump' && populatedCount > 0) {
         lines.push('');
         lines.push('Custom Fields:');
-        for (const cf of issue.customFieldValues) {
+        for (const cf of cfs) {
             const displayValue = Array.isArray(cf.value)
                 ? cf.value.join(', ')
                 : String(cf.value);
             lines.push(`${cf.name} (${cf.type}): ${displayValue}`);
         }
     }
+    else if (customFieldsMode === 'breadcrumb' && populatedCount > 0) {
+        lines.push('');
+        // Issue-type names can contain spaces ("User Story", "Service Request") — the catalog
+        // resource emitter encodes the type and the resolver decodes it (resource-handlers.ts:148, 533),
+        // so the breadcrumb URI has to encode too or the link round-trips wrong.
+        const uri = opts.projectKey && opts.issueTypeName
+            ? ` For what's settable on this issue type: read \`jira://custom-fields/${opts.projectKey}/${encodeURIComponent(opts.issueTypeName)}\`.`
+            : '';
+        lines.push(`📋 ${populatedCount} populated custom field${populatedCount === 1 ? '' : 's'} not shown. ` +
+            `To view: \`expand: ["custom_fields"]\`.${uri}`);
+    }
     // Status history (if requested via expand: ["history"])
     if (issue.statusHistory && issue.statusHistory.length > 0) {
         lines.push('');

package/build/schemas/tool-schemas.js

@@ -142,7 +142,7 @@ export const toolSchemas = {
     },
     manage_jira_issue: {
         name: 'manage_jira_issue',
-        description: 'Get, create, update, delete, move, transition, comment on, link, log work on, or explore hierarchy of Jira issues',
+        description: 'Get, create, update, delete, move, transition, comment on, link, log work on, or explore hierarchy of Jira issues. For custom-field writes, consult `jira://capabilities` (field routing) and `jira://custom-fields/{projectKey}/{issueType}` (what is settable here) — some fields need dedicated tools and others auto-resolve names to ids.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -186,7 +186,7 @@ export const toolSchemas = {
                 },
                 customFields: {
                     type: 'object',
-                    description: 'Custom field values as key-value pairs.',
+                    description: 'Custom field values as { name | id : value }. Names auto-resolve to customfield_NNNNN. Read `jira://capabilities` for the field-routing table (which fields need a dedicated tool or have value-resolution) and `jira://custom-fields/{projectKey}/{issueType}` for what is settable on a given screen, with types and clearing semantics.',
                 },
                 dueDate: {
                     type: ['string', 'null'],
@@ -265,9 +265,9 @@ export const toolSchemas = {
                     type: 'array',
                     items: {
                         type: 'string',
-                        enum: ['comments', 'transitions', 'attachments', 'related_issues', 'history'],
+                        enum: ['comments', 'transitions', 'attachments', 'related_issues', 'history', 'custom_fields'],
                     },
-                    description: 'Additional fields to include in the response.',
+                    description: 'Additional fields to include in the response. Populated custom fields are NOT shown by default — `get` emits a one-line breadcrumb with the count and the opt-in. Pass "custom_fields" to render the full populated dump. For what is *settable* on this issue type (with usage hints), read the scoped resource `jira://custom-fields/{projectKey}/{issueType}` instead.',
                 },
             },
             required: ['operation'],
@@ -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/field-error-classification.js

@@ -0,0 +1,65 @@
+/**
+ * Field-rejection error classification (ADR-213 §A5, issues #49 and #52c).
+ *
+ * Jira rejects a `customFields` write with one opaque message —
+ *   "Field 'X' cannot be set. It is not on the appropriate screen, or unknown."
+ * — that conflates several failure modes, each needing a different recovery. Given Jira's
+ * field-error map (keyed by field id or name), this returns extra guidance lines that pull
+ * those modes apart:
+ *
+ *   - field has a dedicated path (Sprint, Epic Link, Parent, Rank) → point at the right tool/param
+ *   - field exists in the catalog but isn't writable here → "editable inline in the UI, or via the
+ *     owning app — not reachable through the standard edit endpoint"
+ *   - field isn't in the catalog → "not a field this instance exposes — see jira://custom-fields"
+ *   - catalog unavailable → say so; the name may be right but can't be verified here
+ */
+import { fieldDiscovery } from '../client/field-discovery.js';
+import { routeForField } from '../extensions/index.js';
+/** Looks like a Connect/Forge app field key (e.g. `io.tempo.jira__account`) rather than a
+ *  `customfield_NNNNN` id or a plain field name — Jira sometimes reports field errors this way. */
+function looksLikeAppFieldKey(key) {
+    return !key.startsWith('customfield_') && (key.includes('__') || /^[a-z][\w-]*(\.[\w-]+){2,}/i.test(key));
+}
+export function classifyFieldErrors(fieldErrors) {
+    const out = [];
+    const catalogState = fieldDiscovery.getState();
+    for (const fieldKey of Object.keys(fieldErrors)) {
+        const catalogEntry = fieldKey.startsWith('customfield_')
+            ? fieldDiscovery.getFieldById(fieldKey)
+            : undefined;
+        const humanName = catalogEntry?.name ?? fieldKey;
+        const resolvedId = fieldKey.startsWith('customfield_')
+            ? fieldKey
+            : fieldDiscovery.resolveNameToId(fieldKey);
+        const isKnownField = !!catalogEntry || !!resolvedId;
+        const route = routeForField(fieldKey) ?? routeForField(humanName);
+        if (route) {
+            out.push(`  → \`${humanName}\`: ${route.unhandled.message}`);
+            continue;
+        }
+        if (isKnownField) {
+            out.push(`  → \`${humanName}\` exists on this instance but the write was rejected — it may be off ` +
+                `the Edit screen for this issue type, hidden by a field configuration, or an app-managed ` +
+                `field that wants a different value format (e.g. a numeric id rather than a name). It may ` +
+                `still be editable inline in the Jira UI.`);
+            continue;
+        }
+        if (looksLikeAppFieldKey(fieldKey)) {
+            out.push(`  → \`${fieldKey}\` is a field registered by a Connect/Forge app — the write was rejected ` +
+                `(see the message above). App-managed fields often expect a specific value format ` +
+                `(e.g. a numeric account/option id rather than a name) or must be set through the app's own ` +
+                `interface; setting it inline in the Jira UI usually works.`);
+            continue;
+        }
+        if (catalogState === 'unavailable') {
+            out.push(`  → \`${fieldKey}\`: couldn't verify this field name — the custom-field catalog is ` +
+                `unavailable (the admin field API returned 403 and the basic fallback also failed). The ` +
+                `name may be correct but can't be checked here.`);
+            continue;
+        }
+        out.push(`  → \`${fieldKey}\` isn't a custom field this instance exposes (checked the ${catalogState} ` +
+            `catalog). Read jira://custom-fields for available names, or ` +
+            `jira://custom-fields/{projectKey}/{issueType} for the fields on a specific issue type.`);
+    }
+    return out;
+}

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';