@aaronsb/jira-cloud-mcp 0.7.2 → 0.8.0

package/build/client/jira-client.js

@@ -94,6 +94,8 @@ export class JiraClient {
             this.customFields.startDate,
             this.customFields.storyPoints,
             'timeestimate',
+            'timeoriginalestimate',
+            'timespent',
             ...(this.customFields.sprint ? [this.customFields.sprint] : []),
             'issuelinks',
         ];
@@ -147,6 +149,8 @@ export class JiraClient {
             startDate: fields?.[this.customFields.startDate] || null,
             storyPoints: fields?.[this.customFields.storyPoints] ?? null,
             timeEstimate: fields?.timeestimate ?? null,
+            originalEstimate: fields?.timeoriginalestimate ?? null,
+            timeSpent: fields?.timespent ?? null,
             sprint: this.customFields.sprint ? this.extractSprintName(fields?.[this.customFields.sprint]) : null,
             issueLinks: (fields?.issuelinks || []).map((link) => ({
                 type: link.type?.name || '',
@@ -502,6 +506,12 @@ export class JiraClient {
             fields.labels = params.labels;
         if (params.dueDate !== undefined)
             fields.duedate = params.dueDate;
+        if (params.originalEstimate || params.remainingEstimate) {
+            fields.timetracking = {
+                ...(params.originalEstimate ? { originalEstimate: params.originalEstimate } : {}),
+                ...(params.remainingEstimate ? { remainingEstimate: params.remainingEstimate } : {}),
+            };
+        }
         if (params.customFields) {
             Object.assign(fields, this.convertAdfFields(params.customFields));
         }
@@ -510,6 +520,17 @@ export class JiraClient {
             fields,
         });
     }
+    async addWorklog(params) {
+        await this.client.issueWorklogs.addWorklog({
+            issueIdOrKey: params.issueKey,
+            timeSpent: params.timeSpent,
+            comment: params.comment,
+            started: params.started,
+            adjustEstimate: params.adjustEstimate ?? 'auto',
+            newEstimate: params.newEstimate,
+            reduceBy: params.reduceBy,
+        });
+    }
     async addComment(issueKey, commentBody) {
         await this.client.issueComments.addComment({
             issueIdOrKey: issueKey,
@@ -536,7 +557,8 @@ export class JiraClient {
             const leanFields = [
                 'summary', 'issuetype', 'priority', 'assignee', 'reporter',
                 'status', 'resolution', 'labels', 'created', 'updated',
-                'resolutiondate', 'statuscategorychangedate', 'duedate', 'timeestimate',
+                'resolutiondate', 'statuscategorychangedate', 'duedate',
+                'timeestimate', 'timeoriginalestimate', 'timespent',
                 this.customFields.startDate, this.customFields.storyPoints,
                 ...(this.customFields.sprint ? [this.customFields.sprint] : []),
             ];
@@ -1057,6 +1079,9 @@ export class JiraClient {
             fields.labels = params.labels;
         if (params.dueDate)
             fields.duedate = params.dueDate;
+        if (params.originalEstimate) {
+            fields.timetracking = { originalEstimate: params.originalEstimate };
+        }
         if (params.customFields) {
             Object.assign(fields, this.convertAdfFields(params.customFields));
         }

package/build/docs/tool-documentation.js

@@ -68,18 +68,34 @@ function generateIssueToolDocumentation(schema) {
             update: {
                 description: "Updates an existing issue",
                 required_parameters: ["issueKey"],
-                optional_parameters: ["summary", "description", "assignee", "priority", "labels", "customFields"],
+                optional_parameters: ["summary", "description", "assignee", "priority", "labels", "originalEstimate", "remainingEstimate", "customFields"],
                 examples: [
                     {
                         description: "Update issue summary",
                         code: { operation: "update", issueKey: "PROJ-123", summary: "Updated feature request" }
                     },
                     {
-                        description: "Add worklog to issue",
-                        code: {
-                            operation: "update", issueKey: "PROJ-123",
-                            customFields: { "worklog": { "timeSpent": "3h 30m", "comment": "Implemented feature X", "started": "2025-04-09T09:00:00.000Z" } }
-                        }
+                        description: "Set time estimate on an issue",
+                        code: { operation: "update", issueKey: "PROJ-123", originalEstimate: "3d", remainingEstimate: "2d" }
+                    }
+                ]
+            },
+            worklog: {
+                description: "Logs time spent on an issue",
+                required_parameters: ["issueKey", "timeSpent"],
+                optional_parameters: ["worklogComment", "started", "adjustEstimate", "newEstimate", "reduceBy"],
+                examples: [
+                    {
+                        description: "Log 3.5 hours of work",
+                        code: { operation: "worklog", issueKey: "PROJ-123", timeSpent: "3h 30m", worklogComment: "Implemented feature X" }
+                    },
+                    {
+                        description: "Log work with specific start time",
+                        code: { operation: "worklog", issueKey: "PROJ-123", timeSpent: "1d", started: "2025-04-09T09:00:00.000+0000", worklogComment: "Design review" }
+                    },
+                    {
+                        description: "Log work without adjusting estimate",
+                        code: { operation: "worklog", issueKey: "PROJ-123", timeSpent: "2h", adjustEstimate: "leave" }
                     }
                 ]
             },
@@ -122,11 +138,13 @@ function generateIssueToolDocumentation(schema) {
         },
         common_use_cases: [
             {
-                title: "Tracking work logs",
-                description: "To track time spent on issues:",
+                title: "Time tracking",
+                description: "To estimate and log time on issues:",
                 steps: [
-                    { description: "Add a work log to an issue", code: { operation: "update", issueKey: "PROJ-123", customFields: { "worklog": { "timeSpent": "3h 30m", "comment": "Implemented feature X", "started": "2025-04-09T09:00:00.000Z" } } } },
-                    { description: "View work logs for an issue", code: { operation: "get", issueKey: "PROJ-123", expand: ["worklog"] } }
+                    { description: "Set an estimate when creating", code: { operation: "create", projectKey: "PROJ", summary: "New task", issueType: "Task", originalEstimate: "3d" } },
+                    { description: "Update the estimate", code: { operation: "update", issueKey: "PROJ-123", originalEstimate: "5d", remainingEstimate: "3d" } },
+                    { description: "Log time spent", code: { operation: "worklog", issueKey: "PROJ-123", timeSpent: "3h 30m", worklogComment: "Implemented feature X" } },
+                    { description: "View time tracking on an issue", code: { operation: "get", issueKey: "PROJ-123" } }
                 ]
             },
             {

package/build/handlers/analysis-handler.js

@@ -1,6 +1,7 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { GraphQLHierarchyWalker, walkTree } from '../client/graphql-hierarchy.js';
 import { renderRollupTree } from '../handlers/plan-handler.js';
+import { formatDuration } from '../mcp/markdown-renderer.js';
 import { evaluateRow, extractColumnRefs, parseComputeList } from '../utils/cube-dsl.js';
 import { analysisNextSteps } from '../utils/next-steps.js';
 import { normalizeArgs } from '../utils/normalize-args.js';
@@ -39,18 +40,6 @@ function formatDateShort(date) {
 function daysBetween(a, b) {
     return Math.round((b.getTime() - a.getTime()) / (1000 * 60 * 60 * 24));
 }
-function formatDuration(seconds) {
-    const hours = Math.floor(seconds / 3600);
-    const days = Math.floor(hours / 8); // 8-hour work day
-    if (days > 0) {
-        const remainingHours = hours % 8;
-        return remainingHours > 0 ? `${days}d ${remainingHours}h` : `${days}d`;
-    }
-    const minutes = Math.floor((seconds % 3600) / 60);
-    if (hours > 0)
-        return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
-    return `${minutes}m`;
-}
 function countBy(items, keyFn) {
     const counts = new Map();
     for (const item of items) {
@@ -114,22 +103,26 @@ export function renderPoints(issues) {
     return lines.join('\n');
 }
 export function renderTime(issues) {
-    const estimated = issues.filter(i => i.timeEstimate != null);
-    const unestimated = issues.length - estimated.length;
-    const total = sumBy(issues, i => i.timeEstimate);
-    const byBucket = new Map();
-    for (const issue of issues) {
-        const bucket = bucketStatus(issue.statusCategory);
-        byBucket.set(bucket, (byBucket.get(bucket) ?? 0) + (issue.timeEstimate ?? 0));
-    }
-    const done = byBucket.get('Done') ?? 0;
-    const remaining = total - done;
+    const hasOriginal = issues.some(i => i.originalEstimate != null);
+    const hasLogged = issues.some(i => i.timeSpent != null);
+    const hasRemaining = issues.some(i => i.timeEstimate != null);
+    const originalTotal = sumBy(issues, i => i.originalEstimate);
+    const loggedTotal = sumBy(issues, i => i.timeSpent);
+    const remainingTotal = sumBy(issues, i => i.timeEstimate);
+    const unestimated = issues.filter(i => i.originalEstimate == null && i.timeEstimate == null).length;
     const lines = ['## Time (Effort)', ''];
     lines.push('| Metric | Value |');
     lines.push('|--------|-------|');
-    lines.push(`| Original Estimate | ${formatDuration(total)} |`);
-    lines.push(`| Completed | ${formatDuration(done)} |`);
-    lines.push(`| Remaining | ${formatDuration(remaining)} |`);
+    if (hasOriginal)
+        lines.push(`| Original Estimate | ${formatDuration(originalTotal)} |`);
+    if (hasLogged)
+        lines.push(`| Logged | ${formatDuration(loggedTotal)} |`);
+    if (hasRemaining)
+        lines.push(`| Remaining | ${formatDuration(remainingTotal)} |`);
+    if (hasOriginal && hasLogged && originalTotal > 0) {
+        const pct = Math.round((loggedTotal / originalTotal) * 100);
+        lines.push(`| Effort Used | ${pct}% |`);
+    }
     if (unestimated > 0) {
         lines.push(`| Unestimated | ${unestimated} issue${unestimated !== 1 ? 's' : ''} |`);
     }
@@ -779,6 +772,8 @@ function graphIssueToDetails(issue) {
         storyPoints: issue.storyPoints,
         sprint: null,
         timeEstimate: null,
+        originalEstimate: null,
+        timeSpent: null,
         issueLinks: [],
     };
 }

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', 'hierarchy'].includes(normalizedArgs.operation)) {
-        throw new McpError(ErrorCode.InvalidParams, 'Invalid operation parameter. Valid values are: create, get, update, delete, move, transition, comment, link, hierarchy');
+        !['create', 'get', 'update', 'delete', 'move', 'transition', 'comment', 'link', 'hierarchy', 'worklog'].includes(normalizedArgs.operation)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid operation parameter. Valid values are: create, get, update, delete, move, transition, comment, link, hierarchy, worklog');
     }
     // Validate parameters based on operation
     switch (normalizedArgs.operation) {
@@ -62,8 +62,10 @@ function validateManageJiraIssueArgs(args) {
                 normalizedArgs.priority === undefined &&
                 normalizedArgs.labels === undefined &&
                 normalizedArgs.dueDate === undefined &&
+                normalizedArgs.originalEstimate === undefined &&
+                normalizedArgs.remainingEstimate === undefined &&
                 normalizedArgs.customFields === undefined) {
-                throw new McpError(ErrorCode.InvalidParams, 'At least one update field (summary, description, parent, assignee, priority, labels, dueDate, or customFields) must be provided for the update operation.');
+                throw new McpError(ErrorCode.InvalidParams, 'At least one update field (summary, description, parent, assignee, priority, labels, dueDate, originalEstimate, remainingEstimate, or customFields) must be provided for the update operation.');
             }
             break;
         case 'transition':
@@ -93,6 +95,20 @@ 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 'worklog':
+            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 worklog operation.');
+            }
+            if (typeof normalizedArgs.timeSpent !== 'string' || normalizedArgs.timeSpent.trim() === '') {
+                throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid timeSpent parameter. Provide time in Jira format (e.g., "3h 30m", "1d", "2w").');
+            }
+            if (normalizedArgs.adjustEstimate === 'new' && !normalizedArgs.newEstimate) {
+                throw new McpError(ErrorCode.InvalidParams, 'newEstimate is required when adjustEstimate is "new" (e.g., "2d").');
+            }
+            if (normalizedArgs.adjustEstimate === 'manual' && !normalizedArgs.reduceBy) {
+                throw new McpError(ErrorCode.InvalidParams, 'reduceBy is required when adjustEstimate is "manual" (e.g., "1h").');
+            }
+            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.');
@@ -258,6 +274,7 @@ async function handleCreateIssue(jiraClient, args) {
         assignee: args.assignee,
         labels: args.labels,
         dueDate: args.dueDate ?? undefined,
+        originalEstimate: args.originalEstimate,
         customFields,
     });
     // Get the created issue and render to markdown
@@ -283,6 +300,8 @@ async function handleUpdateIssue(jiraClient, args) {
         priority: args.priority,
         labels: args.labels,
         dueDate: args.dueDate,
+        originalEstimate: args.originalEstimate,
+        remainingEstimate: args.remainingEstimate,
         customFields,
     });
     // Get the updated issue and render to markdown
@@ -341,6 +360,28 @@ async function handleLinkIssue(jiraClient, args) {
         ],
     };
 }
+async function handleWorklogIssue(jiraClient, args) {
+    await jiraClient.addWorklog({
+        issueKey: args.issueKey,
+        timeSpent: args.timeSpent,
+        comment: args.worklogComment,
+        started: args.started,
+        adjustEstimate: args.adjustEstimate,
+        newEstimate: args.newEstimate,
+        reduceBy: args.reduceBy,
+    });
+    // Get the updated issue and render to markdown
+    const updatedIssue = await jiraClient.getIssue(args.issueKey, false, false);
+    const markdown = MarkdownRenderer.renderIssue(updatedIssue);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `# Worklog Added\n\nLogged ${args.timeSpent} on ${args.issueKey}\n\n${markdown}${issueGuidance('worklog', args.issueKey)}`,
+            },
+        ],
+    };
+}
 function renderHierarchyTree(node, focusKey, prefix = '', isLast = true, isRoot = true) {
     const connector = isRoot ? '' : (isLast ? '└─ ' : '├─ ');
     const marker = node.key === focusKey ? '  ← you are here' : '';
@@ -419,6 +460,10 @@ export async function handleIssueRequest(jiraClient, request) {
                 console.error('Processing link issue operation');
                 return await handleLinkIssue(jiraClient, normalizedArgs);
             }
+            case 'worklog': {
+                console.error('Processing worklog operation');
+                return await handleWorklogIssue(jiraClient, normalizedArgs);
+            }
             case 'hierarchy': {
                 console.error('Processing hierarchy operation');
                 return await handleHierarchy(jiraClient, normalizedArgs);

package/build/mcp/markdown-renderer.js

@@ -32,6 +32,22 @@ function formatDate(dateStr) {
     const date = new Date(dateStr);
     return date.toLocaleDateString('en-US', { year: 'numeric', month: 'short', day: 'numeric' });
 }
+/** Format seconds into human-readable duration (e.g. 1d 2h, 3h 30m) */
+export function formatDuration(seconds) {
+    if (seconds === 0)
+        return '0m';
+    const days = Math.floor(seconds / 28800); // 8h workday
+    const hours = Math.floor((seconds % 28800) / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const parts = [];
+    if (days > 0)
+        parts.push(`${days}d`);
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0)
+        parts.push(`${minutes}m`);
+    return parts.length > 0 ? parts.join(' ') : '0m';
+}
 /**
  * Format status with visual indicator
  */
@@ -110,16 +126,16 @@ export function renderIssue(issue, transitions) {
         lines.push(dates.join(' | '));
     if (issue.storyPoints)
         lines.push(`Points: ${issue.storyPoints}`);
-    if (issue.timeEstimate) {
-        const hours = Math.floor(issue.timeEstimate / 3600);
-        const minutes = Math.floor((issue.timeEstimate % 3600) / 60);
-        const parts = [];
-        if (hours > 0)
-            parts.push(`${hours}h`);
-        if (minutes > 0)
-            parts.push(`${minutes}m`);
-        lines.push(`Estimate: ${parts.length > 0 ? parts.join(' ') : '0m'}`);
-    }
+    // Time tracking — consolidated line
+    const timeParts = [];
+    if (issue.originalEstimate != null)
+        timeParts.push(`Estimate: ${formatDuration(issue.originalEstimate)}`);
+    if (issue.timeEstimate != null)
+        timeParts.push(`Remaining: ${formatDuration(issue.timeEstimate)}`);
+    if (issue.timeSpent != null)
+        timeParts.push(`Logged: ${formatDuration(issue.timeSpent)}`);
+    if (timeParts.length > 0)
+        lines.push(timeParts.join(' | '));
     if (issue.resolution)
         lines.push(`Resolution: ${issue.resolution}`);
     // Description — already markdown from ADF conversion

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, link, or explore hierarchy of Jira issues',
+        description: 'Get, create, update, delete, move, transition, comment on, link, log work on, or explore hierarchy of Jira issues',
         inputSchema: {
             type: 'object',
             properties: {
                 operation: {
                     type: 'string',
-                    enum: ['create', 'get', 'update', 'delete', 'move', 'transition', 'comment', 'link', 'hierarchy'],
+                    enum: ['create', 'get', 'update', 'delete', 'move', 'transition', 'comment', 'link', 'hierarchy', 'worklog'],
                     description: 'Operation to perform',
                 },
                 issueKey: {
@@ -192,6 +192,39 @@ export const toolSchemas = {
                     type: ['string', 'null'],
                     description: 'Due date in ISO format (e.g., "2025-06-15") or null to clear. For create and update.',
                 },
+                originalEstimate: {
+                    type: 'string',
+                    description: 'Original time estimate in Jira format (e.g., "3d", "2h 30m", "1w"). For create and update.',
+                },
+                remainingEstimate: {
+                    type: 'string',
+                    description: 'Remaining time estimate in Jira format (e.g., "1d", "4h"). For update only.',
+                },
+                timeSpent: {
+                    type: 'string',
+                    description: 'Time spent in Jira format (e.g., "3h 30m", "1d", "2w"). Required for worklog.',
+                },
+                worklogComment: {
+                    type: 'string',
+                    description: 'Description of work performed. For worklog.',
+                },
+                started: {
+                    type: 'string',
+                    description: 'When the work started, ISO datetime (e.g., "2025-04-09T09:00:00.000+0000"). Defaults to now. For worklog.',
+                },
+                adjustEstimate: {
+                    type: 'string',
+                    enum: ['auto', 'leave', 'new', 'manual'],
+                    description: 'How to adjust the remaining estimate: auto (reduce by timeSpent), leave (unchanged), new (set to newEstimate), manual (reduce by reduceBy). Default: auto. For worklog.',
+                },
+                newEstimate: {
+                    type: 'string',
+                    description: 'New remaining estimate when adjustEstimate is "new" (e.g., "2d"). For worklog.',
+                },
+                reduceBy: {
+                    type: 'string',
+                    description: 'Amount to reduce remaining estimate when adjustEstimate is "manual" (e.g., "1h"). For worklog.',
+                },
                 parent: {
                     type: ['string', 'null'],
                     description: 'Parent issue key (e.g., PROJ-100) or null to remove.',

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 'worklog':
+            steps.push({ description: 'View the updated issue', tool: 'manage_jira_issue', example: { operation: 'get', issueKey } }, { description: 'Log more time', tool: 'manage_jira_issue', example: { operation: 'worklog', issueKey, timeSpent: '<duration>' } }, { description: 'Adjust the remaining estimate', tool: 'manage_jira_issue', example: { operation: 'update', issueKey, remainingEstimate: '<duration>' } });
+            break;
         case 'hierarchy':
             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;

package/package.json

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

package/build/handlers/search-handlers.js

@@ -1,103 +0,0 @@
-import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { MarkdownRenderer } from '../mcp/markdown-renderer.js';
-// Helper function to normalize parameter names (support both snake_case and camelCase)
-function normalizeArgs(args) {
-    const normalized = {};
-    for (const [key, value] of Object.entries(args)) {
-        // Convert snake_case to camelCase
-        if (key === 'start_at') {
-            normalized['startAt'] = value;
-        }
-        else if (key === 'max_results') {
-            normalized['maxResults'] = value;
-        }
-        else if (key === 'filter_id') {
-            normalized['filterId'] = value;
-        }
-        else {
-            normalized[key] = value;
-        }
-    }
-    return normalized;
-}
-function isSearchIssuesArgs(args) {
-    if (typeof args !== 'object' || args === null) {
-        throw new McpError(ErrorCode.InvalidParams, `Invalid search_jira_issues arguments: Expected an object with a jql parameter. Example: { "jql": "project = PROJ" }`);
-    }
-    const typedArgs = args;
-    if (typeof typedArgs.jql !== 'string') {
-        throw new McpError(ErrorCode.InvalidParams, `Missing or invalid jql parameter. Please provide a valid JQL query string. Example: { "jql": "project = PROJ" }`);
-    }
-    // Validate startAt if present
-    if (typedArgs.startAt !== undefined && typeof typedArgs.startAt !== 'number') {
-        throw new McpError(ErrorCode.InvalidParams, 'Invalid startAt parameter. Expected a number.');
-    }
-    // Validate maxResults if present
-    if (typedArgs.maxResults !== undefined && typeof typedArgs.maxResults !== 'number') {
-        throw new McpError(ErrorCode.InvalidParams, 'Invalid maxResults parameter. Expected a number.');
-    }
-    // Validate expand parameter if present
-    if (typedArgs.expand !== undefined) {
-        if (!Array.isArray(typedArgs.expand)) {
-            throw new McpError(ErrorCode.InvalidParams, 'Invalid expand parameter. Expected an array of strings.');
-        }
-        const validExpansions = ['issue_details', 'transitions', 'comments_preview'];
-        for (const expansion of typedArgs.expand) {
-            if (typeof expansion !== 'string' || !validExpansions.includes(expansion)) {
-                throw new McpError(ErrorCode.InvalidParams, `Invalid expansion: ${expansion}. Valid expansions are: ${validExpansions.join(', ')}`);
-            }
-        }
-    }
-    return true;
-}
-export async function setupSearchHandlers(server, jiraClient, request) {
-    console.error('Handling search request...');
-    const { name } = request.params;
-    const args = request.params.arguments;
-    if (!args) {
-        throw new McpError(ErrorCode.InvalidParams, 'Missing arguments');
-    }
-    // Normalize arguments to support both snake_case and camelCase
-    const normalizedArgs = normalizeArgs(args);
-    switch (name) {
-        case 'search_jira_issues': {
-            console.error('Processing search_jira_issues request');
-            if (!isSearchIssuesArgs(normalizedArgs)) {
-                throw new McpError(ErrorCode.InvalidParams, 'Invalid search_jira_issues arguments');
-            }
-            try {
-                console.error(`Executing search with args:`, JSON.stringify(normalizedArgs, null, 2));
-                // Parse expansion options (reserved for future use)
-                const _expansionOptions = {};
-                if (normalizedArgs.expand) {
-                    for (const expansion of normalizedArgs.expand) {
-                        _expansionOptions[expansion] = true;
-                    }
-                }
-                // Execute the search
-                const searchResult = await jiraClient.searchIssues(normalizedArgs.jql, normalizedArgs.startAt, normalizedArgs.maxResults);
-                // Render to markdown for token efficiency
-                const markdown = MarkdownRenderer.renderIssueSearchResults(searchResult.issues, searchResult.pagination, normalizedArgs.jql);
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: markdown,
-                        },
-                    ],
-                };
-            }
-            catch (error) {
-                console.error('Error in search_jira_issues:', error);
-                if (error instanceof Error) {
-                    throw new McpError(ErrorCode.InvalidRequest, `Jira API error: ${error.message}`);
-                }
-                throw new McpError(ErrorCode.InvalidRequest, 'Failed to execute Jira search');
-            }
-        }
-        default: {
-            console.error(`Unknown tool requested: ${name}`);
-            throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
-        }
-    }
-}

package/build/schemas/request-schemas.js

@@ -1,187 +0,0 @@
-import { z } from 'zod';
-// Sprint Management Schemas
-export const CreateJiraSprintSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('create_jira_sprint'),
-        arguments: z.object({
-            boardId: z.number(),
-            name: z.string(),
-            startDate: z.string().optional(),
-            endDate: z.string().optional(),
-            goal: z.string().optional(),
-        }),
-    }),
-});
-export const GetJiraSprintSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('get_jira_sprint'),
-        arguments: z.object({
-            sprintId: z.number(),
-            expand: z.array(z.string()).optional(),
-        }),
-    }),
-});
-export const ListJiraSprintsSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('list_jira_sprints'),
-        arguments: z.object({
-            boardId: z.number(),
-            state: z.enum(['future', 'active', 'closed']).optional(),
-            startAt: z.number().optional(),
-            maxResults: z.number().optional(),
-            expand: z.array(z.string()).optional(),
-        }),
-    }),
-});
-export const UpdateJiraSprintSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('update_jira_sprint'),
-        arguments: z.object({
-            sprintId: z.number(),
-            name: z.string().optional(),
-            goal: z.string().optional(),
-            startDate: z.string().optional(),
-            endDate: z.string().optional(),
-            state: z.enum(['future', 'active', 'closed']).optional(),
-        }),
-    }),
-});
-export const DeleteJiraSprintSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('delete_jira_sprint'),
-        arguments: z.object({
-            sprintId: z.number(),
-        }),
-    }),
-});
-export const UpdateSprintIssuesSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('update_sprint_issues'),
-        arguments: z.object({
-            sprintId: z.number(),
-            add: z.array(z.string()).optional(),
-            remove: z.array(z.string()).optional(),
-        }),
-    }),
-});
-// Consolidated API request schemas
-export const GetJiraIssueSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('get_jira_issue'),
-        arguments: z.object({
-            issueKey: z.string(),
-            expand: z.array(z.string()).optional(),
-        }),
-    }),
-});
-export const GetJiraProjectSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('get_jira_project'),
-        arguments: z.object({
-            projectKey: z.string(),
-            expand: z.array(z.string()).optional(),
-            include_status_counts: z.boolean().optional(),
-        }),
-    }),
-});
-export const GetJiraBoardSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('get_jira_board'),
-        arguments: z.object({
-            boardId: z.number(),
-            expand: z.array(z.string()).optional(),
-        }),
-    }),
-});
-export const SearchJiraIssuesSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('search_jira_issues'),
-        arguments: z.object({
-            jql: z.string(),
-            startAt: z.number().optional(),
-            maxResults: z.number().optional(),
-            expand: z.array(z.string()).optional(),
-        }),
-    }),
-});
-export const ListJiraProjectsSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('list_jira_projects'),
-        arguments: z.object({
-            include_status_counts: z.boolean().optional(),
-        }),
-    }),
-});
-export const ListJiraBoardsSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('list_jira_boards'),
-        arguments: z.object({
-            include_sprints: z.boolean().optional(),
-        }),
-    }),
-});
-export const CreateJiraIssueSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('create_jira_issue'),
-        arguments: z.object({
-            projectKey: z.string(),
-            summary: z.string(),
-            description: z.string().optional(),
-            issueType: z.string(),
-            priority: z.string().optional(),
-            assignee: z.string().optional(),
-            labels: z.array(z.string()).optional(),
-            customFields: z.record(z.any()).optional(),
-        }),
-    }),
-});
-export const UpdateJiraIssueSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('update_jira_issue'),
-        arguments: z.object({
-            issueKey: z.string(),
-            summary: z.string().optional(),
-            description: z.string().optional(),
-            parent: z.union([z.string(), z.null()]).optional(),
-            assignee: z.string().optional(),
-            priority: z.string().optional(),
-            labels: z.array(z.string()).optional(),
-            customFields: z.record(z.any()).optional(),
-        }),
-    }),
-});
-export const TransitionJiraIssueSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('transition_jira_issue'),
-        arguments: z.object({
-            issueKey: z.string(),
-            transitionId: z.string(),
-            comment: z.string().optional(),
-        }),
-    }),
-});
-export const AddJiraCommentSchema = z.object({
-    method: z.literal('tools/call'),
-    params: z.object({
-        name: z.literal('add_jira_comment'),
-        arguments: z.object({
-            issueKey: z.string(),
-            body: z.string(),
-        }),
-    }),
-});

