@aaronsb/jira-cloud-mcp 0.8.1 → 0.10.0

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;
@@ -102,7 +105,7 @@ class JiraServer {
             }
         }).catch(() => { });
         // CloudId discovery happens in run() before server connects — must complete
-        // before ListTools so analyze_jira_plan is registered if available.
+        // before ListTools so manage_jira_plan is registered if available.
         this.server.onerror = (error) => console.error('[MCP Error]', error);
         process.on('SIGINT', async () => {
             await this.server.close();
@@ -113,7 +116,7 @@ class JiraServer {
         // Set up required MCP protocol handlers
         this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
             tools: Object.entries(toolSchemas)
-                .filter(([key]) => key !== 'analyze_jira_plan' || this.graphqlClient !== null)
+                .filter(([key]) => key !== 'manage_jira_plan' || this.graphqlClient !== null)
                 .map(([key, schema]) => ({
                 name: key,
                 description: schema.description,
@@ -125,7 +128,7 @@ class JiraServer {
             })),
         }));
         // Set up resource handlers
-        const resourceHandlers = setupResourceHandlers(this.jiraClient);
+        const resourceHandlers = setupResourceHandlers(this.jiraClient, this.graphqlClient);
         this.server.setRequestHandler(ListResourcesRequestSchema, resourceHandlers.listResources);
         this.server.setRequestHandler(ListResourceTemplatesRequestSchema, resourceHandlers.listResourceTemplates);
         this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
@@ -160,12 +163,14 @@ 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,
                     queue_jira_operations: createQueueHandler(toolHandlers, JIRA_HOST),
                     ...(this.graphqlClient ? {
-                        analyze_jira_plan: (_client, req) => handlePlanRequest(this.jiraClient, this.graphqlClient, req, this.cache),
+                        manage_jira_plan: (_client, req) => handlePlanRequest(this.jiraClient, this.graphqlClient, req, this.cache),
                     } : {}),
                 };
                 const handler = handlers[name];
