@aaronsb/jira-cloud-mcp 0.5.10 → 0.6.0

package/build/handlers/plan-handler.js

@@ -0,0 +1,351 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { GraphQLHierarchyWalker, collectLeaves, computeDepth, walkTree } from '../client/graphql-hierarchy.js';
+import { planNextSteps } from '../utils/next-steps.js';
+import { normalizeArgs } from '../utils/normalize-args.js';
+const ALL_ROLLUPS = ['dates', 'points', 'progress', 'assignees'];
+const MAX_CHILDREN_DISPLAY = 20;
+export async function handlePlanRequest(_jiraClient, graphqlClient, request, cache) {
+    const args = normalizeArgs(request.params?.arguments ?? {});
+    const issueKey = args.issueKey;
+    if (!issueKey) {
+        throw new McpError(ErrorCode.InvalidParams, 'issueKey is required for analyze_jira_plan');
+    }
+    const operation = args.operation ?? 'analyze';
+    // Handle release operation
+    if (operation === 'release') {
+        if (!cache) {
+            return { content: [{ type: 'text', text: 'Cache not available.' }] };
+        }
+        const released = cache.release(issueKey);
+        return {
+            content: [{
+                    type: 'text',
+                    text: released
+                        ? `Released cached walk for ${issueKey}.`
+                        : `No cached walk found for ${issueKey}.`,
+                }],
+        };
+    }
+    const rollups = (Array.isArray(args.rollups) ? args.rollups : ALL_ROLLUPS);
+    const mode = args.mode ?? 'rollup';
+    const focus = args.focus;
+    // Try cache-first path
+    if (cache) {
+        const status = cache.getStatus(issueKey);
+        if (status.state === 'error') {
+            cache.release(issueKey);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Walk failed for ${issueKey}: ${status.error ?? 'unknown error'}. Cleared from cache — call again to retry.`,
+                    }],
+                isError: true,
+            };
+        }
+        if (status.state === 'walking') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Walking hierarchy for ${issueKey}... ${status.itemCount} items collected so far.\nCall again to check progress or wait for completion.`,
+                    }],
+            };
+        }
+        if (status.state === 'not_found') {
+            cache.startWalk(issueKey, graphqlClient);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Started hierarchy walk for ${issueKey}. Call again to check progress.\n\n*The walk runs in the background — subsequent calls will show progress or full results once complete.*`,
+                    }],
+            };
+        }
+        if (status.state === 'complete' || status.state === 'stale') {
+            const cached = cache.get(issueKey);
+            const staleNote = status.stale
+                ? '> **Note:** This data may be stale. Call again to refresh, or use `operation: "release"` to clear.\n\n'
+                : '';
+            if (status.stale) {
+                cache.startWalk(issueKey, graphqlClient);
+            }
+            // Focus mode: windowed view of a specific node
+            if (focus) {
+                const output = renderFocusView(cached.tree, focus, rollups);
+                return { content: [{ type: 'text', text: staleNote + output }] };
+            }
+            // Default: summary + entry points (bounded)
+            const rollupResult = GraphQLHierarchyWalker.computeRollups(cached.tree);
+            const output = mode === 'gaps'
+                ? renderGapsSummary(cached.tree, rollups, rollupResult)
+                : renderOverview(cached.tree, issueKey, cached.itemCount, rollups, rollupResult);
+            return {
+                content: [{
+                        type: 'text',
+                        text: staleNote + output + planNextSteps(issueKey, mode, rollupResult.conflicts, rollupResult),
+                    }],
+            };
+        }
+    }
+    // Fallback: no cache, walk synchronously with original limits
+    const walker = new GraphQLHierarchyWalker(graphqlClient);
+    let tree;
+    let totalItems;
+    try {
+        ({ tree, totalItems } = await walker.walkDown(issueKey));
+    }
+    catch (err) {
+        const message = err.message;
+        if (message.includes('not found')) {
+            throw new McpError(ErrorCode.InvalidParams, `Issue ${issueKey} not found.`);
+        }
+        throw new McpError(ErrorCode.InternalError, `Hierarchy walk failed: ${message}`);
+    }
+    const rollupResult = GraphQLHierarchyWalker.computeRollups(tree);
+    const output = renderOverview(tree, issueKey, totalItems, rollups);
+    return {
+        content: [{
+                type: 'text',
+                text: output + planNextSteps(issueKey, mode, rollupResult.conflicts, rollupResult),
+            }],
+    };
+}
+// --- Rendering: Overview (summary + entry points) ---
+function renderOverview(tree, issueKey, totalItems, rollups, rollupResult) {
+    const lines = [];
+    const depth = computeDepth(tree);
+    rollupResult ??= GraphQLHierarchyWalker.computeRollups(tree);
+    lines.push(`# Plan: ${issueKey} — ${tree.issue.summary}`);
+    lines.push(`${totalItems} items, ${depth} levels deep | cached`);
+    lines.push('');
+    renderSummaryBlock(tree, lines, rollups, rollupResult);
+    lines.push('');
+    // Entry points: immediate children with their rollup summaries
+    if (tree.children.length > 0) {
+        lines.push('## Children');
+        lines.push('');
+        const shown = tree.children.slice(0, MAX_CHILDREN_DISPLAY);
+        for (const child of shown) {
+            renderNodeLine(child, lines, rollups);
+        }
+        if (tree.children.length > MAX_CHILDREN_DISPLAY) {
+            lines.push(`*...and ${tree.children.length - MAX_CHILDREN_DISPLAY} more — use \`focus\` to navigate*`);
+        }
+        lines.push('');
+        lines.push('*Use `focus: "ISSUE-KEY"` to explore any node and its neighborhood.*');
+    }
+    return lines.join('\n');
+}
+// --- Rendering: Focus (windowed view of a specific node) ---
+function findInTree(node, key, parent = null) {
+    if (node.issue.key === key)
+        return { node, parent };
+    for (const child of node.children) {
+        const found = findInTree(child, key, node);
+        if (found)
+            return found;
+    }
+    return null;
+}
+function renderFocusView(tree, focusKey, rollups) {
+    const found = findInTree(tree, focusKey);
+    if (!found) {
+        return `Issue ${focusKey} not found in cached hierarchy. Available root: ${tree.issue.key}`;
+    }
+    const focusNode = found.node;
+    const parentNode = found.parent;
+    const lines = [];
+    const rollupResult = GraphQLHierarchyWalker.computeRollups(focusNode);
+    lines.push(`# Focus: ${focusNode.issue.key} — ${focusNode.issue.summary}`);
+    lines.push(`[${focusNode.issue.issueType}] ${focusNode.issue.status}`);
+    lines.push('');
+    // Parent context
+    if (parentNode) {
+        const parentRollup = GraphQLHierarchyWalker.computeRollups(parentNode);
+        lines.push(`**Parent:** ${parentNode.issue.key} — ${parentNode.issue.summary} [${parentNode.issue.issueType}]`);
+        lines.push(`  Progress: ${parentRollup.resolvedItems}/${parentRollup.totalItems} (${parentRollup.progressPct}%)`);
+        lines.push('');
+    }
+    // This node's details
+    renderSummaryBlock(focusNode, lines, rollups, rollupResult);
+    lines.push('');
+    // Siblings (if has parent)
+    if (parentNode) {
+        const siblings = parentNode.children.filter(c => c.issue.key !== focusKey);
+        if (siblings.length > 0) {
+            lines.push(`## Siblings (${siblings.length})`);
+            lines.push('');
+            const shown = siblings.slice(0, MAX_CHILDREN_DISPLAY);
+            for (const sib of shown) {
+                renderNodeLine(sib, lines, rollups);
+            }
+            if (siblings.length > MAX_CHILDREN_DISPLAY) {
+                lines.push(`*...and ${siblings.length - MAX_CHILDREN_DISPLAY} more*`);
+            }
+            lines.push('');
+        }
+    }
+    // Children
+    if (focusNode.children.length > 0) {
+        lines.push(`## Children (${focusNode.children.length})`);
+        lines.push('');
+        const shown = focusNode.children.slice(0, MAX_CHILDREN_DISPLAY);
+        for (const child of shown) {
+            renderNodeLine(child, lines, rollups);
+        }
+        if (focusNode.children.length > MAX_CHILDREN_DISPLAY) {
+            lines.push(`*...and ${focusNode.children.length - MAX_CHILDREN_DISPLAY} more*`);
+        }
+    }
+    else {
+        lines.push('*Leaf node — no children*');
+    }
+    return lines.join('\n');
+}
+/** Render a single node as a compact line with rollup summary */
+function renderNodeLine(node, lines, rollups) {
+    const statusCat = node.issue.statusCategory.toLowerCase();
+    const icon = statusCat === 'done' ? '✓' : statusCat === 'in progress' ? '●' : '○';
+    const parts = [];
+    parts.push(`${icon} **${node.issue.key}**: ${node.issue.summary} [${node.issue.issueType}]`);
+    const details = [];
+    if (node.children.length > 0) {
+        const rollup = GraphQLHierarchyWalker.computeRollups(node);
+        if (rollups.includes('progress')) {
+            details.push(`${rollup.resolvedItems}/${rollup.totalItems} (${rollup.progressPct}%)`);
+        }
+        if (rollups.includes('points') && rollup.totalPoints > 0) {
+            details.push(`${rollup.earnedPoints}/${rollup.totalPoints} pts`);
+        }
+        if (rollups.includes('dates') && (rollup.rolledUpStart || rollup.rolledUpEnd)) {
+            details.push(`${rollup.rolledUpStart ?? '—'} – ${rollup.rolledUpEnd ?? '—'}`);
+        }
+        if (rollup.conflicts.length > 0) {
+            details.push(`${rollup.conflicts.length} conflicts`);
+        }
+    }
+    else {
+        if (node.issue.assignee)
+            details.push(node.issue.assignee);
+        if (rollups.includes('dates') && (node.issue.startDate || node.issue.dueDate)) {
+            details.push(`${node.issue.startDate ?? '—'} – ${node.issue.dueDate ?? '—'}`);
+        }
+        if (rollups.includes('points') && node.issue.storyPoints != null) {
+            details.push(`${node.issue.storyPoints} pts`);
+        }
+    }
+    if (details.length > 0) {
+        lines.push(`- ${parts[0]}`);
+        lines.push(`  ${details.join(' | ')}`);
+    }
+    else {
+        lines.push(`- ${parts[0]}`);
+    }
+}
+// --- Rendering: Gaps summary (bounded) ---
+function renderGapsSummary(tree, rollups, rollupResult) {
+    const lines = [];
+    rollupResult ??= GraphQLHierarchyWalker.computeRollups(tree);
+    lines.push(`# Gaps: ${tree.issue.key} — ${tree.issue.summary}`);
+    lines.push('');
+    const gaps = [];
+    for (const c of rollupResult.conflicts) {
+        gaps.push(`- **${c.issueKey}** [${c.type}]: ${c.message}`);
+    }
+    walkTree(tree, (node) => {
+        if (node.children.length === 0)
+            return;
+        if (rollups.includes('dates')) {
+            const undated = node.children.filter(c => !c.issue.startDate && !c.issue.dueDate);
+            const dated = node.children.length - undated.length;
+            if (undated.length > 0 && dated > 0) {
+                gaps.push(`- **${node.issue.key}**: ${undated.length}/${node.children.length} children have no dates`);
+            }
+        }
+        if (rollups.includes('points')) {
+            const unestimated = node.children.filter(c => c.issue.storyPoints == null);
+            const estimated = node.children.length - unestimated.length;
+            if (unestimated.length > 0 && estimated > 0) {
+                gaps.push(`- **${node.issue.key}**: ${unestimated.length}/${node.children.length} children have no story points`);
+            }
+        }
+        if (rollups.includes('assignees')) {
+            const unassigned = node.children.filter(c => !c.issue.assignee && !c.issue.isResolved);
+            if (unassigned.length > 0) {
+                gaps.push(`- **${node.issue.key}**: ${unassigned.length} active children unassigned`);
+            }
+        }
+    });
+    if (gaps.length === 0) {
+        lines.push('No gaps or conflicts detected.');
+    }
+    else {
+        const unique = [...new Set(gaps)];
+        // Cap output to first 30 gaps
+        const shown = unique.slice(0, 30);
+        lines.push(...shown);
+        if (unique.length > 30) {
+            lines.push(`\n*...and ${unique.length - 30} more. Use \`focus\` on a specific subtree to narrow down.*`);
+        }
+    }
+    return lines.join('\n');
+}
+// --- Shared rendering ---
+function renderSummaryBlock(tree, lines, rollups, result) {
+    if (rollups.includes('dates')) {
+        const own = `${tree.issue.startDate ?? '—'} – ${tree.issue.dueDate ?? '—'}`;
+        const derived = `${result.rolledUpStart ?? '—'} – ${result.rolledUpEnd ?? '—'}`;
+        lines.push(`**Dates:** own ${own} | rolled-up ${derived}`);
+    }
+    if (rollups.includes('points') && result.totalPoints > 0) {
+        lines.push(`**Points:** ${result.totalPoints} total, ${result.earnedPoints} earned`);
+    }
+    if (rollups.includes('progress')) {
+        lines.push(`**Progress:** ${result.resolvedItems}/${result.totalItems} resolved (${result.progressPct}%)`);
+    }
+    if (rollups.includes('assignees') && result.assignees.length > 0) {
+        lines.push(`**Team:** ${result.assignees.join(', ')}${result.unassignedCount > 0 ? ` | ${result.unassignedCount} unassigned` : ''}`);
+    }
+    if (result.conflicts.length > 0) {
+        lines.push(`**Conflicts:** ${result.conflicts.length} detected`);
+    }
+}
+/** Full tree renderer — kept for analysis-handler hierarchy metric (small trees only) */
+export function renderRollupTree(node, lines, rollups, prefix, isLast) {
+    const connector = prefix === '' ? '' : (isLast ? '└── ' : '├── ');
+    const statusCat = node.issue.statusCategory.toLowerCase();
+    const icon = statusCat === 'done' ? '✓' : statusCat === 'in progress' ? '●' : '○';
+    const label = `${icon} **${node.issue.key}**: ${node.issue.summary} [${node.issue.issueType}]`;
+    lines.push(`${prefix}${connector}${label}`);
+    const indent = prefix + (prefix === '' ? '' : (isLast ? '    ' : '│   '));
+    if (rollups.includes('dates')) {
+        const start = node.issue.startDate ?? '—';
+        const due = node.issue.dueDate ?? '—';
+        if (start !== '—' || due !== '—' || node.children.length > 0) {
+            let dateLine = `${indent}  ${start} – ${due}`;
+            if (node.children.length > 0) {
+                const childRollup = GraphQLHierarchyWalker.computeRollups(node);
+                if (childRollup.rolledUpStart || childRollup.rolledUpEnd) {
+                    dateLine += ` | rolled-up ${childRollup.rolledUpStart ?? '—'} – ${childRollup.rolledUpEnd ?? '—'}`;
+                }
+                const conflict = childRollup.conflicts.find(c => c.issueKey === node.issue.key);
+                if (conflict)
+                    dateLine += ` ⚠️ ${conflict.message}`;
+            }
+            lines.push(dateLine);
+        }
+    }
+    if (rollups.includes('points') && node.issue.storyPoints != null) {
+        lines.push(`${indent}  ${node.issue.storyPoints} pts`);
+    }
+    if (rollups.includes('progress') && node.children.length > 0) {
+        const leaves = collectLeaves(node);
+        const resolved = leaves.filter(l => l.isResolved).length;
+        lines.push(`${indent}  Progress: ${resolved}/${leaves.length} (${leaves.length > 0 ? Math.round(resolved / leaves.length * 100) : 0}%)`);
+    }
+    if (rollups.includes('assignees') && node.children.length === 0 && node.issue.assignee) {
+        lines.push(`${indent}  ${node.issue.assignee}`);
+    }
+    const childPrefix = prefix + (prefix === '' ? '' : (isLast ? '    ' : '│   '));
+    node.children.forEach((child, i) => {
+        renderRollupTree(child, lines, rollups, childPrefix, i === node.children.length - 1);
+    });
+}