package/build/utils/formatters/base-formatter.js

@@ -1,58 +0,0 @@
-/**
- * Base formatter for consistent response structure across all entity types
- */
-export class BaseFormatter {
-    /**
-     * Format a response with the standard structure
-     * @param data The main data for the response
-     * @param metadata Optional metadata about the response
-     * @param summary Optional summary information
-     * @returns A formatted response object
-     */
-    static formatResponse(data, metadata, summary) {
-        return {
-            data,
-            ...(metadata && { _metadata: metadata }),
-            ...(summary && { _summary: summary }),
-        };
-    }
-    /**
-     * Create metadata for a response
-     * @param options Metadata options
-     * @returns Response metadata
-     */
-    static createMetadata(options) {
-        const metadata = {};
-        if (options.expansions && options.expansions.length > 0) {
-            metadata.expansions = options.expansions;
-        }
-        if (options.related && Object.keys(options.related).length > 0) {
-            metadata.related = options.related;
-        }
-        if (options.pagination) {
-            const { startAt, maxResults, total } = options.pagination;
-            metadata.pagination = {
-                startAt,
-                maxResults,
-                total,
-                hasMore: startAt + maxResults < total,
-            };
-        }
-        return metadata;
-    }
-    /**
-     * Create a summary for a response
-     * @param options Summary options
-     * @returns Response summary
-     */
-    static createSummary(options) {
-        const summary = {};
-        if (options.status_counts && Object.keys(options.status_counts).length > 0) {
-            summary.status_counts = options.status_counts;
-        }
-        if (options.suggested_actions && options.suggested_actions.length > 0) {
-            summary.suggested_actions = options.suggested_actions;
-        }
-        return summary;
-    }
-}

