@aaronsb/jira-cloud-mcp 0.3.1 → 0.4.1

package/README.md

@@ -2,9 +2,19 @@
 
 A Model Context Protocol server for interacting with Jira Cloud instances.
 
-## Quick Start
+## Install
 
-Add to your MCP settings:
+### Claude Desktop (one-click)
+
+Download [`jira-cloud-mcp.mcpb`](https://github.com/aaronsb/jira-cloud/releases/latest) and open it — Claude Desktop will prompt for your Jira credentials.
+
+### Claude Code
+
+```bash
+claude mcp add jira-cloud -e JIRA_API_TOKEN=your-token -e JIRA_EMAIL=your-email -e JIRA_HOST=https://your-team.atlassian.net -- npx -y @aaronsb/jira-cloud-mcp
+```
+
+### Manual (any MCP client)
 
 ```json
 {
@@ -22,12 +32,6 @@ Add to your MCP settings:
 }
 ```
 
-Or install globally:
-
-```bash
-npm install -g @aaronsb/jira-cloud-mcp
-```
-
 ### Credentials
 
 Generate an API token at [Atlassian Account Settings](https://id.atlassian.com/manage/api-tokens).

package/build/client/jira-client.js

@@ -175,6 +175,153 @@ export class JiraClient {
         }
         return issueDetails;
     }
+    /** Lightweight fetch: key, summary, issuetype, status, parent only */
+    async fetchNodeFields(issueKey) {
+        const issue = await this.client.issues.getIssue({
+            issueIdOrKey: issueKey,
+            fields: ['summary', 'issuetype', 'status', 'parent'],
+        });
+        const f = issue.fields;
+        return {
+            key: issue.key,
+            summary: f?.summary || '',
+            issueType: f?.issuetype?.name || '',
+            status: f?.status?.name || '',
+            parent: f?.parent?.key || null,
+        };
+    }
+    /** Fetch children of given keys in one JQL query. Returns truncated flag if results hit the limit. */
+    async fetchChildren(parentKeys) {
+        if (parentKeys.length === 0)
+            return { children: [], truncated: false };
+        const maxResults = 100;
+        const jql = `parent in (${parentKeys.join(', ')})`;
+        const results = await this.client.issueSearch.searchForIssuesUsingJqlEnhancedSearch({
+            jql,
+            maxResults,
+            fields: ['summary', 'issuetype', 'status', 'parent'],
+        });
+        const issues = results.issues || [];
+        return {
+            children: issues.map((issue) => ({
+                key: issue.key,
+                summary: issue.fields?.summary || '',
+                issueType: issue.fields?.issuetype?.name || '',
+                status: issue.fields?.status?.name || '',
+                parent: issue.fields?.parent?.key || '',
+            })),
+            truncated: issues.length >= maxResults,
+        };
+    }
+    /**
+     * Traverse the issue hierarchy: walk up `upHops` levels and down `downHops` levels
+     * from the focus issue, returning a tree with a "you are here" marker.
+     */
+    async getHierarchy(issueKey, upHops = 4, downHops = 4) {
+        // 1. Fetch focus node
+        const focus = await this.fetchNodeFields(issueKey);
+        // 2. Walk UP the parent chain (with circular reference guard)
+        const ancestors = [];
+        const visited = new Set([focus.key]);
+        let current = focus;
+        for (let i = 0; i < upHops; i++) {
+            if (!current.parent || visited.has(current.parent))
+                break;
+            visited.add(current.parent);
+            const parentNode = await this.fetchNodeFields(current.parent);
+            ancestors.unshift(parentNode); // prepend — root first
+            current = parentNode;
+        }
+        // Build the focus node
+        const focusNode = {
+            key: focus.key,
+            summary: focus.summary,
+            issueType: focus.issueType,
+            status: focus.status,
+            children: [],
+        };
+        // BFS: expand children level by level
+        let truncated = false;
+        let actualDownDepth = 0;
+        let frontier = [focusNode];
+        for (let level = 0; level < downHops; level++) {
+            const parentKeys = frontier.map(n => n.key);
+            const result = await this.fetchChildren(parentKeys);
+            if (result.children.length === 0)
+                break;
+            if (result.truncated)
+                truncated = true;
+            actualDownDepth = level + 1;
+            // Group children by parent
+            const byParent = new Map();
+            for (const child of result.children) {
+                const group = byParent.get(child.parent) || [];
+                group.push(child);
+                byParent.set(child.parent, group);
+            }
+            const nextFrontier = [];
+            for (const parent of frontier) {
+                const childNodes = (byParent.get(parent.key) || []).map(c => ({
+                    key: c.key,
+                    summary: c.summary,
+                    issueType: c.issueType,
+                    status: c.status,
+                    children: [],
+                }));
+                parent.children = childNodes;
+                nextFrontier.push(...childNodes);
+            }
+            frontier = nextFrontier;
+        }
+        // 4. Build the full tree: ancestors → focus → descendants
+        let root = focusNode;
+        for (const ancestor of [...ancestors].reverse()) {
+            root = {
+                key: ancestor.key,
+                summary: ancestor.summary,
+                issueType: ancestor.issueType,
+                status: ancestor.status,
+                children: [root],
+            };
+        }
+        // 5. Expand sibling children for ancestor nodes (batched single call)
+        if (ancestors.length > 0) {
+            // Collect all ancestor keys for a single batched fetch
+            const ancestorKeys = [];
+            let walkNode = root;
+            for (let i = 0; i < ancestors.length; i++) {
+                ancestorKeys.push(walkNode.key);
+                walkNode = walkNode.children[0];
+            }
+            const siblingResult = await this.fetchChildren(ancestorKeys);
+            if (siblingResult.truncated)
+                truncated = true;
+            // Group siblings by parent
+            const siblingsByParent = new Map();
+            for (const child of siblingResult.children) {
+                const group = siblingsByParent.get(child.parent) || [];
+                group.push(child);
+                siblingsByParent.set(child.parent, group);
+            }
+            // Distribute siblings to each ancestor node
+            let node = root;
+            for (let i = 0; i < ancestors.length; i++) {
+                const existingChildKey = node.children[0]?.key;
+                const siblings = (siblingsByParent.get(node.key) || [])
+                    .filter(c => c.key !== existingChildKey)
+                    .map(c => ({ key: c.key, summary: c.summary, issueType: c.issueType, status: c.status, children: [] }));
+                node.children = [...node.children, ...siblings];
+                node = node.children.find(c => c.key === existingChildKey) || node.children[0];
+            }
+        }
+        return {
+            root,
+            focusKey: focus.key,
+            upDepth: ancestors.length,
+            downDepth: actualDownDepth,
+            truncated,
+        };
+    }
     async getIssueAttachments(issueKey) {
         const issue = await this.client.issues.getIssue({
             issueIdOrKey: issueKey,

package/build/handlers/issue-handlers.js

@@ -13,8 +13,8 @@ function validateManageJiraIssueArgs(args) {
     const normalizedArgs = normalizeArgs(args);
     // Validate operation parameter
     if (typeof normalizedArgs.operation !== 'string' ||
-        !['create', 'get', 'update', 'delete', 'move', 'transition', 'comment', 'link'].includes(normalizedArgs.operation)) {
-        throw new McpError(ErrorCode.InvalidParams, 'Invalid operation parameter. Valid values are: create, get, update, delete, move, transition, comment, link');
+        !['create', 'get', 'update', 'delete', 'move', 'transition', 'comment', 'link', 'hierarchy'].includes(normalizedArgs.operation)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid operation parameter. Valid values are: create, get, update, delete, move, transition, comment, link, hierarchy');
     }
     // Validate parameters based on operation
     switch (normalizedArgs.operation) {
@@ -92,6 +92,11 @@ function validateManageJiraIssueArgs(args) {
                 throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid linkType parameter. Please provide a valid link type for the link operation.');
             }
             break;
+        case 'hierarchy':
+            if (typeof normalizedArgs.issueKey !== 'string' || normalizedArgs.issueKey.trim() === '') {
+                throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid issueKey parameter. Please provide a valid issue key for the hierarchy operation.');
+            }
+            break;
     }
     // Validate expand parameter
     if (normalizedArgs.expand !== undefined) {
@@ -332,6 +337,34 @@ async function handleLinkIssue(jiraClient, args) {
         ],
     };
 }
+function renderHierarchyTree(node, focusKey, prefix = '', isLast = true, isRoot = true) {
+    const connector = isRoot ? '' : (isLast ? '└─ ' : '├─ ');
+    const marker = node.key === focusKey ? '  ← you are here' : '';
+    const line = `${prefix}${connector}**${node.key}** ${node.issueType}: ${node.summary} [${node.status}]${marker}`;
+    const childPrefix = isRoot ? '' : (prefix + (isLast ? '   ' : '│  '));
+    const childLines = node.children.map((child, i) => renderHierarchyTree(child, focusKey, childPrefix, i === node.children.length - 1, false));
+    return [line, ...childLines].join('\n');
+}
+async function handleHierarchy(jiraClient, args) {
+    const up = Math.min(Math.max(args.up ?? 4, 0), 8);
+    const down = Math.min(Math.max(args.down ?? 4, 0), 8);
+    console.error(`Fetching hierarchy for ${args.issueKey}: up=${up}, down=${down}`);
+    const result = await jiraClient.getHierarchy(args.issueKey, up, down);
+    const tree = renderHierarchyTree(result.root, result.focusKey);
+    const lines = [
+        `# Issue Hierarchy: ${result.focusKey}`,
+        '',
+        `Traversed ${result.upDepth} level${result.upDepth !== 1 ? 's' : ''} up, ${result.downDepth} level${result.downDepth !== 1 ? 's' : ''} down`,
+    ];
+    if (result.truncated) {
+        lines.push('', '⚠️ Results were truncated — some children may not be shown. Narrow the scope with smaller `up`/`down` values or focus on a specific subtree.');
+    }
+    lines.push('', tree);
+    const summary = lines.join('\n');
+    return {
+        content: [{ type: 'text', text: summary + issueGuidance('hierarchy', args.issueKey) }],
+    };
+}
 // Main handler function
 export async function handleIssueRequest(jiraClient, request) {
     console.error('Handling issue request...');
@@ -382,6 +415,10 @@ export async function handleIssueRequest(jiraClient, request) {
                 console.error('Processing link issue operation');
                 return await handleLinkIssue(jiraClient, normalizedArgs);
             }
+            case 'hierarchy': {
+                console.error('Processing hierarchy operation');
+                return await handleHierarchy(jiraClient, normalizedArgs);
+            }
             default: {
                 console.error(`Unknown operation: ${normalizedArgs.operation}`);
                 throw new McpError(ErrorCode.MethodNotFound, `Unknown operation: ${normalizedArgs.operation}`);

package/build/handlers/queue-handler.js

@@ -20,6 +20,7 @@ export function createQueueHandler(handlers, jiraHost) {
             throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: operations (array)');
         }
         const operations = args.operations;
+        const detail = args.detail === 'full' ? 'full' : 'summary';
         if (operations.length === 0) {
             throw new McpError(ErrorCode.InvalidParams, 'Operations list is empty.');
         }
@@ -100,7 +101,7 @@ export function createQueueHandler(handlers, jiraHost) {
             }
         }
         return {
-            content: [{ type: 'text', text: formatResults(results, operations.length, bailedAt) }],
+            content: [{ type: 'text', text: formatResults(results, operations.length, bailedAt, detail) }],
         };
     };
 }
@@ -222,8 +223,8 @@ function firstLine(text) {
     }
     return stripped.slice(0, 100);
 }
-/** Format the queue results into a compact response */
-function formatResults(results, total, bailedAt) {
+/** Format the queue results */
+function formatResults(results, total, bailedAt, detail = 'summary') {
     const success = results.filter(r => r.status === 'success').length;
     const errors = results.filter(r => r.status === 'error').length;
     const skipped = results.filter(r => r.status === 'skipped').length;
@@ -233,11 +234,29 @@ function formatResults(results, total, bailedAt) {
     if (bailedAt >= 0) {
         lines.push(`Stopped at operation ${bailedAt + 1} due to error.`);
     }
-    lines.push('');
-    for (const r of results) {
-        const icon = r.status === 'success' ? 'ok' : r.status === 'error' ? 'ERR' : 'SKIP';
-        const summary = r.status === 'skipped' ? r.text : firstLine(r.text);
-        lines.push(`  [${r.index + 1}] ${icon}: ${summary}`);
+    if (detail === 'full') {
+        for (const r of results) {
+            const icon = r.status === 'success' ? 'ok' : r.status === 'error' ? 'ERR' : 'SKIP';
+            lines.push('');
+            lines.push(`---`);
+            lines.push(`**[${r.index + 1}] ${icon}**`);
+            if (r.status === 'skipped') {
+                lines.push(r.text);
+            }
+            else {
+                lines.push(stripNextSteps(r.text));
+            }
+        }
+    }
+    else {
+        lines.push('');
+        for (const r of results) {
+            const icon = r.status === 'success' ? 'ok' : r.status === 'error' ? 'ERR' : 'SKIP';
+            const summary = r.status === 'skipped' ? r.text : firstLine(r.text);
+            lines.push(`  [${r.index + 1}] ${icon}: ${summary}`);
+        }
+        lines.push('');
+        lines.push('_Use `detail: "full"` for complete output from each operation._');
     }
     // Consolidated next-step: use the last successful operation's context
     const lastSuccess = [...results].reverse().find(r => r.status === 'success');

package/build/index.js

@@ -18,7 +18,14 @@ const JIRA_EMAIL = process.env.JIRA_EMAIL;
 const JIRA_API_TOKEN = process.env.JIRA_API_TOKEN;
 const JIRA_HOST = process.env.JIRA_HOST;
 if (!JIRA_EMAIL || !JIRA_API_TOKEN || !JIRA_HOST) {
-    throw new Error('Missing required Jira credentials in environment variables');
+    const missing = [
+        !JIRA_API_TOKEN && 'JIRA_API_TOKEN',
+        !JIRA_EMAIL && 'JIRA_EMAIL',
+        !JIRA_HOST && 'JIRA_HOST',
+    ].filter(Boolean).join(', ');
+    console.error(`[jira-cloud] Missing required environment variables: ${missing}`);
+    console.error('[jira-cloud] Set these in your MCP configuration or MCPB extension settings.');
+    process.exit(1);
 }
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');

package/build/schemas/tool-schemas.js

@@ -142,13 +142,13 @@ export const toolSchemas = {
     },
     manage_jira_issue: {
         name: 'manage_jira_issue',
-        description: 'Get, create, update, delete, move, transition, comment on, or link Jira issues',
+        description: 'Get, create, update, delete, move, transition, comment on, link, or explore hierarchy of Jira issues',
         inputSchema: {
             type: 'object',
             properties: {
                 operation: {
                     type: 'string',
-                    enum: ['create', 'get', 'update', 'delete', 'move', 'transition', 'comment', 'link'],
+                    enum: ['create', 'get', 'update', 'delete', 'move', 'transition', 'comment', 'link', 'hierarchy'],
                     description: 'Operation to perform',
                 },
                 issueKey: {
@@ -216,6 +216,14 @@ export const toolSchemas = {
                     type: 'string',
                     description: 'Target issue type for move (e.g., Story, Bug). Required for move.',
                 },
+                up: {
+                    type: 'number',
+                    description: 'Hierarchy: how many levels up to traverse (default 4, max 8).',
+                },
+                down: {
+                    type: 'number',
+                    description: 'Hierarchy: how many levels down to traverse (default 4, max 8).',
+                },
                 expand: {
                     type: 'array',
                     items: {
@@ -344,6 +352,12 @@ export const toolSchemas = {
                     description: 'Ordered list of operations to execute (max 10).',
                     maxItems: 10,
                 },
+                detail: {
+                    type: 'string',
+                    enum: ['full', 'summary'],
+                    description: 'Result detail level. summary (default): one-line status per operation. full: complete output matching individual tool calls. Use full when summary lacks needed detail.',
+                    default: 'summary',
+                },
             },
             required: ['operations'],
         },

package/build/utils/next-steps.js

@@ -38,6 +38,9 @@ export function issueNextSteps(operation, issueKey) {
         case 'link':
             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]}"` } });
+            break;
     }
     return steps.length > 0 ? formatSteps(steps) : '';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaronsb/jira-cloud-mcp",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "mcpName": "io.github.aaronsb/jira-cloud",
   "description": "Model Context Protocol (MCP) server for Jira Cloud - enables AI assistants to interact with Jira",
   "type": "module",
@@ -46,7 +46,7 @@
     "update-doc-timestamps": "node scripts/update-doc-timestamps.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.24.3",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "jira.js": "5.3.1",
     "jsdom": "^27.3.0",
     "markdown-it": "^14.1.0"