@aaronsb/jira-cloud-mcp 0.8.1 → 0.10.0

package/build/client/graphql-client.js

@@ -57,22 +57,42 @@ export async function discoverCloudId(host, email, apiToken) {
 export class GraphQLClient {
     authHeader;
     cloudId;
-    constructor(email, apiToken, cloudId) {
+    tenantedEndpoint;
+    constructor(email, apiToken, cloudId, host) {
         this.authHeader = buildAuthHeader(email, apiToken);
         this.cloudId = cloudId;
+        this.tenantedEndpoint = host
+            ? `https://${extractHostname(host)}/gateway/api/graphql`
+            : null;
     }
     getCloudId() {
         return this.cloudId;
     }
+    /** Site container ARI for Townsquare queries */
+    getSiteAri() {
+        return `ari:cloud:townsquare::site/${this.cloudId}`;
+    }
     async query(query, variables = {}) {
+        return this._fetch(AGG_ENDPOINT, query, variables, {
+            'X-ExperimentalApi': 'JiraPlan,JiraPlansSupport',
+        });
+    }
+    /** Query the tenanted endpoint ({host}/gateway/api/graphql) for site-scoped APIs like Townsquare */
+    async queryTenanted(query, variables = {}) {
+        if (!this.tenantedEndpoint) {
+            return { success: false, error: 'Tenanted endpoint not available (no host configured)' };
+        }
+        return this._fetch(this.tenantedEndpoint, query, variables);
+    }
+    async _fetch(endpoint, query, variables, extraHeaders) {
         try {
-            const response = await fetch(AGG_ENDPOINT, {
+            const response = await fetch(endpoint, {
                 method: 'POST',
                 headers: {
                     'Authorization': this.authHeader,
                     'Content-Type': 'application/json',
                     'Accept': 'application/json',
-                    'X-ExperimentalApi': 'JiraPlan,JiraPlansSupport',
+                    ...extraHeaders,
                 },
                 body: JSON.stringify({
                     query,

package/build/client/graphql-goals.js

@@ -0,0 +1,398 @@
+// --- Queries ---
+const GOALS_SEARCH_QUERY = `
+  query GoalsSearch($containerId: ID!, $searchString: String!, $sort: [TownsquareGoalSortEnum], $first: Int, $after: String) {
+    goals_search(containerId: $containerId, searchString: $searchString, sort: $sort, first: $first, after: $after) {
+      edges {
+        node {
+          id
+          name
+          key
+          url
+          state { value label }
+          owner { name }
+          parentGoal { name key }
+          subGoals(first: 50) {
+            edges { node { name key state { value } } }
+          }
+          workItems(first: 50) @optIn(to: "GraphStoreJiraEpicContributesToAtlasGoal") {
+            edges { node { ... on JiraIssue { key } } }
+          }
+        }
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+    }
+  }
+`;
+const GOAL_BY_KEY_QUERY = `
+  query GoalByKey($containerId: ID!, $goalKey: String!) {
+    goals_byKey(containerId: $containerId, goalKey: $goalKey) {
+      id
+      name
+      key
+      url
+      state { value label }
+      owner { name }
+      parentGoal { name key }
+      description
+      subGoals(first: 50) {
+        edges {
+          node {
+            id name key url
+            state { value label }
+            owner { name }
+            parentGoal { name key }
+            description
+          }
+        }
+      }
+      projects(first: 20) {
+        edges { node { name state { value } } }
+      }
+      workItems(first: 100) @optIn(to: "GraphStoreJiraEpicContributesToAtlasGoal") {
+        edges {
+          node {
+            ... on JiraIssue {
+              key
+              summary
+              status { name }
+              issueType { name }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+// --- Helpers ---
+/** Extract plain text from an ADF JSON string or return as-is if not ADF */
+function extractAdfText(raw) {
+    if (!raw)
+        return null;
+    try {
+        const doc = JSON.parse(raw);
+        if (doc?.type !== 'doc' || !Array.isArray(doc.content))
+            return raw;
+        return extractTextFromNodes(doc.content).trim() || null;
+    }
+    catch {
+        return raw;
+    }
+}
+function extractTextFromNodes(nodes) {
+    let text = '';
+    for (const node of nodes) {
+        if (node.text)
+            text += node.text;
+        if (Array.isArray(node.content))
+            text += extractTextFromNodes(node.content);
+        if (node.type === 'paragraph' || node.type === 'heading')
+            text += '\n';
+        if (node.type === 'hardBreak')
+            text += '\n';
+        if (node.type === 'listItem')
+            text += '- ';
+    }
+    return text;
+}
+/** Wrap plain text in ADF document format (required for Townsquare description/summary fields) */
+function toAdf(text) {
+    return JSON.stringify({
+        version: 1, type: 'doc',
+        content: [{ type: 'paragraph', content: [{ type: 'text', text }] }],
+    });
+}
+// --- Functions ---
+export async function searchGoals(client, searchString, sort = 'HIERARCHY_ASC', first = 50) {
+    const result = await client.queryTenanted(GOALS_SEARCH_QUERY, {
+        containerId: client.getSiteAri(),
+        searchString,
+        sort: [sort],
+        first,
+    });
+    if (!result.success || !result.data) {
+        return { success: false, error: result.error ?? 'No data returned' };
+    }
+    const edges = result.data.goals_search.edges;
+    const goals = edges.map(e => ({
+        id: e.node.id,
+        name: e.node.name,
+        key: e.node.key,
+        url: e.node.url,
+        state: e.node.state,
+        owner: e.node.owner,
+        parentGoal: e.node.parentGoal,
+        description: null,
+    }));
+    const workItemCounts = new Map();
+    for (const e of edges) {
+        const count = e.node.workItems?.edges?.filter(w => w.node.key).length ?? 0;
+        workItemCounts.set(e.node.key, count);
+    }
+    return { success: true, goals, workItemCounts };
+}
+export async function getGoalByKey(client, goalKey) {
+    const result = await client.queryTenanted(GOAL_BY_KEY_QUERY, {
+        containerId: client.getSiteAri(),
+        goalKey,
+    });
+    if (!result.success || !result.data) {
+        return { success: false, error: result.error ?? 'No data returned' };
+    }
+    const node = result.data.goals_byKey;
+    if (!node) {
+        return { success: false, error: `Goal ${goalKey} not found` };
+    }
+    const goal = {
+        id: node.id,
+        name: node.name,
+        key: node.key,
+        url: node.url,
+        state: node.state,
+        owner: node.owner,
+        parentGoal: node.parentGoal,
+        description: extractAdfText(node.description),
+        subGoals: (node.subGoals?.edges ?? []).map(e => ({
+            id: e.node.id,
+            name: e.node.name,
+            key: e.node.key,
+            url: e.node.url,
+            state: e.node.state,
+            owner: e.node.owner,
+            parentGoal: e.node.parentGoal,
+            description: extractAdfText(e.node.description),
+        })),
+        projects: (node.projects?.edges ?? []).map(e => e.node),
+        workItems: (node.workItems?.edges ?? [])
+            .filter(e => e.node.key)
+            .map(e => ({
+            key: e.node.key,
+            summary: e.node.summary ?? '',
+            status: e.node.status ?? { name: 'Unknown' },
+            issueType: e.node.issueType ?? { name: 'Unknown' },
+        })),
+    };
+    return { success: true, goal };
+}
+/**
+ * Resolve all Jira issue keys linked to a goal and optionally its sub-goals.
+ * Returns keys suitable for a `key in (...)` JQL query.
+ */
+export async function resolveGoalWorkItems(client, goalKey, includeSubGoals = true) {
+    const result = await getGoalByKey(client, goalKey);
+    if (!result.success || !result.goal) {
+        return { success: false, error: result.error };
+    }
+    const goal = result.goal;
+    const issueKeys = new Set(goal.workItems.map(w => w.key));
+    if (includeSubGoals && goal.subGoals.length > 0) {
+        // Fetch each sub-goal's work items
+        const subResults = await Promise.all(goal.subGoals.map(sg => getGoalByKey(client, sg.key)));
+        for (const sub of subResults) {
+            if (sub.success && sub.goal) {
+                for (const w of sub.goal.workItems) {
+                    issueKeys.add(w.key);
+                }
+            }
+        }
+    }
+    return { success: true, issueKeys: [...issueKeys], goal };
+}
+// --- Mutations ---
+const GOAL_TYPES_QUERY = `
+  query GoalTypes($containerId: ID!) {
+    goals_goalTypes(containerId: $containerId) {
+      edges { node { id } }
+    }
+  }
+`;
+// Session-level cache for goal type ARIs
+let cachedGoalTypeIds = null;
+async function resolveGoalTypes(client) {
+    if (cachedGoalTypeIds)
+        return cachedGoalTypeIds;
+    const result = await client.queryTenanted(GOAL_TYPES_QUERY, { containerId: client.getSiteAri() });
+    if (!result.success || !result.data)
+        return [];
+    cachedGoalTypeIds = result.data.goals_goalTypes.edges.map(e => e.node.id);
+    return cachedGoalTypeIds;
+}
+/** Resolve goal type: first type for top-level goals, last type for sub-goals */
+async function resolveGoalType(client, hasParent) {
+    const types = await resolveGoalTypes(client);
+    if (types.length === 0)
+        return null;
+    return hasParent ? types[types.length - 1] : types[0];
+}
+const GOAL_CREATE_MUTATION = `
+  mutation CreateGoal($input: TownsquareGoalsCreateInput!) {
+    goals_create(input: $input) {
+      success
+      errors { message }
+      goal { id name key url state { value label } }
+    }
+  }
+`;
+const GOAL_EDIT_MUTATION = `
+  mutation EditGoal($input: TownsquareGoalsEditInput!) {
+    goals_edit(input: $input) {
+      goal { id name key url state { value label } isArchived }
+    }
+  }
+`;
+const GOAL_CREATE_UPDATE_MUTATION = `
+  mutation CreateGoalUpdate($input: TownsquareGoalsCreateUpdateInput!) {
+    goals_createUpdate(input: $input) {
+      success
+      errors { message }
+      update { id url creationDate }
+    }
+  }
+`;
+const GOAL_LINK_WORK_ITEM_MUTATION = `
+  mutation LinkWorkItem($input: TownsquareGoalsLinkWorkItemInput!) {
+    goals_linkWorkItem(input: $input) {
+      goal { id name key }
+    }
+  }
+`;
+const GOAL_UNLINK_WORK_ITEM_MUTATION = `
+  mutation UnlinkWorkItem($input: TownsquareGoalsUnlinkWorkItemInput!) {
+    goals_unlinkWorkItem(input: $input) {
+      goal { id name key }
+    }
+  }
+`;
+/** Resolve a goal key to its ARI (needed for mutations) */
+async function resolveGoalId(client, goalKey) {
+    const result = await getGoalByKey(client, goalKey);
+    if (!result.success || !result.goal) {
+        return { success: false, error: result.error ?? `Goal ${goalKey} not found` };
+    }
+    return { success: true, goalId: result.goal.id };
+}
+export async function createGoal(client, opts) {
+    const hasParent = !!opts.parentGoalKey;
+    const goalTypeId = await resolveGoalType(client, hasParent);
+    if (!goalTypeId) {
+        return { success: false, error: 'Could not discover goal types for this instance. Goals may not be enabled.' };
+    }
+    const input = {
+        containerId: client.getSiteAri(),
+        name: opts.name,
+        goalTypeId,
+    };
+    if (opts.parentGoalKey) {
+        const parent = await resolveGoalId(client, opts.parentGoalKey);
+        if (!parent.success)
+            return { success: false, error: `Parent goal: ${parent.error}` };
+        input.parentGoalId = parent.goalId;
+    }
+    if (opts.targetDate) {
+        input.targetDate = { date: opts.targetDate, confidence: 'QUARTER' };
+    }
+    if (opts.description) {
+        input.description = toAdf(opts.description);
+    }
+    const result = await client.queryTenanted(GOAL_CREATE_MUTATION, { input });
+    if (!result.success || !result.data) {
+        return { success: false, error: result.error ?? 'Create failed' };
+    }
+    const mutation = result.data.goals_create;
+    if (!mutation.success || !mutation.goal) {
+        const msg = mutation.errors?.map(e => e.message).join('; ') ?? 'Unknown error';
+        return { success: false, error: msg };
+    }
+    return { success: true, goal: { name: mutation.goal.name, key: mutation.goal.key, url: mutation.goal.url } };
+}
+export async function editGoal(client, goalKey, opts) {
+    const resolved = await resolveGoalId(client, goalKey);
+    if (!resolved.success)
+        return { success: false, error: resolved.error };
+    const input = { goalId: resolved.goalId };
+    if (opts.name !== undefined)
+        input.name = opts.name;
+    if (opts.description !== undefined) {
+        input.description = toAdf(opts.description);
+    }
+    if (opts.targetDate !== undefined) {
+        input.targetDate = { date: opts.targetDate, confidence: 'QUARTER' };
+    }
+    if (opts.startDate !== undefined)
+        input.startDate = opts.startDate;
+    if (opts.archived !== undefined)
+        input.archived = opts.archived;
+    const result = await client.queryTenanted(GOAL_EDIT_MUTATION, { input });
+    if (!result.success)
+        return { success: false, error: result.error };
+    return { success: true };
+}
+export async function createGoalStatusUpdate(client, goalKey, status, summary) {
+    const resolved = await resolveGoalId(client, goalKey);
+    if (!resolved.success)
+        return { success: false, error: resolved.error };
+    const input = {
+        goalId: resolved.goalId,
+        status,
+    };
+    if (summary) {
+        input.summary = toAdf(summary);
+    }
+    const result = await client.queryTenanted(GOAL_CREATE_UPDATE_MUTATION, { input });
+    if (!result.success || !result.data) {
+        return { success: false, error: result.error ?? 'Status update failed' };
+    }
+    const mutation = result.data.goals_createUpdate;
+    if (!mutation.success) {
+        const msg = mutation.errors?.map(e => e.message).join('; ') ?? 'Status update failed (no error details)';
+        return { success: false, error: msg };
+    }
+    return { success: true };
+}
+const ISSUE_BY_KEY_QUERY = `
+  query IssueByKey($cloudId: ID!, $key: String!) {
+    jira { issueByKey(key: $key, cloudId: $cloudId) { id } }
+  }
+`;
+/** Resolve a Jira issue key to its ARI (needed for goal work item linking) */
+async function resolveIssueAri(client, issueKey) {
+    const result = await client.queryTenanted(ISSUE_BY_KEY_QUERY, { key: issueKey });
+    if (!result.success || !result.data?.jira?.issueByKey) {
+        return { success: false, error: `Issue ${issueKey} not found` };
+    }
+    return { success: true, issueAri: result.data.jira.issueByKey.id };
+}
+export async function linkWorkItem(client, goalKey, issueKey) {
+    const [resolved, issue] = await Promise.all([
+        resolveGoalId(client, goalKey),
+        resolveIssueAri(client, issueKey),
+    ]);
+    if (!resolved.success)
+        return { success: false, error: resolved.error };
+    if (!issue.success)
+        return { success: false, error: issue.error };
+    const result = await client.queryTenanted(GOAL_LINK_WORK_ITEM_MUTATION, {
+        input: { goalId: resolved.goalId, workItemId: issue.issueAri },
+    });
+    if (!result.success)
+        return { success: false, error: result.error };
+    return { success: true };
+}
+export async function unlinkWorkItem(client, goalKey, issueKey) {
+    const [resolved, issue] = await Promise.all([
+        resolveGoalId(client, goalKey),
+        resolveIssueAri(client, issueKey),
+    ]);
+    if (!resolved.success)
+        return { success: false, error: resolved.error };
+    if (!issue.success)
+        return { success: false, error: issue.error };
+    const result = await client.queryTenanted(GOAL_UNLINK_WORK_ITEM_MUTATION, {
+        input: { goalId: resolved.goalId, workItemId: issue.issueAri },
+    });
+    if (!result.success)
+        return { success: false, error: result.error };
+    return { success: true };
+}

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/analysis-handler.js

@@ -742,7 +742,7 @@ async function renderHierarchy(issues, graphqlClient) {
         }
     }
     if (parentKeys.size > MAX_HIERARCHY_ROOTS) {
-        lines.push('', `*Showing ${MAX_HIERARCHY_ROOTS} of ${parentKeys.size} root issues. Use analyze_jira_plan for a focused subtree.*`);
+        lines.push('', `*Showing ${MAX_HIERARCHY_ROOTS} of ${parentKeys.size} root issues. Use manage_jira_plan for a focused subtree.*`);
     }
     return lines.join('\n');
 }
@@ -858,11 +858,11 @@ export async function handleAnalysisRequest(jiraClient, request, graphqlClient,
     const dataRef = args.dataRef;
     if (dataRef && typeof dataRef === 'string' && dataRef.trim() !== '') {
         if (!cache) {
-            throw new McpError(ErrorCode.InvalidParams, 'dataRef requires the graph object cache (start a walk with analyze_jira_plan first).');
+            throw new McpError(ErrorCode.InvalidParams, 'dataRef requires the graph object cache (start a walk with manage_jira_plan first).');
         }
         const cached = cache.get(dataRef);
         if (!cached) {
-            throw new McpError(ErrorCode.InvalidParams, `No cached walk for "${dataRef}". Start one with analyze_jira_plan first.`);
+            throw new McpError(ErrorCode.InvalidParams, `No cached walk for "${dataRef}". Start one with manage_jira_plan first.`);
         }
         if (cached.state === 'walking') {
             return {

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 };
+    }
+}