Backlog MCP Server

Instructions

Implementation Reference

• src/tools/addIssue.ts:124-133 (handler)

  The handler function for the 'add_issue' tool that processes the input parameters including custom fields and calls the Backlog API to create a new issue.

  handler: async ({ customFields, ...params }) => {
    const customFieldPayload = customFieldsToPayload(customFields);
  
    const finalPayload = {
      ...params,
      ...customFieldPayload,
    };
  
    return backlog.postIssue(finalPayload);
  },

• src/tools/addIssue.ts:8-106 (schema)

  Input schema definition for the 'add_issue' tool using Zod, defining all parameters like projectId, summary, issueTypeId, etc., including custom fields.

  const addIssueSchema = buildToolSchema((t) => ({
    projectId: z.number().describe(t('TOOL_ADD_ISSUE_PROJECT_ID', 'Project ID')),
    summary: z
      .string()
      .describe(t('TOOL_ADD_ISSUE_SUMMARY', 'Summary of the issue')),
    issueTypeId: z
      .number()
      .describe(t('TOOL_ADD_ISSUE_ISSUE_TYPE_ID', 'Issue type ID')),
    priorityId: z
      .number()
      .describe(t('TOOL_ADD_ISSUE_PRIORITY_ID', 'Priority ID')),
    description: z
      .string()
      .optional()
      .describe(
        t('TOOL_ADD_ISSUE_DESCRIPTION', 'Detailed description of the issue')
      ),
    startDate: z
      .string()
      .optional()
      .describe(
        t('TOOL_ADD_ISSUE_START_DATE', 'Scheduled start date (yyyy-MM-dd)')
      ),
    dueDate: z
      .string()
      .optional()
      .describe(t('TOOL_ADD_ISSUE_DUE_DATE', 'Scheduled due date (yyyy-MM-dd)')),
    estimatedHours: z
      .number()
      .optional()
      .describe(t('TOOL_ADD_ISSUE_ESTIMATED_HOURS', 'Estimated work hours')),
    actualHours: z
      .number()
      .optional()
      .describe(t('TOOL_ADD_ISSUE_ACTUAL_HOURS', 'Actual work hours')),
    categoryId: z
      .array(z.number())
      .optional()
      .describe(t('TOOL_ADD_ISSUE_CATEGORY_ID', 'Category IDs')),
    versionId: z
      .array(z.number())
      .optional()
      .describe(t('TOOL_ADD_ISSUE_VERSION_ID', 'Version IDs')),
    milestoneId: z
      .array(z.number())
      .optional()
      .describe(t('TOOL_ADD_ISSUE_MILESTONE_ID', 'Milestone IDs')),
    assigneeId: z
      .number()
      .optional()
      .describe(t('TOOL_ADD_ISSUE_ASSIGNEE_ID', 'User ID of the assignee')),
    notifiedUserId: z
      .array(z.number())
      .optional()
      .describe(t('TOOL_ADD_ISSUE_NOTIFIED_USER_ID', 'User IDs to notify')),
    attachmentId: z
      .array(z.number())
      .optional()
      .describe(t('TOOL_ADD_ISSUE_ATTACHMENT_ID', 'Attachment IDs')),
    parentIssueId: z
      .number()
      .optional()
      .describe(t('TOOL_ADD_ISSUE_PARENT_ISSUE_ID', 'Parent issue ID')),
    customFields: z
      .array(
        z.object({
          id: z
            .number()
            .describe(
              t(
                'TOOL_ADD_ISSUE_CUSTOM_FIELD_ID',
                'The ID of the custom field (e.g., 12345)'
              )
            ),
          value: z
            .union([z.number(), z.array(z.number())])
            .optional()
            .describe(
              'The ID(s) of the custom field item. For single-select fields, provide a number. For multi-select fields, provide an array of numbers representing the selected item IDs.'
            ),
          otherValue: z
            .string()
            .optional()
            .describe(
              t(
                'TOOL_ADD_ISSUE_CUSTOM_FIELD_OTHER_VALUE',
                'Other value for list type fields'
              )
            ),
        })
      )
      .optional()
      .describe(
        t(
          'TOOL_ADD_ISSUE_CUSTOM_FIELDS',
          'List of custom fields to set on the issue'
        )
      ),
  }));

• src/tools/tools.ts:96-96 (registration)

  Registration of the 'add_issue' tool within the 'issue' toolset group returned by allTools.

  addIssueTool(backlog, helper),

• src/tools/addIssue.ts:121-122 (schema)

  Tool schema usage: input schema from addIssueSchema and output schema as IssueSchema.

  schema: z.object(addIssueSchema(t)),
  outputSchema: IssueSchema,

• src/tools/tools.ts:88-117 (registration)

  The 'issue' toolset group where the add_issue tool is registered as part of the tools array.

  {
    name: 'issue',
    description: 'Tools for managing issues and their comments.',
    enabled: false,
    tools: [
      getIssueTool(backlog, helper),
      getIssuesTool(backlog, helper),
      countIssuesTool(backlog, helper),
      addIssueTool(backlog, helper),
      updateIssueTool(backlog, helper),
      deleteIssueTool(backlog, helper),
      getIssueCommentsTool(backlog, helper),
      addIssueCommentTool(backlog, helper),
      getPrioritiesTool(backlog, helper),
      getCategoriesTool(backlog, helper),
      getCustomFieldsTool(backlog, helper),
      getIssueTypesTool(backlog, helper),
      getResolutionsTool(backlog, helper),
      getWatchingListItemsTool(backlog, helper),
      getWatchingListCountTool(backlog, helper),
      addWatchingTool(backlog, helper),
      updateWatchingTool(backlog, helper),
      deleteWatchingTool(backlog, helper),
      markWatchingAsReadTool(backlog, helper),
      getVersionMilestoneListTool(backlog, helper),
      addVersionMilestoneTool(backlog, helper),
      updateVersionMilestoneTool(backlog, helper),
      deleteVersionTool(backlog, helper),
    ],
  },