@aaronsb/jira-cloud-mcp 0.5.10 → 0.6.0

package/build/client/graph-object-cache.js

@@ -0,0 +1,127 @@
+import { GraphQLHierarchyWalker, walkTree } from './graphql-hierarchy.js';
+export const MAX_ITEMS = 10_000;
+export const MAX_WALKS = 5;
+export const STALE_EPOCH_DELTA = 100;
+export const DEFAULT_WALK_DEPTH = 3;
+export class GraphObjectCache {
+    walks = new Map();
+    epoch = 0;
+    /** Increment epoch — call on every tool invocation. */
+    tick() {
+        this.epoch++;
+    }
+    getEpoch() {
+        return this.epoch;
+    }
+    /** Start a background hierarchy walk for the given root issue key. */
+    startWalk(rootKey, graphqlClient) {
+        // Evict if at capacity — remove oldest by createdEpoch
+        if (this.walks.size >= MAX_WALKS && !this.walks.has(rootKey)) {
+            let oldestKey = null;
+            let oldestEpoch = Infinity;
+            for (const [key, walk] of this.walks) {
+                if (walk.createdEpoch < oldestEpoch) {
+                    oldestEpoch = walk.createdEpoch;
+                    oldestKey = key;
+                }
+            }
+            if (oldestKey)
+                this.walks.delete(oldestKey);
+        }
+        const tree = {
+            issue: {
+                key: rootKey,
+                summary: '',
+                issueType: 'Unknown',
+                hierarchyLevel: null,
+                status: 'Unknown',
+                statusCategory: 'unknown',
+                assignee: null,
+                startDate: null,
+                dueDate: null,
+                storyPoints: null,
+                isResolved: false,
+                hasChildIssues: false,
+                parentKey: null,
+            },
+            children: [],
+        };
+        const flatIndex = new Map();
+        flatIndex.set(rootKey, tree.issue);
+        const cached = {
+            rootKey,
+            tree,
+            flatIndex,
+            state: 'walking',
+            itemCount: 0,
+            createdEpoch: this.epoch,
+        };
+        // Start async walk with progress reporting
+        const walker = new GraphQLHierarchyWalker(graphqlClient);
+        cached.walkPromise = walker.walkDown(rootKey, DEFAULT_WALK_DEPTH, MAX_ITEMS, (count) => {
+            cached.itemCount = count;
+        }).then(({ tree: walked, totalItems }) => {
+            cached.tree = walked;
+            cached.itemCount = totalItems;
+            cached.state = 'complete';
+            // Rebuild flat index from walked tree
+            cached.flatIndex.clear();
+            walkTree(walked, (node) => {
+                cached.flatIndex.set(node.issue.key, node.issue);
+            });
+        }).catch((err) => {
+            console.error(`[graph-cache] Walk failed for ${rootKey}:`, err);
+            cached.state = 'error';
+            cached.error = err.message ?? 'Unknown error';
+        });
+        this.walks.set(rootKey, cached);
+        return cached;
+    }
+    /** Get the status of a cached walk. */
+    getStatus(rootKey) {
+        const walk = this.walks.get(rootKey);
+        if (!walk) {
+            return { state: 'not_found', itemCount: 0, stale: false };
+        }
+        if (walk.state === 'error') {
+            return { state: 'error', itemCount: walk.itemCount, stale: false, error: walk.error };
+        }
+        const stale = walk.state === 'complete' && (this.epoch - walk.createdEpoch) > STALE_EPOCH_DELTA;
+        return {
+            state: stale ? 'stale' : walk.state,
+            itemCount: walk.itemCount,
+            stale,
+        };
+    }
+    /** Get a cached walk by root key. Returns null if not found. */
+    get(rootKey) {
+        return this.walks.get(rootKey) ?? null;
+    }
+    /**
+     * Patch a specific issue's fields in any cached walk.
+     * Uses the flat index for O(1) lookup. Returns true if the issue was found and patched.
+     */
+    patch(issueKey, fields) {
+        for (const walk of this.walks.values()) {
+            const issue = walk.flatIndex.get(issueKey);
+            if (issue) {
+                Object.assign(issue, fields);
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Release a cached walk, freeing memory. */
+    release(rootKey) {
+        return this.walks.delete(rootKey);
+    }
+    /** Check if any walk is stale given the current epoch. */
+    hasStaleWalks() {
+        for (const walk of this.walks.values()) {
+            if (walk.state === 'complete' && (this.epoch - walk.createdEpoch) > STALE_EPOCH_DELTA) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

package/build/client/graphql-client.js

@@ -0,0 +1,95 @@
+const AGG_ENDPOINT = 'https://api.atlassian.com/graphql';
+const TENANT_CONTEXT_QUERY = `
+  query GetTenantContexts($hostNames: [String!]!) {
+    tenantContexts(hostNames: $hostNames) {
+      cloudId
+    }
+  }
+`;
+function buildAuthHeader(email, apiToken) {
+    return `Basic ${Buffer.from(`${email}:${apiToken}`).toString('base64')}`;
+}
+function extractHostname(host) {
+    return host
+        .replace(/^https?:\/\//, '')
+        .replace(/\/.*$/, '');
+}
+/**
+ * Discover the Atlassian cloudId for a given Jira host.
+ * Returns null if discovery fails (non-Atlassian host, bad credentials, etc.)
+ */
+export async function discoverCloudId(host, email, apiToken) {
+    const hostname = extractHostname(host);
+    try {
+        const response = await fetch(AGG_ENDPOINT, {
+            method: 'POST',
+            headers: {
+                'Authorization': buildAuthHeader(email, apiToken),
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+            },
+            body: JSON.stringify({
+                query: TENANT_CONTEXT_QUERY,
+                variables: { hostNames: [hostname] },
+            }),
+        });
+        if (!response.ok) {
+            console.error(`[jira-cloud] CloudId discovery failed: HTTP ${response.status}`);
+            return null;
+        }
+        const result = await response.json();
+        if (result.errors?.length) {
+            console.error(`[jira-cloud] CloudId discovery GraphQL error: ${result.errors[0].message}`);
+            return null;
+        }
+        const cloudId = result.data?.tenantContexts?.[0]?.cloudId;
+        if (!cloudId) {
+            console.error(`[jira-cloud] CloudId discovery: no tenant found for ${hostname}`);
+            return null;
+        }
+        return cloudId;
+    }
+    catch (err) {
+        console.error(`[jira-cloud] CloudId discovery failed:`, err.message);
+        return null;
+    }
+}
+export class GraphQLClient {
+    authHeader;
+    cloudId;
+    constructor(email, apiToken, cloudId) {
+        this.authHeader = buildAuthHeader(email, apiToken);
+        this.cloudId = cloudId;
+    }
+    getCloudId() {
+        return this.cloudId;
+    }
+    async query(query, variables = {}) {
+        try {
+            const response = await fetch(AGG_ENDPOINT, {
+                method: 'POST',
+                headers: {
+                    'Authorization': this.authHeader,
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/json',
+                    'X-ExperimentalApi': 'JiraPlan,JiraPlansSupport',
+                },
+                body: JSON.stringify({
+                    query,
+                    variables: { cloudId: this.cloudId, ...variables },
+                }),
+            });
+            if (!response.ok) {
+                return { success: false, error: `HTTP ${response.status}: ${response.statusText}` };
+            }
+            const result = await response.json();
+            if (result.errors?.length) {
+                return { success: false, error: result.errors.map(e => e.message).join('; ') };
+            }
+            return { success: true, data: result.data };
+        }
+        catch (err) {
+            return { success: false, error: err.message };
+        }
+    }
+}

package/build/client/graphql-hierarchy.js

@@ -0,0 +1,253 @@
+const ISSUE_SEARCH_QUERY = `
+  query SearchChildren($cloudId: ID!, $jql: String!, $first: Int!) {
+    jira {
+      issueSearch(
+        cloudId: $cloudId,
+        issueSearchInput: { jql: $jql },
+        first: $first
+      ) @optIn(to: "JiraSpreadsheetComponent-M1") {
+        totalCount
+        edges {
+          node {
+            key
+            summary
+            issueTypeField { issueType { name hierarchy { level } } }
+            statusField { status { name statusCategory { name } } }
+            assigneeField { user { name } }
+            dueDateField { date }
+            startDateField { date }
+            storyPointsField { number }
+            storyPointEstimateField { number }
+            isResolved
+            hasChildIssues
+            parentIssueField { parentIssue { key } }
+          }
+        }
+      }
+    }
+  }
+`;
+const DEFAULT_MAX_DEPTH = 4;
+const DEFAULT_MAX_ITEMS = 200;
+const PAGE_SIZE = 50;
+const ISSUE_KEY_PATTERN = /^[A-Z][A-Z0-9_]+-\d+$/;
+/** Map a raw AGG issue node to our clean GraphIssue type */
+function mapIssueNode(node) {
+    return {
+        key: node.key,
+        summary: node.summary,
+        issueType: node.issueTypeField?.issueType?.name ?? 'Unknown',
+        hierarchyLevel: node.issueTypeField?.issueType?.hierarchy?.level ?? null,
+        status: node.statusField?.status?.name ?? 'Unknown',
+        statusCategory: node.statusField?.status?.statusCategory?.name ?? 'unknown',
+        assignee: node.assigneeField?.user?.name ?? null,
+        startDate: node.startDateField?.date ?? null,
+        dueDate: node.dueDateField?.date ?? null,
+        storyPoints: node.storyPointsField?.number ?? node.storyPointEstimateField?.number ?? null,
+        isResolved: node.isResolved ?? false,
+        hasChildIssues: node.hasChildIssues ?? false,
+        parentKey: node.parentIssueField?.parentIssue?.key ?? null,
+    };
+}
+export class GraphQLHierarchyWalker {
+    client;
+    itemCount = 0;
+    truncated = false;
+    onProgress;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Get current item count (useful for progress reporting during async walks). */
+    getItemCount() {
+        return this.itemCount;
+    }
+    /**
+     * Walk down from a root issue key, collecting all descendants.
+     * Uses JQL `parent = KEY` at each level for efficient batch fetching.
+     */
+    async walkDown(issueKey, maxDepth = DEFAULT_MAX_DEPTH, maxItems = DEFAULT_MAX_ITEMS, onProgress) {
+        this.itemCount = 0;
+        this.truncated = false;
+        this.onProgress = onProgress;
+        if (!ISSUE_KEY_PATTERN.test(issueKey)) {
+            throw new Error(`Invalid issue key format: ${issueKey}`);
+        }
+        const rootResult = await this.client.query(ISSUE_SEARCH_QUERY, {
+            jql: `key = ${issueKey}`,
+            first: 1,
+        });
+        const rootNode = rootResult.data?.jira?.issueSearch?.edges?.[0]?.node;
+        if (!rootResult.success || !rootNode) {
+            throw new Error(rootResult.error
+                ? `GraphQL error: ${rootResult.error}`
+                : `Issue ${issueKey} not found via GraphQL search`);
+        }
+        const rootIssue = mapIssueNode(rootNode);
+        this.itemCount = 1;
+        const tree = {
+            issue: rootIssue,
+            children: [],
+        };
+        if (rootIssue.hasChildIssues && maxDepth > 0) {
+            await this.fetchChildren(tree, 1, maxDepth, maxItems);
+        }
+        return {
+            tree,
+            totalItems: this.itemCount,
+            truncated: this.truncated,
+        };
+    }
+    async fetchChildren(parent, currentDepth, maxDepth, maxItems) {
+        if (currentDepth > maxDepth || this.itemCount >= maxItems) {
+            this.truncated = true;
+            return;
+        }
+        const jql = `parent = ${parent.issue.key} ORDER BY rank`;
+        const remaining = maxItems - this.itemCount;
+        const first = Math.min(PAGE_SIZE, remaining);
+        const result = await this.client.query(ISSUE_SEARCH_QUERY, {
+            jql,
+            first,
+        });
+        if (!result.success || !result.data)
+            return;
+        const edges = result.data.jira?.issueSearch?.edges ?? [];
+        const totalCount = result.data.jira?.issueSearch?.totalCount ?? 0;
+        if (totalCount > first) {
+            this.truncated = true;
+        }
+        for (const edge of edges) {
+            if (this.itemCount >= maxItems) {
+                this.truncated = true;
+                break;
+            }
+            const issue = mapIssueNode(edge.node);
+            this.itemCount++;
+            this.onProgress?.(this.itemCount);
+            const childNode = { issue, children: [] };
+            parent.children.push(childNode);
+            if (issue.hasChildIssues && currentDepth < maxDepth) {
+                await this.fetchChildren(childNode, currentDepth + 1, maxDepth, maxItems);
+            }
+        }
+    }
+    /**
+     * Compute rollups bottom-up on a collected tree.
+     * Aggregates dates, points, progress, and assignees from leaves upward.
+     */
+    static computeRollups(tree) {
+        const leaves = collectLeaves(tree);
+        const allNodes = [];
+        walkTree(tree, n => allNodes.push(n.issue));
+        const conflicts = [];
+        detectConflicts(tree, conflicts);
+        // Dates: earliest start, latest due across all descendants
+        const starts = allNodes
+            .map(n => n.startDate)
+            .filter((d) => d !== null);
+        const dues = allNodes
+            .map(n => n.dueDate)
+            .filter((d) => d !== null);
+        const rolledUpStart = starts.length > 0 ? starts.sort()[0] : null;
+        const rolledUpEnd = dues.length > 0 ? dues.sort().reverse()[0] : null;
+        // Points
+        const totalPoints = leaves.reduce((sum, n) => sum + (n.storyPoints ?? 0), 0);
+        const earnedPoints = leaves
+            .filter(n => n.isResolved)
+            .reduce((sum, n) => sum + (n.storyPoints ?? 0), 0);
+        // Progress (leaf-based)
+        const resolvedItems = leaves.filter(n => n.isResolved).length;
+        const totalItems = leaves.length;
+        const progressPct = totalItems > 0 ? Math.round((resolvedItems / totalItems) * 100) : 0;
+        // Assignees
+        const assigneeSet = new Set();
+        let unassignedCount = 0;
+        for (const node of allNodes) {
+            if (node.assignee) {
+                assigneeSet.add(node.assignee);
+            }
+            else if (!node.isResolved) {
+                unassignedCount++;
+            }
+        }
+        return {
+            rolledUpStart,
+            rolledUpEnd,
+            totalItems: allNodes.length,
+            resolvedItems,
+            progressPct,
+            totalPoints,
+            earnedPoints,
+            assignees: [...assigneeSet].sort(),
+            unassignedCount,
+            conflicts,
+        };
+    }
+}
+// --- Tree utilities (exported for testing) ---
+export function collectLeaves(node) {
+    if (node.children.length === 0)
+        return [node.issue];
+    return node.children.flatMap(collectLeaves);
+}
+export function walkTree(node, fn) {
+    fn(node);
+    for (const child of node.children) {
+        walkTree(child, fn);
+    }
+}
+export function computeDepth(node) {
+    if (node.children.length === 0)
+        return 1;
+    return 1 + Math.max(...node.children.map(computeDepth));
+}
+function detectConflicts(node, conflicts) {
+    if (node.children.length === 0)
+        return;
+    // Own due date earlier than latest child due
+    if (node.issue.dueDate) {
+        const childDues = node.children
+            .map(c => c.issue.dueDate)
+            .filter((d) => d !== null);
+        const latestChild = childDues.sort().reverse()[0];
+        if (latestChild && latestChild > node.issue.dueDate) {
+            const ownDate = new Date(node.issue.dueDate);
+            const childDate = new Date(latestChild);
+            const diffDays = Math.ceil((childDate.getTime() - ownDate.getTime()) / (1000 * 60 * 60 * 24));
+            conflicts.push({
+                issueKey: node.issue.key,
+                type: 'due_date',
+                message: `Children end ${diffDays}d after parent due date`,
+            });
+        }
+    }
+    // Own start date later than earliest child start
+    if (node.issue.startDate) {
+        const childStarts = node.children
+            .map(c => c.issue.startDate)
+            .filter((d) => d !== null);
+        const earliestChild = childStarts.sort()[0];
+        if (earliestChild && earliestChild < node.issue.startDate) {
+            conflicts.push({
+                issueKey: node.issue.key,
+                type: 'start_date',
+                message: 'Children start before parent start date',
+            });
+        }
+    }
+    // Resolved parent with open children
+    if (node.issue.isResolved) {
+        const openChildren = node.children.filter(c => !c.issue.isResolved);
+        if (openChildren.length > 0) {
+            conflicts.push({
+                issueKey: node.issue.key,
+                type: 'resolved_with_open_children',
+                message: `Resolved but has ${openChildren.length} open children`,
+            });
+        }
+    }
+    // Recurse
+    for (const child of node.children) {
+        detectConflicts(child, conflicts);
+    }
+}

package/build/client/jira-client.js

@@ -104,6 +104,7 @@ export class JiraClient {
             people.push({ displayName: fields.reporter.displayName, accountId: fields.reporter.accountId, role: 'reporter' });
         }
         return {
+            id: issue.id,
             key: issue.key,
             summary: fields?.summary,
             description: fields?.description
@@ -410,6 +411,38 @@ export class JiraClient {
             url: attachment.content || '',
         }));
     }
+    async getBulkChangelogs(issueKeys, fieldIds = ['status']) {
+        const result = new Map();
+        let nextPageToken;
+        do {
+            const response = await this.client.issues.getBulkChangelogs({
+                issueIdsOrKeys: issueKeys,
+                fieldIds,
+                maxResults: 1000,
+                nextPageToken,
+            });
+            for (const issueLog of response.issueChangeLogs || []) {
+                const issueId = issueLog.issueId;
+                if (!issueId)
+                    continue;
+                const transitions = result.get(issueId) || [];
+                for (const history of issueLog.changeHistories || []) {
+                    for (const item of history.items || []) {
+                        if (item.field === 'status') {
+                            transitions.push({
+                                date: history.created || '',
+                                from: item.fromString || '',
+                                to: item.toString || '',
+                            });
+                        }
+                    }
+                }
+                result.set(issueId, transitions);
+            }
+            nextPageToken = response.nextPageToken ?? undefined;
+        } while (nextPageToken);
+        return result;
+    }
     async getFilter(filterId) {
         return await this.client.filters.getFilter({
             id: parseInt(filterId, 10),

package/build/docs/tool-documentation.js

@@ -528,6 +528,14 @@ function generateAnalysisToolDocumentation(schema) {
                     { description: "Summary only", code: { jql: "project = AA", metrics: ["summary"] } },
                 ],
             },
+            {
+                title: "Flow analysis — where do issues get stuck?",
+                description: "Analyze status transitions, time in status, and bounce patterns:",
+                steps: [
+                    { description: "Flow metrics", code: { jql: "project = AA AND resolution = Unresolved", metrics: ["flow"] } },
+                    { description: "Combined with summary", code: { jql: "project = AA", metrics: ["summary", "flow"], groupBy: "issuetype" } },
+                ],
+            },
             {
                 title: "Data cube — discover then compute",
                 description: "Two-phase analysis with computed columns:",