@aaronsb/jira-cloud-mcp 0.5.8 → 0.5.10

package/build/client/jira-client.js

@@ -410,6 +410,11 @@ export class JiraClient {
             url: attachment.content || '',
         }));
     }
+    async getFilter(filterId) {
+        return await this.client.filters.getFilter({
+            id: parseInt(filterId, 10),
+        });
+    }
     async getFilterIssues(filterId) {
         const filter = await this.client.filters.getFilter({
             id: parseInt(filterId, 10)
@@ -1003,6 +1008,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

@@ -592,9 +592,29 @@ async function handleCubeSetup(jiraClient, jql) {
 // ── Main Handler ───────────────────────────────────────────────────────
 export async function handleAnalysisRequest(jiraClient, request) {
     const args = normalizeArgs(request.params?.arguments || {});
-    const jql = args.jql;
-    if (!jql || typeof jql !== 'string' || jql.trim() === '') {
-        throw new McpError(ErrorCode.InvalidParams, 'jql parameter is required.');
+    // Resolve JQL: filterId takes precedence over inline jql
+    let jql;
+    let filterSource;
+    const filterId = args.filterId;
+    if (filterId && typeof filterId === 'string' && filterId.trim() !== '') {
+        let filter;
+        try {
+            filter = await jiraClient.getFilter(filterId);
+        }
+        catch {
+            throw new McpError(ErrorCode.InvalidParams, `Filter ${filterId} not found or not accessible. Use manage_jira_filter with operation "list" to see available filters.`);
+        }
+        if (!filter.jql) {
+            throw new McpError(ErrorCode.InvalidParams, `Filter ${filterId} has no JQL query.`);
+        }
+        jql = filter.jql;
+        filterSource = `${filter.name || filterId} (filter ${filterId})`;
+    }
+    else {
+        jql = args.jql;
+        if (!jql || typeof jql !== 'string' || jql.trim() === '') {
+            throw new McpError(ErrorCode.InvalidParams, 'Either jql or filterId parameter is required.');
+        }
     }
     // Parse requested metrics
     const requested = (args.metrics && Array.isArray(args.metrics))
@@ -620,22 +640,24 @@ export async function handleAnalysisRequest(jiraClient, request) {
     // Cube setup — discover dimensions from sample, no issue fetching
     if (hasCubeSetup) {
         const cubeText = await handleCubeSetup(jiraClient, jql);
-        const nextSteps = analysisNextSteps(jql, []);
+        const nextSteps = analysisNextSteps(jql, [], false, undefined, filterSource);
+        const banner = filterSource ? `*Using saved filter: ${filterSource}*\n\n` : '';
         return {
             content: [{
                     type: 'text',
-                    text: cubeText + '\n' + nextSteps,
+                    text: banner + cubeText + '\n' + nextSteps,
                 }],
         };
     }
     // 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, [], false, groupBy);
+        const nextSteps = analysisNextSteps(jql, [], false, groupBy, filterSource);
+        const banner = filterSource ? `*Using saved filter: ${filterSource}*\n\n` : '';
         return {
             content: [{
                     type: 'text',
-                    text: summaryText + '\n' + nextSteps,
+                    text: banner + summaryText + '\n' + nextSteps,
                 }],
         };
     }
@@ -676,6 +698,10 @@ export async function handleAnalysisRequest(jiraClient, request) {
     }
     const now = new Date();
     const lines = [];
+    if (filterSource) {
+        lines.push(`*Using saved filter: ${filterSource}*`);
+        lines.push('');
+    }
     // Summary first if requested alongside other metrics
     if (hasSummary) {
         const summaryText = await handleSummary(jiraClient, jql, groupBy, compute, groupLimit);
@@ -704,7 +730,7 @@ export async function handleAnalysisRequest(jiraClient, request) {
         }
     }
     // Next steps
-    const nextSteps = analysisNextSteps(jql, allIssues.slice(0, 3).map(i => i.key), truncated, groupBy);
+    const nextSteps = analysisNextSteps(jql, allIssues.slice(0, 3).map(i => i.key), truncated, groupBy, filterSource);
     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/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/prompts/prompt-messages.js

@@ -10,40 +10,50 @@ const builders = {
     backlog_health({ project }) {
         return {
             description: `Backlog health check for ${project}`,
-            messages: [msg(`Analyze backlog health for project ${project}. Use the analyze_jira_issues and manage_jira_filter tools.
+            messages: [msg(`Analyze backlog health for project ${project}. Use the queue_jira_operations tool to run this as a pipeline.
 
-Step 1 — Summary with data quality signals:
-{"jql":"project = ${project} AND resolution = Unresolved","metrics":["summary"],"groupBy":"priority","compute":["rot_pct = backlog_rot / open * 100","stale_pct = stale / open * 100","gap_pct = no_estimate / open * 100"]}
+Use queue_jira_operations with this pipeline:
+Operation 0 — Save the query as a reusable filter:
+{"tool":"manage_jira_filter","args":{"operation":"create","name":"${project} backlog health","jql":"project = ${project} AND resolution = Unresolved"}}
 
-Step 2 — Cycle metrics for staleness distribution and status age:
-{"jql":"project = ${project} AND resolution = Unresolved","metrics":["cycle"],"maxResults":100}
+Operation 1 — Summary with data quality signals (uses $0.filterId):
+{"tool":"analyze_jira_issues","args":{"filterId":"$0.filterId","metrics":["summary"],"groupBy":"priority","compute":["rot_pct = backlog_rot / open * 100","stale_pct = stale / open * 100","gap_pct = no_estimate / open * 100"]}}
 
-Step 3 — Summarize findings:
+Operation 2 — Cycle metrics for staleness distribution:
+{"tool":"analyze_jira_issues","args":{"filterId":"$0.filterId","metrics":["cycle"],"maxResults":100}}
+
+After the pipeline completes, summarize findings:
 - What percentage of the backlog is rotting (no owner, no dates, untouched)?
 - What's stuck in the same status for 30+ days?
 - What's missing estimates or start dates?
 - Flag the worst offenders by issue key.
-- Recommend specific triage actions.`)],
+- Recommend specific triage actions.
+- The saved filter can be reused for follow-up analysis or shared with the team.`)],
         };
     },
     contributor_workload({ project }) {
         return {
             description: `Contributor workload for ${project}`,
-            messages: [msg(`Analyze contributor workload for project ${project}. Use the analyze_jira_issues tool.
+            messages: [msg(`Analyze contributor workload for project ${project}. Use queue_jira_operations to run the analysis pipeline in a single call.
+
+Use queue_jira_operations with this pipeline:
+Operation 0 — Save the base query as a filter:
+{"tool":"manage_jira_filter","args":{"operation":"create","name":"${project} workload","jql":"project = ${project} AND resolution = Unresolved"}}
 
-Step 1 — Assignee distribution with quality signals:
-{"jql":"project = ${project} AND resolution = Unresolved","metrics":["summary"],"groupBy":"assignee","compute":["stale_pct = stale / open * 100","blocked_pct = blocked / open * 100"]}
+Operation 1 — Assignee distribution with quality signals (uses $0.filterId):
+{"tool":"analyze_jira_issues","args":{"filterId":"$0.filterId","metrics":["summary"],"groupBy":"assignee","compute":["stale_pct = stale / open * 100","blocked_pct = blocked / open * 100"]}}
 
-Step 2 — For the top 3 assignees by open issue count, run scoped detail metrics:
+After the pipeline, for the top 3 assignees by open count, run scoped detail:
 {"jql":"project = ${project} AND resolution = Unresolved AND assignee = '{name}'","metrics":["cycle","schedule"]}
 
-This pattern keeps each detail query within the sample cap for precise results.
+This keeps each detail query within the sample cap for precise results.
 
-Step 3 — Summarize:
+Summarize:
 - Who has the most open work?
 - Who has the most stale or at-risk issues?
 - Are there load imbalances?
-- What needs reassignment or triage?`)],
+- What needs reassignment or triage?
+- The saved filter can be reused for follow-up workload checks.`)],
         };
     },
     sprint_review({ board_id }) {
@@ -52,16 +62,21 @@ Step 3 — Summarize:
             messages: [msg(`Prepare a sprint review for board ${board_id}. Use manage_jira_sprint and analyze_jira_issues tools.
 
 Step 1 — Find the active sprint:
-{"operation":"list","boardId":${board_id},"state":"active"}
+Use manage_jira_sprint: {"operation":"list","boardId":${board_id},"state":"active"}
+
+Step 2 — Use queue_jira_operations to run the analysis pipeline (use the sprint ID from step 1):
+Operation 0 — Save the sprint query as a filter:
+{"tool":"manage_jira_filter","args":{"operation":"create","name":"Sprint review board ${board_id}","jql":"sprint = {sprintId}"}}
 
-Step 2 — Analyze sprint issues (use the sprint ID from step 1):
-{"jql":"sprint = {sprintId}","metrics":["summary","points","schedule"],"compute":["done_pct = resolved_7d / total * 100"]}
+Operation 1 — Summary + velocity metrics:
+{"tool":"analyze_jira_issues","args":{"filterId":"$0.filterId","metrics":["summary","points","schedule"],"compute":["done_pct = resolved_7d / total * 100"]}}
 
 Step 3 — Summarize:
 - Current velocity vs planned
 - Scope changes (items added/removed mid-sprint)
 - At-risk items (overdue, blocked, stale)
-- Completion forecast — will the sprint goal be met?`)],
+- Completion forecast — will the sprint goal be met?
+- The saved filter persists for daily standups or end-of-sprint reporting.`)],
         };
     },
     narrow_analysis({ jql }) {

package/build/schemas/tool-schemas.js

@@ -326,13 +326,17 @@ export const toolSchemas = {
     },
     analyze_jira_issues: {
         name: 'analyze_jira_issues',
-        description: 'Compute project metrics over issues selected by JQL. For counting and breakdown questions ("how many by status/assignee/priority"), use metrics: ["summary"] with groupBy — this gives exact counts with no issue cap. Use detail metrics (points, time, schedule, cycle, distribution) only when you need per-issue analysis; these are capped at maxResults issues. Always prefer this tool over manage_jira_filter or manage_jira_project for quantitative questions. Read jira://analysis/recipes for composition patterns.',
+        description: 'Compute project metrics over issues selected by JQL or a saved filter. For counting and breakdown questions ("how many by status/assignee/priority"), use metrics: ["summary"] with groupBy — this gives exact counts with no issue cap. Use detail metrics (points, time, schedule, cycle, distribution) only when you need per-issue analysis; these are capped at maxResults issues. Always prefer this tool over manage_jira_filter or manage_jira_project for quantitative questions. Tip: save complex JQL as a filter with manage_jira_filter, then reuse the filterId here for repeated analysis. Read jira://analysis/recipes for composition patterns.',
         inputSchema: {
             type: 'object',
             properties: {
                 jql: {
                     type: 'string',
-                    description: 'JQL query selecting the issues to analyze. Examples: "project in (AA, GC, LGS)", "sprint in openSprints()", "assignee = currentUser() AND resolution = Unresolved".',
+                    description: 'JQL query selecting the issues to analyze. Either jql or filterId is required (filterId takes precedence). Examples: "project in (AA, GC, LGS)", "sprint in openSprints()", "assignee = currentUser() AND resolution = Unresolved".',
+                },
+                filterId: {
+                    type: 'string',
+                    description: 'ID of a saved Jira filter to use as the query source. The filter\'s JQL is resolved automatically. Use this to run different analyses against a saved query without repeating the JQL. Create filters with manage_jira_filter.',
                 },
                 metrics: {
                     type: 'array',
@@ -364,12 +368,12 @@ export const toolSchemas = {
                     default: 100,
                 },
             },
-            required: ['jql'],
+            required: [],
         },
     },
     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).',
+        description: 'Execute multiple Jira operations in a single call. Operations run sequentially with result references ($0.key) and per-operation error strategies (bail/continue). Powerful for analysis pipelines: create a filter, then run multiple analyze_jira_issues calls against $0.filterId with different groupBy/compute — all in one call.',
         inputSchema: {
             type: 'object',
             properties: {

package/build/utils/next-steps.js

@@ -61,7 +61,7 @@ export function filterNextSteps(operation, filterId, jql) {
             steps.push({ description: 'Run a filter', tool: 'manage_jira_filter', example: { operation: 'execute_filter', filterId: '<id>' } }, { description: 'Search with JQL directly', tool: 'manage_jira_filter', example: { operation: 'execute_jql', jql: '<query>' } });
             break;
         case 'create':
-            steps.push({ description: 'Execute the new filter', tool: 'manage_jira_filter', example: { operation: 'execute_filter', filterId } });
+            steps.push({ description: 'Execute the new filter', tool: 'manage_jira_filter', example: { operation: 'execute_filter', filterId } }, { description: 'Run analysis against this filter', tool: 'analyze_jira_issues', example: { filterId, metrics: ['summary'], groupBy: 'assignee' } });
             break;
     }
     return steps.length > 0 ? formatSteps(steps) : '';
@@ -125,7 +125,7 @@ export function boardNextSteps(operation, boardId) {
     }
     return steps.length > 0 ? formatSteps(steps) : '';
 }
-export function analysisNextSteps(jql, issueKeys, truncated = false, groupBy) {
+export function analysisNextSteps(jql, issueKeys, truncated = false, groupBy, filterSource) {
     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] } });
@@ -144,5 +144,9 @@ export function analysisNextSteps(jql, issueKeys, truncated = false, groupBy) {
     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'] } });
     }
+    // Suggest saving as filter if not already using one
+    if (!filterSource) {
+        steps.push({ description: 'Save this query as a filter for reuse across analyses', tool: 'manage_jira_filter', example: { operation: 'create', name: '<descriptive name>', jql } });
+    }
     return formatSteps(steps) + '\n- Read `jira://analysis/recipes` for data cube patterns and compute DSL examples';
 }

package/package.json

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