Jira MCP Server

Instructions

Implementation Reference

• src/handlers/issue-handlers.ts:151-228 (handler)

  Core implementation of the `update_issue` tool handler. Parses arguments, validates required `issueKey`, builds update payload handling ADF description conversion, assignee resolution via userHandlers, labels, custom fields; performs API PUT request and returns formatted success or error response.

  async handleUpdateIssue(args: any) {
    try {
      const { issueKey, summary, description, priority, assignee, labels, customFields } = args;
  
      if (!issueKey) {
        throw new Error('issueKey is required');
      }
  
      const updateData: any = { fields: {} };
  
      if (summary) updateData.fields.summary = summary;
  
      // Handle description - convert to ADF format if it's plain text
      if (description) {
        if (typeof description === 'string') {
          // Convert plain text to Atlassian Document Format
          updateData.fields.description = {
            type: 'doc',
            version: 1,
            content: [
              {
                type: 'paragraph',
                content: [
                  {
                    type: 'text',
                    text: description,
                  },
                ],
              },
            ],
          };
        } else {
          // Already in ADF format
          updateData.fields.description = description;
        }
      }
  
      if (priority) updateData.fields.priority = { name: priority };
  
      if (assignee) {
        // Auto-resolve email to account ID if needed
        const accountId = await this.userHandlers.resolveUserToAccountId(assignee);
        updateData.fields.assignee = { id: accountId };
      }
  
      if (labels) updateData.fields.labels = labels;
  
      // Merge custom fields
      if (customFields && typeof customFields === 'object') {
        Object.assign(updateData.fields, customFields);
      }
  
      if (Object.keys(updateData.fields).length === 0) {
        throw new Error('At least one field to update must be provided');
      }
  
      await this.apiClient.put(`/issue/${issueKey}`, updateData);
  
      return {
        content: [
          {
            type: 'text',
            text: `✅ Issue ${issueKey} updated successfully!`,
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: 'text',
            text: JiraFormatters.formatError(error),
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/definitions.ts:60-96 (schema)

  Input schema definition for the `update_issue` tool, specifying properties like issueKey (required), optional fields for summary, description, priority, assignee, labels, customFields, with descriptions.

    name: 'update_issue',
    description: 'Update fields of an existing Jira issue. TIP: Use get_create_metadata to discover available custom fields and their allowed values for the project.',
    inputSchema: {
      type: 'object',
      properties: {
        issueKey: {
          type: 'string',
          description: 'The issue key to update (e.g., PROJ-123)',
        },
        summary: {
          type: 'string',
          description: 'New summary/title - optional',
        },
        description: {
          description: 'New description in ADF format or plain string - optional',
        },
        priority: {
          type: 'string',
          description: 'New priority name - optional',
        },
        assignee: {
          type: 'string',
          description: 'New assignee account ID or email (will auto-lookup account ID from email) - optional',
        },
        labels: {
          type: 'array',
          items: { type: 'string' },
          description: 'New labels array - optional',
        },
        customFields: {
          type: 'object',
          description: 'Custom fields as key-value pairs (e.g., {"customfield_10000": "value"}) - optional. Use get_create_metadata to discover available fields.',
        },
      },
      required: ['issueKey'],
    },
  },

• src/index.ts:102-103 (registration)

  Registration of the `update_issue` tool in the MCP server's CallToolRequestSchema handler switch statement, dispatching to `issueHandlers.handleUpdateIssue`.

  case 'update_issue':
    return this.issueHandlers.handleUpdateIssue(request.params.arguments);

• src/index.ts:90-92 (registration)

  Registration for listing tools via ListToolsRequestSchema, which includes the `update_issue` tool from `toolDefinitions`.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: toolDefinitions,
  }));

• src/index.ts:70-71 (registration)

  Instantiation of IssueHandlers (containing handleUpdateIssue) in the JiraMCPServer constructor, passing apiClient and userHandlers dependencies.

  this.userHandlers = new UserHandlers(this.apiClient);
  this.issueHandlers = new IssueHandlers(this.apiClient, this.userHandlers);