jira_add_worklog
Log time spent on JIRA issues to track work progress and maintain accurate records for project management and billing.
Instructions
Add a worklog entry to track time spent on an issue
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | ||
| timeSpent | Yes | ||
| comment | No | ||
| started | No | ||
| visibility | No |
Implementation Reference
- AddWorklogHandler class implementing the tool execution logic: validates input, calls use case to add worklog to JIRA issue, handles and enhances errors with user-friendly messages, formats response
export class AddWorklogHandler extends BaseToolHandler< AddWorklogParams, string > { private formatter: WorklogEntryFormatter; /** * Create a new AddWorklogHandler with use case and validator * * @param addWorklogUseCase - Use case for adding worklog entries * @param worklogValidator - Validator for worklog parameters */ constructor( private readonly addWorklogUseCase: AddWorklogUseCase, private readonly worklogValidator: WorklogValidator, ) { super("JIRA", "Add Worklog"); this.formatter = new WorklogEntryFormatter(); } /** * Execute the handler logic * Adds a worklog entry and formats the result * * @param params - Parameters for worklog addition */ protected async execute(params: AddWorklogParams): Promise<string> { try { // Step 1: Validate parameters const validatedParams = this.worklogValidator.validateAddWorklogParams(params); this.logger.info(`Adding worklog to issue: ${validatedParams.issueKey}`, { timeSpent: validatedParams.timeSpent, }); // Step 2: Add worklog using use case const response = await this.addWorklogUseCase.execute({ issueKey: validatedParams.issueKey, timeSpent: validatedParams.timeSpent, comment: validatedParams.comment, started: validatedParams.started, }); // Step 3: Format worklog using the formatter return this.formatter.format(response.worklog); } catch (error) { this.logger.error(`Failed to add worklog: ${error}`); throw this.enhanceError(error, params); } } /** * Enhance error messages for better user guidance */ private enhanceError(error: unknown, params?: AddWorklogParams): Error { const issueContext = params?.issueKey ? ` for issue ${params.issueKey}` : ""; if (error instanceof JiraNotFoundError) { return new Error( `❌ **Issue Not Found**\n\nNo issue found${issueContext}.\n\n**Solutions:**\n- Verify the issue key is correct\n- Check if the issue exists\n- Verify you have permission to view the issue\n\n**Example:** \`jira_add_worklog issueKey="PROJ-123" timeSpent="2h"\``, ); } if (error instanceof JiraPermissionError) { return new Error( `❌ **Permission Denied**\n\nYou don't have permission to add worklog entries${issueContext}.\n\n**Solutions:**\n- Check your JIRA permissions\n- Contact your JIRA administrator\n- Verify you have work on issues permission\n\n**Required Permissions:** Work on Issues`, ); } if (error instanceof JiraApiError) { return new Error( `❌ **JIRA API Error**\n\n${error.message}\n\n**Solutions:**\n- Verify the time format (e.g., "2h", "30m", "1d")\n- Check the issue key is valid (format: PROJ-123)\n- Verify the started date is in ISO format\n\n**Example:** \`jira_add_worklog issueKey="PROJ-123" timeSpent="2h" comment="Fixed bug"\``, ); } if (error instanceof Error) { return new Error( `❌ **Worklog Addition Failed**\n\n${error.message}${issueContext}\n\n**Solutions:**\n- Check your parameters are valid\n- Verify your JIRA connection\n- Ensure time format is correct (e.g., "2h", "30m")\n\n**Example:** \`jira_add_worklog issueKey="PROJ-123" timeSpent="2h"\``, ); } return new Error( `❌ **Unknown Error**\n\nAn unknown error occurred during worklog addition${issueContext}.\n\nPlease check your parameters and try again.`, ); } } - Zod schema defining the input parameters for the jira_add_worklog tool including issueKey, timeSpent (required with format validation), optional comment, started datetime, and visibility
export const addWorklogParamsSchema = z.object({ issueKey: issueKeySchema, // Required fields timeSpent: z .string() .min(1, "Time spent is required") .regex( /^\d+[wdhm]$/, "Time spent must be in format like '2w', '3d', '4h', '30m'", ), // Optional fields comment: z .string() .max(32767, "Comment too long (max 32,767 characters)") .optional(), started: z .string() .datetime("Started time must be a valid ISO datetime") .optional(), // Visibility settings visibility: z .object({ type: z.enum(["group", "role"]), value: z.string().min(1), }) .optional(), }); - Tool configuration object registering 'jira_add_worklog' with name, description, params schema, and bound handler function
{ name: "jira_add_worklog", description: "Add a worklog entry to track time spent on an issue", params: addWorklogParamsSchema.shape, handler: tools.jira_add_worklog.handle.bind(tools.jira_add_worklog), }, - Factory creation of the jira_add_worklog ToolHandler object, wrapping the AddWorklogHandler.handle method
jira_add_worklog: { handle: async (args: unknown) => addWorklogHandler.handle(args), }, - src/features/jira/tools/registry/tool.registry.ts:94-100 (registration)Registration group configuration including jira_add_worklog tool handler passed to worklog tools config creator, which is then registered with MCP server
groupName: "worklogs", configs: createWorklogToolsConfig({ jira_add_worklog: tools.jira_add_worklog, jira_get_worklogs: tools.jira_get_worklogs, jira_update_worklog: tools.jira_update_worklog, jira_delete_worklog: tools.jira_delete_worklog, }),