package/build/utils/formatters/board-formatter.js

@@ -1,63 +0,0 @@
-import { BaseFormatter } from './base-formatter.js';
-export class BoardFormatter {
-    /**
-     * Format a board response with the standard structure and optional expansions
-     * @param board The board data
-     * @param options Expansion options
-     * @returns A formatted board response
-     */
-    static formatBoard(board, options = {}) {
-        // Create metadata with available expansions
-        const metadata = this.createBoardMetadata(board, options);
-        // Create summary
-        const summary = this.createBoardSummary(board);
-        return BaseFormatter.formatResponse(board, metadata, summary);
-    }
-    /**
-     * Create metadata for a board response
-     */
-    static createBoardMetadata(board, options) {
-        // Determine which expansions are available but not included
-        const availableExpansions = [];
-        if (!options.sprints && !board.sprints) {
-            availableExpansions.push('sprints');
-        }
-        if (!options.issues) {
-            availableExpansions.push('issues');
-        }
-        if (!options.configuration) {
-            availableExpansions.push('configuration');
-        }
-        // Create related entities map
-        const related = {};
-        if (board.location?.projectId) {
-            related.project = board.location.projectName || `Project ${board.location.projectId}`;
-        }
-        return BaseFormatter.createMetadata({
-            expansions: availableExpansions,
-            related
-        });
-    }
-    /**
-     * Create a summary for a board response
-     */
-    static createBoardSummary(board) {
-        const suggestedActions = [
-            {
-                text: `View all issues on ${board.name}`
-            }
-        ];
-        // Add sprint-related actions if sprints are available
-        if (board.sprints && board.sprints.length > 0) {
-            const activeSprints = board.sprints.filter(sprint => sprint.state === 'active');
-            if (activeSprints.length > 0) {
-                suggestedActions.push({
-                    text: `View active sprint: ${activeSprints[0].name}`
-                });
-            }
-        }
-        return BaseFormatter.createSummary({
-            suggested_actions: suggestedActions
-        });
-    }
-}

