jira_get_worklogs
Retrieve worklog entries for a specific JIRA issue to track time spent, analyze effort, and monitor progress on tasks.
Instructions
Get all worklog entries for a specific issue
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | ||
| startAt | No | ||
| maxResults | No | ||
| startedAfter | No | ||
| startedBefore | No |
Implementation Reference
- The GetWorklogsHandler class implements the core tool execution logic: validates input parameters, invokes the GetWorklogsUseCase, formats the worklog list response, and provides enhanced error messages.export class GetWorklogsHandler extends BaseToolHandler< GetWorklogsParams, string > { private formatter: WorklogListFormatter; /** * Create a new GetWorklogsHandler with use case and validator * * @param getWorklogsUseCase - Use case for retrieving worklog entries * @param worklogValidator - Validator for worklog parameters */ constructor( private readonly getWorklogsUseCase: GetWorklogsUseCase, private readonly worklogValidator: WorklogValidator, ) { super("JIRA", "Get Worklogs"); this.formatter = new WorklogListFormatter(); } /** * Execute the handler logic * Retrieves worklog entries and formats them * * @param params - Parameters for worklog retrieval */ protected async execute(params: GetWorklogsParams): Promise<string> { try { // Step 1: Validate parameters const validatedParams = this.worklogValidator.validateGetWorklogsParams(params); this.logger.info( `Getting worklogs for issue: ${validatedParams.issueKey}`, ); // Step 2: Get worklogs using use case const response = await this.getWorklogsUseCase.execute({ issueKey: validatedParams.issueKey, }); // Step 3: Format worklogs using the formatter return this.formatter.format(response.worklogs); } catch (error) { this.logger.error(`Failed to get worklogs: ${error}`); throw this.enhanceError(error, params); } } /** * Enhance error messages for better user guidance */ private enhanceError(error: unknown, params?: GetWorklogsParams): 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_get_worklogs issueKey="PROJ-123"\``, ); } if (error instanceof JiraPermissionError) { return new Error( `❌ **Permission Denied**\n\nYou don't have permission to view worklog entries${issueContext}.\n\n**Solutions:**\n- Check your JIRA permissions\n- Contact your JIRA administrator\n- Verify you have browse projects permission\n\n**Required Permissions:** Browse Projects`, ); } if (error instanceof JiraApiError) { return new Error( `❌ **JIRA API Error**\n\n${error.message}\n\n**Solutions:**\n- Check the issue key is valid (format: PROJ-123)\n- Verify your JIRA connection\n- Try with a different issue\n\n**Example:** \`jira_get_worklogs issueKey="PROJ-123"\``, ); } if (error instanceof Error) { return new Error( `❌ **Worklog Retrieval Failed**\n\n${error.message}${issueContext}\n\n**Solutions:**\n- Check your parameters are valid\n- Verify your JIRA connection\n- Try with a different issue\n\n**Example:** \`jira_get_worklogs issueKey="PROJ-123"\``, ); } return new Error( `❌ **Unknown Error**\n\nAn unknown error occurred during worklog retrieval${issueContext}.\n\nPlease check your parameters and try again.`, ); } }
- Zod schema defining the input parameters for the jira_get_worklogs tool, including issueKey (required), optional pagination (startAt, maxResults), and date filters (startedAfter, startedBefore).export const getWorklogsParamsSchema = z.object({ issueKey: issueKeySchema, // Optional pagination startAt: z.number().int().min(0).optional().default(0), maxResults: z.number().int().min(1).max(1000).optional().default(1000), // Optional date filtering startedAfter: z .string() .datetime("Started after must be a valid ISO datetime") .optional(), startedBefore: z .string() .datetime("Started before must be a valid ISO datetime") .optional(), });
- Tool configuration object used for registering the jira_get_worklogs tool with the MCP server, specifying name, description, input schema, and handler binding.name: "jira_get_worklogs", description: "Get all worklog entries for a specific issue", params: getWorklogsParamsSchema.shape, handler: tools.jira_get_worklogs.handle.bind(tools.jira_get_worklogs), }, { name: "jira_update_worklog", description: "Update an existing worklog entry", params: updateWorklogParamsSchema.shape, handler: tools.jira_update_worklog.handle.bind(tools.jira_update_worklog), }, { name: "jira_delete_worklog", description: "Delete a worklog entry from an issue", params: deleteWorklogParamsSchema.shape, handler: tools.jira_delete_worklog.handle.bind(tools.jira_delete_worklog), }, ];
- Factory function createWorklogHandlers that instantiates the GetWorklogsHandler with dependencies and creates the jira_get_worklogs tool handler wrapper with the 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, passing the jira_get_worklogs handler to createWorklogToolsConfig for final MCP server registration.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, }),