@aaronsb/jira-cloud-mcp 0.2.7 → 0.3.1

package/build/schemas/tool-schemas.js

@@ -1,67 +1,45 @@
 export const toolSchemas = {
-    // Filter Management API
     manage_jira_filter: {
         name: 'manage_jira_filter',
-        description: 'Filter management with CRUD operations and issue retrieval',
+        description: 'Search for issues using JQL queries, or manage saved filters',
         inputSchema: {
             type: 'object',
             properties: {
                 operation: {
                     type: 'string',
                     enum: ['get', 'create', 'update', 'delete', 'list', 'execute_filter', 'execute_jql'],
-                    description: 'Operation to perform on the filter',
+                    description: 'Operation to perform',
                 },
-                // Parameters for get, update, delete, execute_filter operations
                 filterId: {
                     type: 'string',
-                    description: 'The ID of the filter. Required for get, update, delete, and execute_filter operations. Can also use snake_case "filter_id".',
+                    description: 'Filter ID. Required for get, update, delete, execute_filter.',
                 },
-                // Parameters for create and update operations
                 name: {
                     type: 'string',
-                    description: 'Name of the filter. Required for create operation, optional for update.',
+                    description: 'Filter name. Required for create.',
                 },
                 jql: {
                     type: 'string',
-                    description: 'JQL query string. Supports a wide range of search patterns:\n\n' +
-                        '# Portfolio/Plans Queries\n' +
-                        '- Find child issues: issue in portfolioChildIssuesOf("PROJ-123")\n' +
-                        '- Combined portfolio search: issue in portfolioChildIssuesOf("PROJ-123") AND status = "In Progress"\n' +
-                        '- Multiple portfolios: issue in portfolioChildIssuesOf("PROJ-123") OR issue in portfolioChildIssuesOf("PROJ-456")\n\n' +
-                        '# Common Search Patterns\n' +
-                        '- Assigned issues: assignee = currentUser()\n' +
-                        '- Unassigned issues: assignee IS EMPTY\n' +
-                        '- Recent changes: status CHANGED AFTER -1w\n' +
-                        '- Multiple statuses: status IN ("In Progress", "Under Review", "Testing")\n' +
-                        '- Priority tasks: priority = High AND status = Open\n' +
-                        '- Component search: component = "User Interface" OR component = "API"\n\n' +
-                        '# Advanced Functions\n' +
-                        '- Sort results: ORDER BY created DESC\n' +
-                        '- Track changes: status WAS "Resolved" AND status = "Open"\n' +
-                        '- Team filters: assignee IN MEMBERSOF("developers")\n\n' +
-                        'JQL supports complex combinations using AND, OR, NOT operators and parentheses for grouping. ' +
-                        'All text values are case-sensitive and must be enclosed in quotes when they contain spaces.',
+                    description: 'JQL query string. Required for create and execute_jql. Read jira://tools/manage_jira_filter/documentation for syntax examples.',
                 },
                 description: {
                     type: 'string',
-                    description: 'Description of the filter. Optional for create/update.',
+                    description: 'Filter description.',
                 },
                 favourite: {
                     type: 'boolean',
-                    description: 'Whether to mark the filter as a favorite. Optional for create/update.',
+                    description: 'Mark as favorite.',
                 },
-                // Parameters for list operation
                 startAt: {
                     type: 'integer',
-                    description: 'Index of the first filter to return (0-based). Used for list and execute_jql operations. Can also use snake_case "start_at".',
+                    description: 'Pagination offset (0-based).',
                     default: 0,
                 },
                 maxResults: {
                     type: 'integer',
-                    description: 'Maximum number of filters or issues to return. Used for list and execute_jql operations. Can also use snake_case "max_results".',
+                    description: 'Max items to return.',
                     default: 50,
                 },
-                // Parameters for sharing
                 sharePermissions: {
                     type: 'array',
                     items: {
@@ -70,381 +48,304 @@ export const toolSchemas = {
                             type: {
                                 type: 'string',
                                 enum: ['group', 'project', 'global'],
-                                description: 'Type of share permission',
-                            },
-                            group: {
-                                type: 'string',
-                                description: 'Group name (required when type is "group")',
-                            },
-                            project: {
-                                type: 'string',
-                                description: 'Project key (required when type is "project")',
                             },
+                            group: { type: 'string' },
+                            project: { type: 'string' },
                         },
                         required: ['type'],
                     },
-                    description: 'Share permissions for the filter. Optional for create/update. Can also use snake_case "share_permissions".',
+                    description: 'Share permissions for the filter.',
                 },
-                // Common expansion options
                 expand: {
                     type: 'array',
                     items: {
                         type: 'string',
                         enum: ['jql', 'description', 'permissions', 'issue_count', 'issue_details', 'transitions', 'comments_preview'],
                     },
-                    description: 'Optional fields to include in the response',
+                    description: 'Additional fields to include in the response.',
                 },
             },
             required: ['operation'],
         },
     },
-    // Sprint Management API
     manage_jira_sprint: {
         name: 'manage_jira_sprint',
-        description: 'Sprint management with CRUD operations and issue management',
+        description: 'Manage sprints: create, start, close, and assign issues to sprints',
         inputSchema: {
             type: 'object',
             properties: {
                 operation: {
                     type: 'string',
                     enum: ['get', 'create', 'update', 'delete', 'list', 'manage_issues'],
-                    description: 'Operation to perform on the sprint',
+                    description: 'Operation to perform',
                 },
-                // Parameters for get operation
                 sprintId: {
                     type: 'integer',
-                    description: 'The ID of the sprint. Required for get, update, delete, and manage_issues operations. Can also use snake_case "sprint_id".',
+                    description: 'Sprint ID. Required for get, update, delete, manage_issues.',
                 },
-                // Parameters for create operation
                 boardId: {
                     type: 'integer',
-                    description: 'The ID of the board. Required for create and list operations. Can also use snake_case "board_id".',
+                    description: 'Board ID. Required for create and list.',
                 },
                 name: {
                     type: 'string',
-                    description: 'Name of the sprint. Required for create operation, optional for update.',
+                    description: 'Sprint name. Required for create.',
                 },
-                // Common parameters for create and update
                 startDate: {
                     type: 'string',
-                    description: 'Start date for the sprint in ISO format (e.g., "2025-03-20T00:00:00.000Z"). Can also use snake_case "start_date".',
+                    description: 'Start date in ISO format (e.g., "2025-03-20T00:00:00.000Z").',
                 },
                 endDate: {
                     type: 'string',
-                    description: 'End date for the sprint in ISO format (e.g., "2025-04-03T00:00:00.000Z"). Can also use snake_case "end_date".',
+                    description: 'End date in ISO format.',
                 },
                 goal: {
                     type: 'string',
-                    description: 'Goal or objective for the sprint',
+                    description: 'Sprint goal.',
                 },
                 state: {
                     type: 'string',
                     enum: ['future', 'active', 'closed'],
-                    description: 'Sprint state. Used for filtering in list operation or changing state in update operation.',
+                    description: 'Sprint state. Filter for list, or set via update.',
                 },
-                // Parameters for list operation
                 startAt: {
                     type: 'integer',
-                    description: 'Index of the first sprint to return (0-based). Used for list operation. Can also use snake_case "start_at".',
+                    description: 'Pagination offset (0-based).',
                     default: 0,
                 },
                 maxResults: {
                     type: 'integer',
-                    description: 'Maximum number of sprints to return. Used for list operation. Can also use snake_case "max_results".',
+                    description: 'Max items to return.',
                     default: 50,
                 },
-                // Parameters for manage_issues operation
                 add: {
                     type: 'array',
-                    items: {
-                        type: 'string',
-                    },
-                    description: 'Array of issue keys to add to the sprint. Used for manage_issues operation.',
+                    items: { type: 'string' },
+                    description: 'Issue keys to add to sprint (manage_issues).',
                 },
                 remove: {
                     type: 'array',
-                    items: {
-                        type: 'string',
-                    },
-                    description: 'Array of issue keys to remove from the sprint. Used for manage_issues operation.',
+                    items: { type: 'string' },
+                    description: 'Issue keys to remove from sprint (manage_issues).',
                 },
-                // Common expansion options
                 expand: {
                     type: 'array',
                     items: {
                         type: 'string',
                         enum: ['issues', 'report', 'board'],
                     },
-                    description: 'Optional fields to include in the response',
+                    description: 'Additional fields to include in the response.',
                 },
             },
             required: ['operation'],
         },
     },
-    // Issue Management API
     manage_jira_issue: {
         name: 'manage_jira_issue',
-        description: 'Issue management with CRUD operations, transitions, comments, and linking',
+        description: 'Get, create, update, delete, move, transition, comment on, or link Jira issues',
         inputSchema: {
             type: 'object',
             properties: {
                 operation: {
                     type: 'string',
-                    enum: ['create', 'get', 'update', 'delete', 'transition', 'comment', 'link'],
-                    description: 'Operation to perform on the issue',
+                    enum: ['create', 'get', 'update', 'delete', 'move', 'transition', 'comment', 'link'],
+                    description: 'Operation to perform',
                 },
-                // Parameters for get, update, delete, transition, comment, and link operations
                 issueKey: {
                     type: 'string',
-                    description: 'The Jira issue key (e.g., WORK-123). Required for all operations except create. Can also use snake_case "issue_key".',
+                    description: 'Issue key (e.g., PROJ-123). Required for all operations except create.',
                 },
-                // Parameters for create operation
                 projectKey: {
                     type: 'string',
-                    description: 'Project key (e.g., PROJ). Required for create operation. Can also use snake_case "project_key".',
+                    description: 'Project key (e.g., PROJ). Required for create.',
                 },
-                // Common parameters for create and update
                 summary: {
                     type: 'string',
-                    description: 'Issue summary/title. Required for create, optional for update.',
+                    description: 'Issue title. Required for create.',
                 },
                 description: {
                     type: 'string',
-                    description: 'Detailed description of the issue. Optional for create/update.',
+                    description: 'Issue description.',
                 },
                 issueType: {
                     type: 'string',
-                    description: 'Type of issue (e.g., Story, Bug, Task). Required for create. Can also use snake_case "issue_type".',
+                    description: 'Issue type (e.g., Story, Bug, Task). Required for create.',
                 },
                 priority: {
                     type: 'string',
-                    description: 'Issue priority (e.g., High, Medium, Low). Optional for create/update.',
+                    description: 'Priority (e.g., High, Medium, Low).',
                 },
                 assignee: {
                     type: 'string',
-                    description: 'Username of the assignee. Optional for create/update.',
+                    description: 'Atlassian accountId of the assignee.',
                 },
                 labels: {
                     type: 'array',
-                    items: {
-                        type: 'string'
-                    },
-                    description: 'Array of labels to apply to the issue. Optional for create/update.',
+                    items: { type: 'string' },
+                    description: 'Labels to apply.',
                 },
                 customFields: {
                     type: 'object',
-                    description: 'Custom field values as key-value pairs. Optional for create/update. Can also use snake_case "custom_fields".',
+                    description: 'Custom field values as key-value pairs.',
                 },
-                // Parameters for update operation
                 parent: {
                     type: ['string', 'null'],
-                    description: 'The key of the parent issue (e.g., PROJ-123) or null to remove parent. Optional for update.',
+                    description: 'Parent issue key (e.g., PROJ-100) or null to remove.',
                 },
-                // Parameters for transition operation
                 transitionId: {
                     type: 'string',
-                    description: 'The ID of the transition to perform. Required for transition operation. Can also use snake_case "transition_id".',
+                    description: 'Transition ID. Required for transition. Use expand: ["transitions"] on get to discover IDs.',
                 },
-                // Parameters for comment and transition operations
                 comment: {
                     type: 'string',
-                    description: 'Comment text. Required for comment operation, optional for transition.',
+                    description: 'Comment text. Required for comment, optional for transition.',
                 },
-                // Parameters for link operation
                 linkType: {
                     type: 'string',
-                    description: 'Type of link between issues (e.g., "relates to", "blocks"). Required for link operation. Can also use snake_case "link_type".',
+                    description: 'Link type (e.g., "blocks", "relates to"). Required for link. Read jira://issue-link-types for valid types.',
                 },
                 linkedIssueKey: {
                     type: 'string',
-                    description: 'The key of the issue to link to. Required for link operation. Can also use snake_case "linked_issue_key".',
+                    description: 'Issue key to link to. Required for link.',
+                },
+                targetProjectKey: {
+                    type: 'string',
+                    description: 'Target project key for move (e.g., NEWPROJ). Required for move.',
+                },
+                targetIssueType: {
+                    type: 'string',
+                    description: 'Target issue type for move (e.g., Story, Bug). Required for move.',
                 },
-                // Common expansion options
                 expand: {
                     type: 'array',
                     items: {
                         type: 'string',
                         enum: ['comments', 'transitions', 'attachments', 'related_issues', 'history'],
                     },
-                    description: 'Optional fields to include in the response',
+                    description: 'Additional fields to include in the response.',
                 },
             },
             required: ['operation'],
         },
     },
-    // Project Management API
     manage_jira_project: {
         name: 'manage_jira_project',
-        description: 'Project management with CRUD operations and related data',
+        description: 'List projects or get project details including status counts',
         inputSchema: {
             type: 'object',
             properties: {
                 operation: {
                     type: 'string',
-                    enum: ['get', 'create', 'update', 'delete', 'list'],
-                    description: 'Operation to perform on the project',
+                    enum: ['get', 'list'],
+                    description: 'Operation to perform',
                 },
-                // Parameters for get, update, delete operations
                 projectKey: {
                     type: 'string',
-                    description: 'The Jira project key (e.g., PROJ). Required for get, update, and delete operations. Can also use snake_case "project_key".',
-                },
-                // Parameters for create operation
-                name: {
-                    type: 'string',
-                    description: 'Name of the project. Required for create operation, optional for update.',
-                },
-                key: {
-                    type: 'string',
-                    description: 'Project key. Required for create operation.',
-                },
-                // Common parameters for create and update
-                description: {
-                    type: 'string',
-                    description: 'Description of the project. Optional for create/update.',
-                },
-                lead: {
-                    type: 'string',
-                    description: 'Username of the project lead. Optional for create/update.',
+                    description: 'Project key (e.g., PROJ). Required for get.',
                 },
-                // Parameters for list operation
                 startAt: {
                     type: 'integer',
-                    description: 'Index of the first project to return (0-based). Used for list operation. Can also use snake_case "start_at".',
+                    description: 'Pagination offset (0-based).',
                     default: 0,
                 },
                 maxResults: {
                     type: 'integer',
-                    description: 'Maximum number of projects to return. Used for list operation. Can also use snake_case "max_results".',
+                    description: 'Max items to return.',
                     default: 50,
                 },
-                // Common expansion options
                 expand: {
                     type: 'array',
                     items: {
                         type: 'string',
                         enum: ['boards', 'components', 'versions', 'recent_issues'],
                     },
-                    description: 'Optional fields to include in the response',
+                    description: 'Additional fields to include in the response.',
                 },
                 include_status_counts: {
                     type: 'boolean',
-                    description: 'Whether to include issue counts by status',
+                    description: 'Include issue counts by status.',
                     default: true,
                 },
             },
             required: ['operation'],
         },
     },
-    // Board Management API
     manage_jira_board: {
         name: 'manage_jira_board',
-        description: 'Board management with CRUD operations and related data',
+        description: 'List boards or get board details and configuration',
         inputSchema: {
             type: 'object',
             properties: {
                 operation: {
                     type: 'string',
-                    enum: ['get', 'list', 'create', 'update', 'delete', 'get_configuration'],
-                    description: 'Operation to perform on the board',
+                    enum: ['get', 'list'],
+                    description: 'Operation to perform',
                 },
-                // Parameters for get, update, delete, get_configuration operations
                 boardId: {
                     type: 'integer',
-                    description: 'The ID of the board. Required for get, update, delete, and get_configuration operations. Can also use snake_case "board_id".',
+                    description: 'Board ID. Required for get.',
                 },
-                // Parameters for create operation
-                name: {
-                    type: 'string',
-                    description: 'Name of the board. Required for create operation, optional for update.',
-                },
-                type: {
-                    type: 'string',
-                    enum: ['scrum', 'kanban'],
-                    description: 'Type of board. Required for create operation.',
-                },
-                projectKey: {
-                    type: 'string',
-                    description: 'Project key for the board. Required for create operation. Can also use snake_case "project_key".',
-                },
-                // Parameters for list operation
                 startAt: {
                     type: 'integer',
-                    description: 'Index of the first board to return (0-based). Used for list operation. Can also use snake_case "start_at".',
+                    description: 'Pagination offset (0-based).',
                     default: 0,
                 },
                 maxResults: {
                     type: 'integer',
-                    description: 'Maximum number of boards to return. Used for list operation. Can also use snake_case "max_results".',
+                    description: 'Max items to return.',
                     default: 50,
                 },
-                // Common expansion options
                 expand: {
                     type: 'array',
                     items: {
                         type: 'string',
                         enum: ['sprints', 'issues', 'configuration'],
                     },
-                    description: 'Optional fields to include in the response',
+                    description: 'Additional fields to include in the response.',
                 },
                 include_sprints: {
                     type: 'boolean',
-                    description: 'Whether to include active sprints for each board (shorthand for expand: ["sprints"])',
+                    description: 'Include active sprints (shorthand for expand: ["sprints"]).',
                     default: false,
                 },
             },
             required: ['operation'],
         },
     },
-    // Enhanced Search API - will be deprecated after consolidation
-    search_jira_issues: {
-        name: 'search_jira_issues',
-        description: 'Search for issues using JQL with enhanced results and optional expansions',
+    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).',
         inputSchema: {
             type: 'object',
             properties: {
-                jql: {
-                    type: 'string',
-                    description: 'JQL query string. Supports a wide range of search patterns:\n\n' +
-                        '# Portfolio/Plans Queries\n' +
-                        '- Find child issues: issue in portfolioChildIssuesOf("PROJ-123")\n' +
-                        '- Combined portfolio search: issue in portfolioChildIssuesOf("PROJ-123") AND status = "In Progress"\n' +
-                        '- Multiple portfolios: issue in portfolioChildIssuesOf("PROJ-123") OR issue in portfolioChildIssuesOf("PROJ-456")\n\n' +
-                        '# Common Search Patterns\n' +
-                        '- Assigned issues: assignee = currentUser()\n' +
-                        '- Unassigned issues: assignee IS EMPTY\n' +
-                        '- Recent changes: status CHANGED AFTER -1w\n' +
-                        '- Multiple statuses: status IN ("In Progress", "Under Review", "Testing")\n' +
-                        '- Priority tasks: priority = High AND status = Open\n' +
-                        '- Component search: component = "User Interface" OR component = "API"\n\n' +
-                        '# Advanced Functions\n' +
-                        '- Sort results: ORDER BY created DESC\n' +
-                        '- Track changes: status WAS "Resolved" AND status = "Open"\n' +
-                        '- Team filters: assignee IN MEMBERSOF("developers")\n\n' +
-                        'JQL supports complex combinations using AND, OR, NOT operators and parentheses for grouping. ' +
-                        'All text values are case-sensitive and must be enclosed in quotes when they contain spaces.',
-                },
-                startAt: {
-                    type: 'number',
-                    description: 'Index of the first issue to return (0-based). Can also use snake_case "start_at".',
-                    default: 0,
-                },
-                maxResults: {
-                    type: 'number',
-                    description: 'Maximum number of issues to return (default: 25, max: 100). Can also use snake_case "max_results".',
-                    default: 25,
-                    maximum: 100,
-                },
-                expand: {
+                operations: {
                     type: 'array',
                     items: {
-                        type: 'string',
-                        enum: ['issue_details', 'transitions', 'comments_preview'],
+                        type: 'object',
+                        properties: {
+                            tool: {
+                                type: 'string',
+                                enum: ['manage_jira_issue', 'manage_jira_filter', 'manage_jira_sprint', 'manage_jira_project', 'manage_jira_board'],
+                                description: 'Which tool to call.',
+                            },
+                            args: {
+                                type: 'object',
+                                description: 'Arguments for the tool call. Use $N.field to reference results from earlier operations (e.g., $0.key for the issue key from operation 0).',
+                            },
+                            onError: {
+                                type: 'string',
+                                enum: ['bail', 'continue'],
+                                description: 'Error strategy. bail (default): stop queue. continue: log error, proceed to next.',
+                                default: 'bail',
+                            },
+                        },
+                        required: ['tool', 'args'],
                     },
-                    description: 'Optional fields to include in the response',
+                    description: 'Ordered list of operations to execute (max 10).',
+                    maxItems: 10,
                 },
             },
-            required: ['jql'],
+            required: ['operations'],
         },
     },
 };