package/build/index.js

@@ -4,11 +4,14 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { fieldDiscovery } from './client/field-discovery.js';
+import { GraphObjectCache } from './client/graph-object-cache.js';
+import { discoverCloudId, GraphQLClient } from './client/graphql-client.js';
 import { JiraClient } from './client/jira-client.js';
 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 { 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';
@@ -32,9 +35,34 @@ if (!JIRA_EMAIL || !JIRA_API_TOKEN || !JIRA_HOST) {
 }
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
+/** Map manage_jira_issue update args to GraphIssue field patches */
+function extractChangedFields(args) {
+    const fields = {};
+    if ('dueDate' in args)
+        fields.dueDate = args.dueDate;
+    if ('summary' in args)
+        fields.summary = args.summary;
+    if ('assignee' in args)
+        fields.assignee = args.assignee;
+    if ('storyPoints' in args)
+        fields.storyPoints = args.storyPoints;
+    // startDate may come via customFields — check both
+    if ('startDate' in args)
+        fields.startDate = args.startDate;
+    const customFields = args.customFields;
+    if (customFields) {
+        for (const [key, val] of Object.entries(customFields)) {
+            if (key.toLowerCase().includes('start'))
+                fields.startDate = val;
+        }
+    }
+    return fields;
+}
 class JiraServer {
     server;
     jiraClient;
+    graphqlClient = null;
+    cache = new GraphObjectCache();
     constructor() {
         const serverName = process.env.MCP_SERVER_NAME || 'jira-cloud';
         console.error(`Initializing Jira MCP server: ${serverName}`);
@@ -56,6 +84,8 @@ class JiraServer {
         this.setupHandlers();
         // Start async field discovery (non-blocking)
         fieldDiscovery.startAsync(this.jiraClient.v3Client);
+        // CloudId discovery happens in run() before server connects — must complete
+        // before ListTools so analyze_jira_plan is registered if available.
         this.server.onerror = (error) => console.error('[MCP Error]', error);
         process.on('SIGINT', async () => {
             await this.server.close();
@@ -66,6 +96,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)
                 .map(([key, schema]) => ({
                 name: key,
                 description: schema.description,
@@ -101,6 +132,7 @@ class JiraServer {
         // Set up tool handlers
         this.server.setRequestHandler(CallToolRequestSchema, async (request, _extra) => {
             console.error('Received request:', JSON.stringify(request, null, 2));
+            this.cache.tick();
             const { name } = request.params;
             console.error(`Handling tool request: ${name}`);
             try {
@@ -110,11 +142,14 @@ class JiraServer {
                     manage_jira_board: handleBoardRequest,
                     manage_jira_sprint: handleSprintRequest,
                     manage_jira_filter: handleFilterRequest,
-                    analyze_jira_issues: handleAnalysisRequest,
+                    analyze_jira_issues: (client, req) => handleAnalysisRequest(client, req, this.graphqlClient, this.cache),
                 };
                 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),
+                    } : {}),
                 };
                 const handler = handlers[name];
                 if (!handler) {
@@ -131,6 +166,21 @@ class JiraServer {
                         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;
                     }
+                    // Surgical cache patching — update cached issues on mutations
+                    const reqArgs = request.params.arguments;
+                    const op = reqArgs?.operation;
+                    if ((op === 'update' || op === 'transition') && this.cache.walks.size > 0) {
+                        const issueKey = reqArgs?.issueKey;
+                        if (issueKey) {
+                            const changedFields = extractChangedFields(reqArgs);
+                            if (Object.keys(changedFields).length > 0) {
+                                const patched = this.cache.patch(issueKey, changedFields);
+                                if (patched) {
+                                    console.error(`[graph-cache] Patched ${issueKey} in cache`);
+                                }
+                            }
+                        }
+                    }
                 }
                 else {
                     consecutiveIssueCalls = 0;
@@ -178,6 +228,20 @@ class JiraServer {
         });
     }
     async run() {
+        // Discover cloudId before connecting — must complete before ListTools
+        try {
+            const cloudId = await discoverCloudId(JIRA_HOST, JIRA_EMAIL, JIRA_API_TOKEN);
+            if (cloudId) {
+                this.graphqlClient = new GraphQLClient(JIRA_EMAIL, JIRA_API_TOKEN, cloudId);
+                console.error(`[jira-cloud] GraphQL client ready (cloudId: ${cloudId.slice(0, 8)}...)`);
+            }
+            else {
+                console.error('[jira-cloud] GraphQL/Plans unavailable — analyze_jira_plan disabled');
+            }
+        }
+        catch {
+            console.error('[jira-cloud] GraphQL discovery failed — analyze_jira_plan disabled');
+        }
         const transport = new StdioServerTransport();
         await this.server.connect(transport);
         console.error('Jira MCP server running on stdio');

package/build/prompts/prompt-messages.js

@@ -19,8 +19,8 @@ Operation 0 — Save the query as a reusable filter:
 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"]}}
 
-Operation 2 — Cycle metrics for staleness distribution:
-{"tool":"analyze_jira_issues","args":{"filterId":"$0.filterId","metrics":["cycle"],"maxResults":100}}
+Operation 2 — Flow analysis for transition patterns and bottlenecks:
+{"tool":"analyze_jira_issues","args":{"filterId":"$0.filterId","metrics":["flow"],"maxResults":100}}
 
 After the pipeline completes, summarize findings:
 - What percentage of the backlog is rotting (no owner, no dates, untouched)?

package/build/schemas/tool-schemas.js

@@ -326,30 +326,34 @@ export const toolSchemas = {
     },
     analyze_jira_issues: {
         name: 'analyze_jira_issues',
-        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.',
+        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) for per-issue analysis (capped at maxResults). Use flow for status transition patterns — how issues move through statuses, where they bounce, and how long they stay. 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. Either jql or filterId is required (filterId takes precedence). Examples: "project in (AA, GC, LGS)", "sprint in openSprints()", "assignee = currentUser() AND resolution = Unresolved".',
+                    description: 'JQL query selecting the issues to analyze. Either jql, filterId, or dataRef is required (dataRef > filterId > jql 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.',
                 },
+                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.',
+                },
                 metrics: {
                     type: 'array',
                     items: {
                         type: 'string',
-                        enum: ['summary', 'points', 'time', 'schedule', 'cycle', 'distribution', 'cube_setup'],
+                        enum: ['summary', 'points', 'time', 'schedule', 'cycle', 'distribution', 'flow', 'hierarchy', 'cube_setup'],
                     },
-                    description: 'Which metric groups to compute. summary = exact counts via count API (no issue cap, fastest) — use with groupBy for "how many by assignee/status/priority" questions. distribution = approximate counts from fetched issues (capped by maxResults — use summary + groupBy instead when you need exact counts). cube_setup = discover dimensions before cube queries. points = earned value/SPI. time = effort estimates. schedule = overdue/risk. cycle = lead time/throughput. Default: all detail metrics. For counting/breakdown questions, always prefer summary + groupBy over distribution.',
+                    description: 'Which metric groups to compute. summary = exact counts via count API (no issue cap, fastest) — use with groupBy for "how many by assignee/status/priority" questions. distribution = approximate counts from fetched issues (capped by maxResults — use summary + groupBy instead when you need exact counts). flow = status transition analysis from bulk changelogs — entries per status, avg time in each, bounce rates, top bouncers. hierarchy = tree visualization with rollups for parent-child structures (requires GraphQL — opt-in like flow). cube_setup = discover dimensions before cube queries. points = earned value/SPI. time = effort estimates. schedule = overdue/risk. cycle = lead time/throughput. Default: all detail metrics (excluding flow and hierarchy — request explicitly). For counting/breakdown questions, always prefer summary + groupBy over distribution.',
                 },
                 groupBy: {
                     type: 'string',
-                    enum: ['project', 'assignee', 'priority', 'issuetype'],
-                    description: 'Split counts by this dimension — produces a breakdown table. Use with metrics: ["summary"] for exact counts. This is the correct approach for "how many issues per assignee/priority/type" questions. "project" produces a per-project comparison.',
+                    enum: ['project', 'assignee', 'priority', 'issuetype', 'parent'],
+                    description: 'Split counts by this dimension — produces a breakdown table. Use with metrics: ["summary"] for exact counts. This is the correct approach for "how many issues per assignee/priority/type" questions. "project" produces a per-project comparison. "parent" groups by parent issue — useful for seeing rollups per epic/initiative.',
                 },
                 compute: {
                     type: 'array',
@@ -371,6 +375,42 @@ 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.',
+        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.',
+                },
+                issueKey: {
+                    type: 'string',
+                    description: 'Issue key at the root of the plan tree (e.g., PROJ-100). Required.',
+                },
+                rollups: {
+                    type: 'array',
+                    items: {
+                        type: 'string',
+                        enum: ['dates', 'points', 'progress', 'assignees'],
+                    },
+                    description: 'Which rollup dimensions to include. Default: all.',
+                },
+                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.',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['rollup', 'gaps'],
+                    description: 'Output mode. rollup (default): summary + entry points. gaps: conflicts and missing data only.',
+                },
+            },
+            required: ['issueKey'],
+        },
+    },
     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). 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.',

package/build/utils/next-steps.js

@@ -39,7 +39,7 @@ export function issueNextSteps(operation, issueKey) {
             steps.push({ description: 'View the linked issue', tool: 'manage_jira_issue', example: { operation: 'get', issueKey } }, { description: 'Read available link types from jira://issue-link-types resource' });
             break;
         case 'hierarchy':
-            steps.push({ description: 'View a specific issue from the tree', tool: 'manage_jira_issue', example: { operation: 'get', 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: '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]}"` } });
             break;
     }
     return steps.length > 0 ? formatSteps(steps) : '';
@@ -125,6 +125,52 @@ export function boardNextSteps(operation, boardId) {
     }
     return steps.length > 0 ? formatSteps(steps) : '';
 }
+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' } });
+    }
+    if (mode !== 'timeline') {
+        steps.push({ description: 'View the timeline', tool: 'analyze_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);
+    // Append conflict fix operations if conflicts exist
+    if (conflicts && conflicts.length > 0 && rollup) {
+        result += conflictFixSteps(conflicts, rollup);
+    }
+    return result;
+}
+export function conflictFixSteps(conflicts, rollup) {
+    const fixOps = [];
+    const lines = ['\n\n**Conflict fixes:**'];
+    for (const conflict of conflicts) {
+        switch (conflict.type) {
+            case 'due_date':
+                if (rollup.rolledUpEnd) {
+                    lines.push(`- Update ${conflict.issueKey} due date to ${rollup.rolledUpEnd} — \`manage_jira_issue\` \`{ operation: "update", issueKey: "${conflict.issueKey}", dueDate: "${rollup.rolledUpEnd}" }\``);
+                    fixOps.push({ tool: 'manage_jira_issue', args: { operation: 'update', issueKey: conflict.issueKey, dueDate: rollup.rolledUpEnd } });
+                }
+                break;
+            case 'start_date':
+                if (rollup.rolledUpStart) {
+                    lines.push(`- Update ${conflict.issueKey} start date to ${rollup.rolledUpStart} — read \`jira://custom-fields\` to find the start date field ID, then use \`manage_jira_issue update\``);
+                    // Don't auto-generate queue op for start date — field ID is instance-specific
+                }
+                break;
+            case 'resolved_with_open_children':
+                lines.push(`- ${conflict.issueKey}: ${conflict.message} — reopen parent or resolve open children (use \`manage_jira_issue get\` with \`expand: ["transitions"]\` to find transition IDs)`);
+                break;
+        }
+    }
+    if (fixOps.length > 0) {
+        lines.push('');
+        lines.push('**Fix all date conflicts in one call:**');
+        lines.push(`\`queue_jira_operations\` — \`${JSON.stringify({ operations: fixOps.map(op => ({ ...op, onError: 'continue' })) })}\``);
+    }
+    return lines.join('\n');
+}
 export function analysisNextSteps(jql, issueKeys, truncated = false, groupBy, filterSource) {
     const steps = [];
     if (issueKeys.length > 0) {
@@ -144,6 +190,10 @@ export function analysisNextSteps(jql, issueKeys, truncated = false, groupBy, fi
     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 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] } });
+    }
     // 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 } });