@aaronsb/jira-cloud-mcp 0.7.6 → 0.8.1

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' : ''} |`);
     }
@@ -405,6 +398,10 @@ async function batchParallel(tasks, batchSize) {
     return results;
 }
 const ROW_BATCH_SIZE = 3; // ~18-33 concurrent count queries per batch
+/** Strip ORDER BY clause from JQL — ordering is meaningless for counts and analysis */
+export function stripOrderBy(jql) {
+    return jql.replace(/\s+ORDER\s+BY\s+.+$/i, '');
+}
 /** Build a scoped JQL by adding a condition to the base query */
 function scopeJql(baseJql, condition) {
     return `(${baseJql}) AND ${condition}`;
@@ -779,6 +776,8 @@ function graphIssueToDetails(issue) {
         storyPoints: issue.storyPoints,
         sprint: null,
         timeEstimate: null,
+        originalEstimate: null,
+        timeSpent: null,
         issueLinks: [],
     };
 }
@@ -899,6 +898,9 @@ export async function handleAnalysisRequest(jiraClient, request, graphqlClient,
             throw new McpError(ErrorCode.InvalidParams, 'Either jql, filterId, or dataRef parameter is required.');
         }
     }
+    // Strip ORDER BY — analysis uses counts and full-page fetches, ordering is meaningless
+    // and breaks scopeJql() which wraps JQL in parens (ORDER BY inside parens is invalid)
+    jql = stripOrderBy(jql);
     // Parse requested metrics
     const requested = (args.metrics && Array.isArray(args.metrics))
         ? args.metrics

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.6",
+  "version": "0.8.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",