package/build/utils/bulk-operation-guard.js

@@ -0,0 +1,74 @@
+/**
+ * Sliding-window tracker for bulk-destructive operations (ADR-202 §1.4).
+ *
+ * Detects when an LLM agent is calling destructive operations (delete, move)
+ * in rapid succession and deflects to Jira's bulk-operations UI.
+ */
+const WINDOW_MS = 60_000; // 60-second sliding window
+const DEFAULT_LIMIT = 3;
+/** Session-level operation tracker (singleton) */
+class BulkOperationGuard {
+    ops = [];
+    limit;
+    constructor() {
+        const envLimit = process.env.JIRA_BULK_DESTRUCTIVE_LIMIT;
+        this.limit = envLimit ? parseInt(envLimit, 10) : DEFAULT_LIMIT;
+        if (isNaN(this.limit) || this.limit < 1) {
+            this.limit = DEFAULT_LIMIT;
+        }
+    }
+    /** Prune entries outside the sliding window */
+    prune() {
+        const cutoff = Date.now() - WINDOW_MS;
+        this.ops = this.ops.filter(op => op.timestamp >= cutoff);
+    }
+    /**
+     * Check whether a destructive operation should be allowed.
+     * Returns `null` if allowed, or a deflection message if refused.
+     */
+    check(operation, issueKey, jiraHost) {
+        this.prune();
+        const recentCount = this.ops.length;
+        if (recentCount < this.limit) {
+            return null; // allowed
+        }
+        // Build deflection
+        const recentKeys = this.ops.map(op => op.issueKey);
+        recentKeys.push(issueKey);
+        const jql = `key in (${recentKeys.join(', ')})`;
+        const encodedJql = encodeURIComponent(jql);
+        const lines = [
+            `Bulk ${operation} is not supported through this tool — ${operation === 'delete' ? 'deleting' : 'moving'} ${recentKeys.length} issues in quick succession is best done with manual review.`,
+            '',
+            `**Your JQL query:** \`${jql}\``,
+        ];
+        if (jiraHost) {
+            const host = jiraHost.replace(/^https?:\/\//, '');
+            lines.push(`**Review in Jira:** https://${host}/issues/?jql=${encodedJql}`);
+        }
+        lines.push('');
+        lines.push(`From Jira's issue list, select the issues and use the bulk operations menu.`);
+        lines.push('');
+        lines.push(`To ${operation} a single issue, wait a moment and try again with one issue at a time.`);
+        return lines.join('\n');
+    }
+    /** Record a successful destructive operation */
+    record(operation, issueKey) {
+        this.ops.push({ operation, issueKey, timestamp: Date.now() });
+    }
+    /** How many more destructive ops are allowed in the current window */
+    remainingCapacity() {
+        this.prune();
+        return Math.max(0, this.limit - this.ops.length);
+    }
+    /** Reset for testing */
+    reset() {
+        this.ops = [];
+    }
+    /** Visible for testing */
+    getLimit() {
+        return this.limit;
+    }
+}
+/** Singleton instance — lives for the MCP server process lifetime */
+export const bulkOperationGuard = new BulkOperationGuard();