@aaronsb/jira-cloud-mcp 0.5.6 → 0.5.9

package/build/client/jira-client.js

@@ -134,7 +134,7 @@ export class JiraClient {
             people: people.length > 0 ? people : undefined,
         };
     }
-    async getIssue(issueKey, includeComments = false, includeAttachments = false, customFieldMeta) {
+    async getIssue(issueKey, includeComments = false, includeAttachments = false, customFieldMeta, includeHistory = false) {
         const fields = [...this.issueFields];
         if (includeAttachments) {
             fields.push('attachment');
@@ -147,13 +147,32 @@ export class JiraClient {
                 }
             }
         }
+        const expands = [];
+        if (includeComments)
+            expands.push('comments');
+        if (includeHistory)
+            expands.push('changelog');
         const params = {
             issueIdOrKey: issueKey,
             fields,
-            expand: includeComments ? 'comments' : undefined
+            expand: expands.length > 0 ? expands.join(',') : undefined,
         };
         const issue = await this.client.issues.getIssue(params);
         const issueDetails = this.mapIssueFields(issue);
+        // Extract status transitions from changelog
+        if (includeHistory && issue.changelog?.histories) {
+            const histories = issue.changelog.histories;
+            issueDetails.statusHistory = histories
+                .flatMap(h => h.items
+                .filter(item => item.field === 'status')
+                .map(item => ({
+                date: h.created,
+                from: item.fromString || '',
+                to: item.toString || '',
+                author: h.author?.displayName || 'Unknown',
+            })))
+                .sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
+        }
         // Extract custom field values using catalog metadata
         if (customFieldMeta) {
             const rawFields = issue.fields;
@@ -984,6 +1003,52 @@ export class JiraClient {
         const response = await this.client.issues.createIssue({ fields });
         return { key: response.key };
     }
+    async createFilter(name, jql, description, favourite) {
+        const result = await this.client.filters.createFilter({
+            name,
+            jql,
+            description: description || '',
+            favourite: favourite ?? false,
+        });
+        if (!result.id || !result.name) {
+            throw new Error('Invalid filter response from Jira');
+        }
+        return {
+            id: result.id,
+            name: result.name,
+            owner: result.owner?.displayName || 'Unknown',
+            favourite: result.favourite || false,
+            viewUrl: result.viewUrl || '',
+            description: result.description || '',
+            jql: result.jql || '',
+        };
+    }
+    async updateFilter(filterId, updates) {
+        // Fetch existing filter to merge with updates (API requires name)
+        const existing = await this.client.filters.getFilter({ id: parseInt(filterId, 10) });
+        const result = await this.client.filters.updateFilter({
+            id: parseInt(filterId, 10),
+            name: updates.name || existing.name || '',
+            jql: updates.jql ?? existing.jql,
+            description: updates.description ?? existing.description,
+            favourite: updates.favourite ?? existing.favourite,
+        });
+        if (!result.id || !result.name) {
+            throw new Error('Invalid filter response from Jira');
+        }
+        return {
+            id: result.id,
+            name: result.name,
+            owner: result.owner?.displayName || 'Unknown',
+            favourite: result.favourite || false,
+            viewUrl: result.viewUrl || '',
+            description: result.description || '',
+            jql: result.jql || '',
+        };
+    }
+    async deleteFilter(filterId) {
+        await this.client.filters.deleteFilter(filterId);
+    }
     async listMyFilters(expand = false) {
         const filters = await this.client.filters.getMyFilters();
         return Promise.all(filters.map(async (filter) => {

package/build/handlers/analysis-handler.js

@@ -422,11 +422,9 @@ async function handleSummary(jiraClient, jql, groupBy, compute, groupLimit = DEF
     const groupBudget = maxGroupsForBudget(neededImplicits.length);
     // Effective group cap: user's preference vs API query budget (whichever is smaller)
     const effectiveGroupCap = Math.min(groupLimit, groupBudget);
-    if (groupBy === 'project') {
+    if (groupBy === 'project' && extractProjectKeys(jql).length > 0) {
+        // Fast path: project keys are explicit in JQL — no sampling needed
         let keys = extractProjectKeys(jql);
-        if (keys.length === 0) {
-            throw new McpError(ErrorCode.InvalidParams, 'groupBy "project" requires project keys in JQL (e.g., project in (AA, GC))');
-        }
         const capped = keys.length > effectiveGroupCap;
         if (capped)
             keys = keys.slice(0, effectiveGroupCap);
@@ -479,6 +477,11 @@ async function handleSummary(jiraClient, jql, groupBy, compute, groupLimit = DEF
         lines.push('');
         lines.push(renderSummaryTable([row], compute));
     }
+    // Workload interpretation hint — steer LLMs to decompose before reporting raw numbers
+    if (groupBy === 'assignee') {
+        lines.push('');
+        lines.push('*Interpretation tip: High open counts per person may include backlog, review, and future-planned work — not just active tasks. Before reporting workload, break down by status: `metrics: ["summary"], groupBy: "issuetype"` scoped to one assignee to distinguish active work from queued/backlog items.*');
+    }
     return lines.join('\n');
 }
 /** Detect which implicit measures are referenced by compute expressions */
@@ -628,7 +631,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
     // If only summary requested, skip issue fetching entirely
     if (hasSummary && fetchMetrics.length === 0) {
         const summaryText = await handleSummary(jiraClient, jql, groupBy, compute, groupLimit);
-        const nextSteps = analysisNextSteps(jql, []);
+        const nextSteps = analysisNextSteps(jql, [], false, groupBy);
         return {
             content: [{
                     type: 'text',
@@ -701,7 +704,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
         }
     }
     // Next steps
-    const nextSteps = analysisNextSteps(jql, allIssues.slice(0, 3).map(i => i.key), truncated);
+    const nextSteps = analysisNextSteps(jql, allIssues.slice(0, 3).map(i => i.key), truncated, groupBy);
     lines.push(nextSteps);
     return {
         content: [{

package/build/handlers/filter-handlers.js

@@ -207,14 +207,62 @@ async function handleListFilters(jiraClient, args) {
         ],
     };
 }
-async function handleCreateFilter(_jiraClient, _args) {
-    throw new McpError(ErrorCode.InternalError, 'Create filter operation is not yet implemented');
+async function handleCreateFilter(jiraClient, args) {
+    if (!args.name) {
+        throw new McpError(ErrorCode.InvalidParams, 'name is required for create operation');
+    }
+    if (!args.jql) {
+        throw new McpError(ErrorCode.InvalidParams, 'jql is required for create operation');
+    }
+    const filter = await jiraClient.createFilter(args.name, args.jql, args.description, args.favourite);
+    const lines = [
+        `# Filter Created: ${filter.name}`,
+        '',
+        `**ID:** ${filter.id}`,
+        `**JQL:** \`${filter.jql}\``,
+        `**Owner:** ${filter.owner}`,
+        filter.description ? `**Description:** ${filter.description}` : '',
+        `**Favourite:** ${filter.favourite ? 'Yes' : 'No'}`,
+        '',
+        `[View in Jira](${filter.viewUrl})`,
+    ].filter(Boolean);
+    return {
+        content: [{ type: 'text', text: lines.join('\n') + filterNextSteps('create', filter.id) }],
+    };
 }
-async function handleUpdateFilter(_jiraClient, _args) {
-    throw new McpError(ErrorCode.InternalError, 'Update filter operation is not yet implemented');
+async function handleUpdateFilter(jiraClient, args) {
+    if (!args.filterId) {
+        throw new McpError(ErrorCode.InvalidParams, 'filterId is required for update operation');
+    }
+    const updates = {};
+    if (args.name)
+        updates.name = args.name;
+    if (args.jql)
+        updates.jql = args.jql;
+    if (args.description !== undefined)
+        updates.description = args.description;
+    if (args.favourite !== undefined)
+        updates.favourite = args.favourite;
+    const filter = await jiraClient.updateFilter(args.filterId, updates);
+    const lines = [
+        `# Filter Updated: ${filter.name}`,
+        '',
+        `**ID:** ${filter.id}`,
+        `**JQL:** \`${filter.jql}\``,
+        `**Owner:** ${filter.owner}`,
+    ];
+    return {
+        content: [{ type: 'text', text: lines.join('\n') + filterNextSteps('get', filter.id) }],
+    };
 }
-async function handleDeleteFilter(_jiraClient, _args) {
-    throw new McpError(ErrorCode.InternalError, 'Delete filter operation is not yet implemented');
+async function handleDeleteFilter(jiraClient, args) {
+    if (!args.filterId) {
+        throw new McpError(ErrorCode.InvalidParams, 'filterId is required for delete operation');
+    }
+    await jiraClient.deleteFilter(args.filterId);
+    return {
+        content: [{ type: 'text', text: `Filter ${args.filterId} deleted.` }],
+    };
 }
 async function handleExecuteFilter(jiraClient, _args) {
     const filterId = _args.filterId;

package/build/handlers/issue-handlers.js

@@ -187,7 +187,8 @@ async function handleGetIssue(jiraClient, args) {
     // Get issue with requested expansions and catalog custom fields
     const includeComments = expansionOptions.comments || false;
     const includeAttachments = expansionOptions.attachments || false;
-    const issue = await jiraClient.getIssue(args.issueKey, includeComments, includeAttachments, getCatalogFieldMeta());
+    const includeHistory = expansionOptions.history || false;
+    const issue = await jiraClient.getIssue(args.issueKey, includeComments, includeAttachments, getCatalogFieldMeta(), includeHistory);
     // Get transitions if requested
     let transitions = undefined;
     if (expansionOptions.transitions) {

package/build/index.js

@@ -95,6 +95,9 @@ class JiraServer {
             const { name, arguments: args } = request.params;
             return getPrompt(name, args);
         });
+        // Track consecutive single-issue calls to suggest queue tool
+        const QUEUE_HINT_THRESHOLD = 3;
+        let consecutiveIssueCalls = 0;
         // Set up tool handlers
         this.server.setRequestHandler(CallToolRequestSchema, async (request, _extra) => {
             console.error('Received request:', JSON.stringify(request, null, 2));
@@ -121,6 +124,17 @@ class JiraServer {
                 if (!response) {
                     throw new McpError(ErrorCode.InternalError, `No response from handler for tool: ${name}`);
                 }
+                // Track consecutive manage_jira_issue calls and suggest queue tool
+                if (name === 'manage_jira_issue') {
+                    consecutiveIssueCalls++;
+                    if (consecutiveIssueCalls >= QUEUE_HINT_THRESHOLD && response.content?.[0]?.text) {
+                        response.content[0].text += `\n\n---\n**💡 Efficiency tip:** You've made ${consecutiveIssueCalls} consecutive \`manage_jira_issue\` calls. Consider using \`queue_jira_operations\` to batch multiple issue operations into a single call — it's faster and uses less context.`;
+                        consecutiveIssueCalls = 0;
+                    }
+                }
+                else {
+                    consecutiveIssueCalls = 0;
+                }
                 return response;
             }
             catch (error) {

package/build/mcp/markdown-renderer.js

@@ -165,6 +165,20 @@ export function renderIssue(issue, transitions) {
             lines.push(`${cf.name} (${cf.type}): ${displayValue}`);
         }
     }
+    // Status history (if requested via expand: ["history"])
+    if (issue.statusHistory && issue.statusHistory.length > 0) {
+        lines.push('');
+        lines.push('Status History:');
+        for (const h of issue.statusHistory) {
+            lines.push(`${formatDate(h.date)}: ${h.from} → ${h.to} (by ${h.author})`);
+        }
+        // Show time in current status
+        const last = issue.statusHistory[issue.statusHistory.length - 1];
+        const daysSince = Math.floor((Date.now() - new Date(last.date).getTime()) / (1000 * 60 * 60 * 24));
+        if (daysSince > 0) {
+            lines.push(`*In "${last.to}" for ${daysSince} days*`);
+        }
+    }
     // Available transitions
     if (transitions && transitions.length > 0) {
         lines.push('');

package/build/utils/next-steps.js

@@ -125,11 +125,21 @@ export function boardNextSteps(operation, boardId) {
     }
     return steps.length > 0 ? formatSteps(steps) : '';
 }
-export function analysisNextSteps(jql, issueKeys, truncated = false) {
+export function analysisNextSteps(jql, issueKeys, truncated = false, groupBy) {
     const steps = [];
     if (issueKeys.length > 0) {
         steps.push({ description: 'Get details on a specific issue', tool: 'manage_jira_issue', example: { operation: 'get', issueKey: issueKeys[0] } });
     }
+    // Contextual cross-dimension suggestions based on groupBy
+    if (groupBy === 'assignee') {
+        steps.push({ description: 'Break down a person\'s workload by status (active vs backlog vs review)', tool: 'analyze_jira_issues', example: { jql: `${jql} AND assignee = "<name>"`, metrics: ['summary'], groupBy: 'issuetype' } }, { description: 'Compare workload health with computed metrics', tool: 'analyze_jira_issues', example: { jql, metrics: ['summary'], groupBy: 'assignee', compute: ['overdue_pct = overdue / open * 100', 'stale_pct = stale / open * 100'] } });
+    }
+    else if (groupBy === 'issuetype' || groupBy === 'priority') {
+        steps.push({ description: 'See who owns these issues', tool: 'analyze_jira_issues', example: { jql, metrics: ['summary'], groupBy: 'assignee' } });
+    }
+    else if (groupBy === 'project') {
+        steps.push({ description: 'Drill into a project by assignee', tool: 'analyze_jira_issues', example: { jql: `${jql} AND project = <KEY>`, metrics: ['summary'], groupBy: 'assignee' } });
+    }
     steps.push({ description: 'Discover dimensions for cube analysis', tool: 'analyze_jira_issues', example: { jql, metrics: ['cube_setup'] } }, { description: 'Add computed columns', tool: 'analyze_jira_issues', example: { jql, metrics: ['summary'], groupBy: 'project', compute: ['bug_pct = bugs / total * 100'] } }, { description: 'Narrow the analysis with refined JQL', tool: 'analyze_jira_issues', example: { jql: `${jql} AND priority = High` } }, { description: 'View the full issue list', tool: 'manage_jira_filter', example: { operation: 'execute_jql', jql } });
     if (truncated) {
         steps.push({ description: 'Distribution counts above are approximate (issue cap hit). For exact breakdowns use summary + groupBy', tool: 'analyze_jira_issues', example: { jql, metrics: ['summary'], groupBy: 'assignee' } }, { description: 'Or narrow JQL for precise detail metrics', tool: 'analyze_jira_issues', example: { jql: `${jql} AND assignee = currentUser()`, metrics: ['cycle'] } });

package/package.json

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