@@ -293,15 +298,15 @@ class JiraServer {
         try {
             const cloudId = await discoverCloudId(JIRA_HOST, JIRA_EMAIL, JIRA_API_TOKEN);
             if (cloudId) {
-                this.graphqlClient = new GraphQLClient(JIRA_EMAIL, JIRA_API_TOKEN, cloudId);
+                this.graphqlClient = new GraphQLClient(JIRA_EMAIL, JIRA_API_TOKEN, cloudId, JIRA_HOST);
                 console.error(`[jira-cloud] GraphQL client ready (cloudId: ${cloudId.slice(0, 8)}...)`);
             }
             else {
-                console.error('[jira-cloud] GraphQL/Plans unavailable — analyze_jira_plan disabled');
+                console.error('[jira-cloud] GraphQL/Plans unavailable — manage_jira_plan disabled');
             }
         }
         catch {
-            console.error('[jira-cloud] GraphQL discovery failed — analyze_jira_plan disabled');
+            console.error('[jira-cloud] GraphQL discovery failed — manage_jira_plan disabled');
         }
         const transport = new StdioServerTransport();
         await this.server.connect(transport);

package/build/schemas/tool-schemas.js

@@ -373,7 +373,7 @@ export const toolSchemas = {
                 },
                 dataRef: {
                     type: 'string',
-                    description: 'Root issue key of a cached hierarchy walk. Analyzes cached plan data without re-fetching from Jira. Start a walk with analyze_jira_plan first. Supports all metrics except flow. Takes precedence over jql/filterId.',
+                    description: 'Root issue key of a cached hierarchy walk. Analyzes cached plan data without re-fetching from Jira. Start a walk with manage_jira_plan first. Supports all metrics except flow. Takes precedence over jql/filterId.',
                 },
                 metrics: {
                     type: 'array',
@@ -408,20 +408,66 @@ export const toolSchemas = {
             required: [],
         },
     },
-    analyze_jira_plan: {
-        name: 'analyze_jira_plan',
-        description: 'Analyze hierarchy rollups for any parent issue. Walks the issue tree via GraphQL, computes rolled-up dates, points, progress, assignees, and detects date conflicts. Results are cached server-side for fast re-analysis. Works on any Jira instance (no Plans/Premium required). For flat-set metrics use analyze_jira_issues (with dataRef to analyze cached plan data); for structure without rollups use manage_jira_issue hierarchy.',
+    manage_jira_plan: {
+        name: 'manage_jira_plan',
+        description: 'Navigate and manage the strategic-to-execution hierarchy. Walks issue trees and Atlassian Goals via GraphQL. Read: analyze rollups (dates, points, progress, conflicts), discover goals (list_goals), get goal detail (get_goal). Write: create/update goals, post status updates, link/unlink Jira issues to goals. Results cached server-side. For flat-set metrics use analyze_jira_issues; for structure without rollups use manage_jira_issue hierarchy.',
         inputSchema: {
             type: 'object',
             properties: {
                 operation: {
                     type: 'string',
-                    enum: ['analyze', 'release'],
-                    description: 'Operation to perform. analyze (default): walk hierarchy and compute rollups. release: free cached walk data for this issueKey.',
+                    enum: ['analyze', 'release', 'list_goals', 'get_goal', 'create_goal', 'update_goal', 'update_goal_status', 'link_work_item', 'unlink_work_item'],
+                    description: 'Operation to perform. analyze: walk hierarchy and compute rollups. release: free cached walk. list_goals: search goals. get_goal: goal detail. create_goal: create a goal. update_goal: edit goal name/description/dates/archive. update_goal_status: post a status update (on_track/off_track/done). link_work_item: link a Jira issue to a goal. unlink_work_item: unlink a Jira issue from a goal.',
                 },
                 issueKey: {
                     type: 'string',
-                    description: 'Issue key at the root of the plan tree (e.g., PROJ-100). Required.',
+                    description: 'Issue key at the root of the plan tree (e.g., PROJ-100). Required for analyze/release unless goalKey is provided. Also used with link_work_item/unlink_work_item to specify the Jira issue.',
+                },
+                goalKey: {
+                    type: 'string',
+                    description: 'Atlassian Goal key (e.g., PRAEC-25). Used for get_goal, analyze, update_goal, update_goal_status, link_work_item, unlink_work_item.',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Goal name. Required for create_goal. Optional for update_goal (renames the goal).',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Goal description text. For create_goal and update_goal.',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['on_track', 'off_track', 'at_risk', 'done', 'pending', 'paused'],
+                    description: 'Goal status for update_goal_status.',
+                },
+                summary: {
+                    type: 'string',
+                    description: 'Status update summary text for update_goal_status. Describes what changed and why.',
+                },
+                parentGoalKey: {
+                    type: 'string',
+                    description: 'Parent goal key for create_goal. Makes the new goal a sub-goal of this parent.',
+                },
+                targetDate: {
+                    type: 'string',
+                    description: 'Target date in ISO format (YYYY-MM-DD) for create_goal and update_goal.',
+                },
+                startDate: {
+                    type: 'string',
+                    description: 'Start date in ISO format (YYYY-MM-DD) for update_goal.',
+                },
+                archived: {
+                    type: 'boolean',
+                    description: 'Set to true to archive a goal, false to unarchive. For update_goal.',
+                },
+                searchString: {
+                    type: 'string',
+                    description: 'TQL search string for list_goals. Examples: \'name LIKE "Health"\', \'status = on_track\'. Empty string returns all goals.',
+                },
+                sort: {
+                    type: 'string',
+                    enum: ['HIERARCHY_ASC', 'HIERARCHY_DESC', 'NAME_ASC', 'NAME_DESC', 'TARGET_DATE_ASC', 'TARGET_DATE_DESC', 'LATEST_UPDATE_DATE_ASC', 'LATEST_UPDATE_DATE_DESC'],
+                    description: 'Sort order for list_goals. Default: HIERARCHY_ASC (groups parents with children).',
                 },
                 rollups: {
                     type: 'array',
@@ -433,7 +479,7 @@ export const toolSchemas = {
                 },
                 focus: {
                     type: 'string',
-                    description: 'Issue key to focus on within the cached plan. Shows the node, its parent, siblings, and children — a windowed view for navigating large plans. Requires a completed walk.',
+                    description: 'Issue key to focus on within the cached plan. Windowed view for navigating large plans.',
                 },
                 mode: {
                     type: 'string',
@@ -441,7 +487,73 @@ export const toolSchemas = {
                     description: 'Output mode. rollup (default): summary + entry points. gaps: conflicts and missing data only.',
                 },
             },
-            required: ['issueKey'],
+            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: {
@@ -457,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' });
@@ -42,7 +42,7 @@ export function issueNextSteps(operation, issueKey) {
             steps.push({ description: 'View the updated issue', tool: 'manage_jira_issue', example: { operation: 'get', issueKey } }, { description: 'Log more time', tool: 'manage_jira_issue', example: { operation: 'worklog', issueKey, timeSpent: '<duration>' } }, { description: 'Adjust the remaining estimate', tool: 'manage_jira_issue', example: { operation: 'update', issueKey, remainingEstimate: '<duration>' } });
             break;
         case 'hierarchy':
-            steps.push({ description: 'View a specific issue from the tree', tool: 'manage_jira_issue', example: { operation: 'get', issueKey } }, { description: 'Analyze plan rollups (requires Jira Plans)', tool: 'analyze_jira_plan', example: { issueKey } }, { description: 'Search for issues in this project', tool: 'manage_jira_filter', example: { operation: 'execute_jql', jql: `project = "${issueKey?.split('-')[0]}"` } });
+            steps.push({ description: 'View a specific issue from the tree', tool: 'manage_jira_issue', example: { operation: 'get', issueKey } }, { description: 'Analyze plan rollups (requires Jira Plans)', tool: 'manage_jira_plan', example: { issueKey } }, { description: 'Search for issues in this project', tool: 'manage_jira_filter', example: { operation: 'execute_jql', jql: `project = "${issueKey?.split('-')[0]}"` } });
             break;
     }
     return steps.length > 0 ? formatSteps(steps) : '';
@@ -132,10 +132,10 @@ export function planNextSteps(issueKey, mode, conflicts, rollup) {
     const steps = [];
     steps.push({ description: 'View the issue details', tool: 'manage_jira_issue', example: { operation: 'get', issueKey } }, { description: 'Explore the hierarchy tree', tool: 'manage_jira_issue', example: { operation: 'hierarchy', issueKey } });
     if (mode !== 'gaps') {
-        steps.push({ description: 'Check for data gaps and conflicts', tool: 'analyze_jira_plan', example: { issueKey, mode: 'gaps' } });
+        steps.push({ description: 'Check for data gaps and conflicts', tool: 'manage_jira_plan', example: { issueKey, mode: 'gaps' } });
     }
     if (mode !== 'timeline') {
-        steps.push({ description: 'View the timeline', tool: 'analyze_jira_plan', example: { issueKey, mode: 'timeline' } });
+        steps.push({ description: 'View the timeline', tool: 'manage_jira_plan', example: { issueKey, mode: 'timeline' } });
     }
     steps.push({ description: 'Run flat metrics on children', tool: 'analyze_jira_issues', example: { jql: `parent = ${issueKey}`, metrics: ['summary'], groupBy: 'assignee' } });
     let result = formatSteps(steps);
@@ -174,6 +174,54 @@ export function conflictFixSteps(conflicts, rollup) {
     }
     return lines.join('\n');
 }
+export function goalNextSteps(operation, goalKey, workItemCount) {
+    const steps = [];
+    switch (operation) {
+        case 'list_goals':
+            steps.push({ description: 'Get detail on a specific goal', tool: 'manage_jira_plan', example: { operation: 'get_goal', goalKey: 'GOAL-KEY' } }, { description: 'Analyze a goal\'s linked issues', tool: 'manage_jira_plan', example: { operation: 'analyze', goalKey: 'GOAL-KEY' } });
+            break;
+        case 'get_goal':
+            if (goalKey && workItemCount && workItemCount > 0) {
+                steps.push({ description: 'Analyze this goal\'s linked issues', tool: 'manage_jira_plan', example: { operation: 'analyze', goalKey } });
+            }
+            steps.push({ description: 'Search for more goals', tool: 'manage_jira_plan', example: { operation: 'list_goals', searchString: '' } });
+            break;
+        case 'analyze':
+            if (goalKey) {
+                steps.push({ description: 'View goal detail', tool: 'manage_jira_plan', example: { operation: 'get_goal', goalKey } }, { description: 'Update goal status', tool: 'manage_jira_plan', example: { operation: 'update_goal_status', goalKey, status: 'on_track', summary: 'Progress update' } });
+            }
+            break;
+        case 'create_goal':
+        case 'update_goal':
+        case 'update_goal_status':
+            if (goalKey) {
+                steps.push({ description: 'View updated goal', tool: 'manage_jira_plan', example: { operation: 'get_goal', goalKey } });
+            }
+            break;
+        case 'link_work_item':
+        case 'unlink_work_item':
+            if (goalKey) {
+                steps.push({ description: 'View goal with updated links', tool: 'manage_jira_plan', example: { operation: 'get_goal', goalKey } }, { description: 'Analyze goal progress', tool: 'manage_jira_plan', example: { operation: 'analyze', goalKey } });
+            }
+            break;
+    }
+    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) {
@@ -195,7 +243,7 @@ export function analysisNextSteps(jql, issueKeys, truncated = false, groupBy, fi
     }
     // Suggest plan analysis when issue keys suggest hierarchical structure
     if (issueKeys.length > 0) {
-        steps.push({ description: 'Analyze plan rollups for a parent issue (requires Jira Plans)', tool: 'analyze_jira_plan', example: { issueKey: issueKeys[0] } });
+        steps.push({ description: 'Analyze plan rollups for a parent issue (requires Jira Plans)', tool: 'manage_jira_plan', example: { issueKey: issueKeys[0] } });
     }
     // Suggest saving as filter if not already using one
     if (!filterSource) {

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.8.1",
+  "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",