package/build/utils/formatters/filter-formatter.js

@@ -1,66 +0,0 @@
-import { BaseFormatter } from './base-formatter.js';
-export class FilterFormatter {
-    /**
-     * Format a filter response with the standard structure and optional expansions
-     * @param filter The filter data
-     * @param options Expansion options
-     * @returns A formatted filter response
-     */
-    static formatFilter(filter, options = {}) {
-        // Create metadata with available expansions
-        const metadata = this.createFilterMetadata(filter, options);
-        // Create summary
-        const summary = this.createFilterSummary(filter);
-        return BaseFormatter.formatResponse(filter, metadata, summary);
-    }
-    /**
-     * Create metadata for a filter response
-     */
-    static createFilterMetadata(filter, options) {
-        // Determine which expansions are available but not included
-        const availableExpansions = [];
-        if (!options.jql && !filter.jql) {
-            availableExpansions.push('jql');
-        }
-        if (!options.description && !filter.description) {
-            availableExpansions.push('description');
-        }
-        if (!options.permissions && !filter.sharePermissions) {
-            availableExpansions.push('permissions');
-        }
-        if (!options.issue_count && filter.issueCount === undefined) {
-            availableExpansions.push('issue_count');
-        }
-        // Create related entities map
-        const related = {
-            owner: filter.owner
-        };
-        return BaseFormatter.createMetadata({
-            expansions: availableExpansions,
-            related
-        });
-    }
-    /**
-     * Create a summary for a filter response
-     */
-    static createFilterSummary(filter) {
-        const suggestedActions = [
-            {
-                text: `View filter results: ${filter.name}`
-            }
-        ];
-        if (filter.jql) {
-            suggestedActions.push({
-                text: `Edit JQL: ${filter.name}`
-            });
-        }
-        if (!filter.favourite) {
-            suggestedActions.push({
-                text: `Add to favorites`
-            });
-        }
-        return BaseFormatter.createSummary({
-            suggested_actions: suggestedActions
-        });
-    }
-}

