JIRA MCP Server

Instructions

Implementation Reference

• src/features/jira/issues/handlers/add-worklog.handler.ts:22-109 (handler)

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

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

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

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

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

• src/features/jira/tools/factories/tool.factory.ts:141-143 (handler)

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