JIRA MCP Server

Instructions

Implementation Reference

• src/features/jira/issues/handlers/get-worklogs.handler.ts:22-106 (handler)

  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.`,
      );
    }
  }

• src/features/jira/issues/validators/worklog.validator.ts:109-126 (schema)

  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(),
  });

• src/features/jira/tools/configs/worklog-tools.config.ts:34-51 (registration)

  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),
    },
  ];

• src/features/jira/tools/factories/tool.factory.ts:119-154 (helper)

  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,
  }),