package/build/utils/formatters/index.js

@@ -1,7 +0,0 @@
-export * from './base-formatter.js';
-export * from './issue-formatter.js';
-export * from './project-formatter.js';
-export * from './search-formatter.js';
-export * from './board-formatter.js';
-export * from './sprint-formatter.js';
-export * from './filter-formatter.js';

package/build/utils/formatters/issue-formatter.js

@@ -1,84 +0,0 @@
-import { BaseFormatter } from './base-formatter.js';
-export class IssueFormatter {
-    /**
-     * Format an issue response with the standard structure and optional expansions
-     * @param issue The issue data
-     * @param options Expansion options
-     * @param transitions Optional transitions data (if requested)
-     * @returns A formatted issue response
-     */
-    static formatIssue(issue, options = {}, transitions) {
-        // Create metadata with available expansions
-        const metadata = this.createIssueMetadata(issue, options, transitions);
-        // Create summary with status and suggested actions
-        const summary = this.createIssueSummary(issue, transitions);
-        return BaseFormatter.formatResponse(issue, metadata, summary);
-    }
-    /**
-     * Create metadata for an issue response
-     */
-    static createIssueMetadata(issue, options, transitions) {
-        // Determine which expansions are available but not included
-        const availableExpansions = [];
-        if (!options.comments && issue.comments === undefined) {
-            availableExpansions.push('comments');
-        }
-        if (!options.transitions && transitions === undefined) {
-            availableExpansions.push('transitions');
-        }
-        if (!options.attachments && issue.attachments === undefined) {
-            availableExpansions.push('attachments');
-        }
-        if (!options.related_issues) {
-            availableExpansions.push('related_issues');
-        }
-        if (!options.history) {
-            availableExpansions.push('history');
-        }
-        // Create related entities map
-        const related = {};
-        if (issue.parent) {
-            related.parent = issue.parent;
-        }
-        // Extract related issues from issue links
-        const relatedIssues = issue.issueLinks
-            .map(link => link.outward || link.inward)
-            .filter((key) => key !== null);
-        if (relatedIssues.length > 0) {
-            related.linked_issues = relatedIssues;
-        }
-        return BaseFormatter.createMetadata({
-            expansions: availableExpansions,
-            related
-        });
-    }
-    /**
-     * Create a summary for an issue response
-     */
-    static createIssueSummary(issue, transitions) {
-        const suggestedActions = [];
-        // Add suggested actions based on available transitions
-        if (transitions && transitions.length > 0) {
-            // Common transitions to suggest
-            const commonTransitions = ['Done', 'In Progress', 'To Do', 'Closed', 'Resolved'];
-            for (const transitionName of commonTransitions) {
-                const transition = transitions.find(t => t.name === transitionName);
-                if (transition) {
-                    suggestedActions.push({
-                        text: `Move to ${transitionName}`,
-                        action_id: transition.id
-                    });
-                }
-            }
-        }
-        // Add assignment suggestion if not assigned
-        if (!issue.assignee) {
-            suggestedActions.push({
-                text: 'Assign to team member'
-            });
-        }
-        return BaseFormatter.createSummary({
-            suggested_actions: suggestedActions
-        });
-    }
-}

