jira_add_worklog
Track time spent on JIRA issues by adding worklog entries with issue keys, time spent, comments, and timestamps directly via the JIRA MCP Server integration.
Instructions
Add a worklog entry to track time spent on an issue
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| comment | No | ||
| issueKey | Yes | ||
| started | No | ||
| timeSpent | Yes | ||
| visibility | No |
Implementation Reference
- The AddWorklogHandler class that implements the core logic for the jira_add_worklog tool. It validates input parameters, executes the addWorklogUseCase, formats the response, and handles errors with user-friendly messages.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 and validation rules for the jira_add_worklog tool.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 the jira_add_worklog tool with name, description, parameters schema, and handler.{ 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 function creating the jira_add_worklog tool handler by instantiating AddWorklogHandler with dependencies and wrapping its handle method.function createWorklogHandlers(dependencies: JiraDependencies) { const addWorklogHandler = new AddWorklogHandler( dependencies.addWorklogUseCase, dependencies.worklogValidator, ); const getWorklogsHandler = new GetWorklogsHandler( dependencies.getWorklogsUseCase, dependencies.worklogValidator, ); const updateWorklogHandler = new UpdateWorklogHandler( dependencies.updateWorklogUseCase, dependencies.worklogValidator, ); const deleteWorklogHandler = new DeleteWorklogHandler( dependencies.deleteWorklogUseCase, dependencies.worklogValidator, ); return { jira_add_worklog: { handle: async (args: unknown) => addWorklogHandler.handle(args), }, jira_get_worklogs: { handle: async (args: unknown) => getWorklogsHandler.handle(args), }, jira_update_worklog: { handle: async (args: unknown) => updateWorklogHandler.handle(args), }, jira_delete_worklog: { handle: async (args: unknown) => deleteWorklogHandler.handle(args), }, }; }
- src/features/jira/tools/registry/tool.registry.ts:94-100 (registration)Tool registry configuration group for worklogs, invoking createWorklogToolsConfig to register jira_add_worklog among others.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, }),