package/build/utils/formatters/project-formatter.js

@@ -1,55 +0,0 @@
-import { BaseFormatter } from './base-formatter.js';
-export class ProjectFormatter {
-    /**
-     * Format a project response with the standard structure and optional expansions
-     * @param project The project data
-     * @param options Expansion options
-     * @returns A formatted project response
-     */
-    static formatProject(project, options = {}) {
-        // Create metadata with available expansions
-        const metadata = this.createProjectMetadata(project, options);
-        // Create summary with status counts
-        const summary = this.createProjectSummary(project);
-        return BaseFormatter.formatResponse(project, metadata, summary);
-    }
-    /**
-     * Create metadata for a project response
-     */
-    static createProjectMetadata(project, options) {
-        // Determine which expansions are available but not included
-        const availableExpansions = [];
-        if (!options.boards) {
-            availableExpansions.push('boards');
-        }
-        if (!options.components) {
-            availableExpansions.push('components');
-        }
-        if (!options.versions) {
-            availableExpansions.push('versions');
-        }
-        if (!options.recent_issues) {
-            availableExpansions.push('recent_issues');
-        }
-        return BaseFormatter.createMetadata({
-            expansions: availableExpansions
-        });
-    }
-    /**
-     * Create a summary for a project response
-     */
-    static createProjectSummary(project) {
-        const suggestedActions = [
-            {
-                text: `View all issues in ${project.key}`
-            },
-            {
-                text: `Create issue in ${project.key}`
-            }
-        ];
-        return BaseFormatter.createSummary({
-            status_counts: project.status_counts,
-            suggested_actions: suggestedActions
-        });
-    }
-}

package/build/utils/formatters/search-formatter.js

@@ -1,62 +0,0 @@
-import { BaseFormatter } from './base-formatter.js';
-export class SearchFormatter {
-    /**
-     * Format a search response with the standard structure and optional expansions
-     * @param searchResult The search result data
-     * @param options Expansion options
-     * @returns A formatted search response
-     */
-    static formatSearchResult(searchResult, options = {}) {
-        // Create metadata with available expansions and pagination
-        const metadata = this.createSearchMetadata(searchResult, options);
-        // Create summary with status counts
-        const summary = this.createSearchSummary(searchResult);
-        return BaseFormatter.formatResponse(searchResult, metadata, summary);
-    }
-    /**
-     * Create metadata for a search response
-     */
-    static createSearchMetadata(searchResult, options) {
-        // Determine which expansions are available but not included
-        const availableExpansions = [];
-        if (!options.issue_details) {
-            availableExpansions.push('issue_details');
-        }
-        if (!options.transitions) {
-            availableExpansions.push('transitions');
-        }
-        if (!options.comments_preview) {
-            availableExpansions.push('comments_preview');
-        }
-        return BaseFormatter.createMetadata({
-            expansions: availableExpansions,
-            pagination: {
-                startAt: searchResult.pagination.startAt,
-                maxResults: searchResult.pagination.maxResults,
-                total: searchResult.pagination.total
-            }
-        });
-    }
-    /**
-     * Create a summary for a search response
-     */
-    static createSearchSummary(searchResult) {
-        // Count issues by status
-        const statusCounts = {};
-        for (const issue of searchResult.issues) {
-            const status = issue.status;
-            statusCounts[status] = (statusCounts[status] || 0) + 1;
-        }
-        const suggestedActions = [];
-        // Add pagination actions if there are more results
-        if (searchResult.pagination.hasMore) {
-            suggestedActions.push({
-                text: 'Load more results'
-            });
-        }
-        return BaseFormatter.createSummary({
-            status_counts: statusCounts,
-            suggested_actions: suggestedActions
-        });
-    }
-}

package/build/utils/formatters/sprint-formatter.js

@@ -1,111 +0,0 @@
-import { BaseFormatter } from './base-formatter.js';
-export class SprintFormatter {
-    /**
-     * Format a sprint response with the standard structure and optional expansions
-     * @param sprint The sprint data
-     * @param options Expansion options
-     * @returns A formatted sprint response
-     */
-    static formatSprint(sprint, options = {}) {
-        // Create metadata with available expansions
-        const metadata = this.createSprintMetadata(sprint, options);
-        // Create summary
-        const summary = this.createSprintSummary(sprint);
-        return BaseFormatter.formatResponse(sprint, metadata, summary);
-    }
-    /**
-     * Format a list of sprints
-     * @param sprints Array of sprint data
-     * @param pagination Pagination information
-     * @returns A formatted response with sprints array
-     */
-    static formatSprintList(sprints, pagination) {
-        // Create metadata
-        const metadata = {};
-        if (pagination) {
-            metadata.pagination = {
-                startAt: pagination.startAt,
-                maxResults: pagination.maxResults,
-                total: pagination.total,
-                hasMore: pagination.startAt + pagination.maxResults < pagination.total,
-            };
-        }
-        // Create summary with status counts
-        const statusCounts = {
-            future: 0,
-            active: 0,
-            closed: 0,
-        };
-        sprints.forEach(sprint => {
-            if (sprint.state && statusCounts[sprint.state] !== undefined) {
-                statusCounts[sprint.state]++;
-            }
-        });
-        const summary = {
-            status_counts: statusCounts,
-            suggested_actions: [
-                { text: 'Create new sprint', action_id: 'create_sprint' },
-            ],
-        };
-        return BaseFormatter.formatResponse(sprints, metadata, summary);
-    }
-    /**
-     * Create metadata for a sprint response
-     */
-    static createSprintMetadata(sprint, options) {
-        // Determine which expansions are available but not included
-        const availableExpansions = [];
-        if (!options.issues && !sprint.issues) {
-            availableExpansions.push('issues');
-        }
-        if (!options.report && !sprint.report) {
-            availableExpansions.push('report');
-        }
-        // Create related entities map
-        const related = {
-            board: sprint.boardId.toString(),
-        };
-        return BaseFormatter.createMetadata({
-            expansions: availableExpansions,
-            related
-        });
-    }
-    /**
-     * Create a summary for a sprint response
-     */
-    static createSprintSummary(sprint) {
-        const suggestedActions = [];
-        // Add suggested actions based on sprint state
-        switch (sprint.state) {
-            case 'future':
-                suggestedActions.push({ text: 'Start Sprint', action_id: 'start_sprint' });
-                suggestedActions.push({ text: 'Add Issues to Sprint', action_id: 'add_issues' });
-                suggestedActions.push({ text: 'Edit Sprint', action_id: 'update_sprint' });
-                break;
-            case 'active':
-                suggestedActions.push({ text: 'Complete Sprint', action_id: 'complete_sprint' });
-                suggestedActions.push({ text: 'Add Issues to Sprint', action_id: 'add_issues' });
-                suggestedActions.push({ text: 'Remove Issues from Sprint', action_id: 'remove_issues' });
-                suggestedActions.push({ text: 'Edit Sprint', action_id: 'update_sprint' });
-                break;
-            case 'closed':
-                suggestedActions.push({ text: 'View Sprint Report', action_id: 'view_report' });
-                suggestedActions.push({ text: 'Create New Sprint', action_id: 'create_sprint' });
-                break;
-        }
-        // Add status counts if issues are available
-        const statusCounts = {};
-        if (sprint.issues && sprint.issues.length > 0) {
-            sprint.issues.forEach(issue => {
-                if (!statusCounts[issue.status]) {
-                    statusCounts[issue.status] = 0;
-                }
-                statusCounts[issue.status]++;
-            });
-        }
-        return BaseFormatter.createSummary({
-            status_counts: Object.keys(statusCounts).length > 0 ? statusCounts : undefined,
-            suggested_actions: suggestedActions
-        });
-    }
-}