transition_issue

Instructions

Implementation Reference

• src/tools/transitions.ts:86-96 (handler)

  The handler case within handleTransitionTool that validates args against transitionIssueSchema and calls jiraClient.transitionIssue(). Returns a success message.

  case 'transition_issue': {
    const validatedArgs = await transitionIssueSchema.validate(args);
    const _result = await jiraClient.transitionIssue(validatedArgs);
    return {
      content: [
        {
          type: 'text',
          text: `Issue ${validatedArgs.issueKey} transitioned successfully`,
        },
      ],
    };

• src/schemas/index.ts:90-100 (schema)

  The Yup validation schema for transition_issue, requiring issueKey and transitionId (converted to string), with optional comment and fields.

  export const transitionIssueSchema = yup.object({
    issueKey: yup.string().required('Issue key is required'),
    transitionId: yup.mixed()
      .required('Transition ID is required')
      .transform(function (value) {
        // Convert to string if it's a number
        return String(value);
      }),
    comment: yup.string().optional(),
    fields: yup.object().optional(),
  });

• src/jira-client.ts:250-311 (helper)

  The JiraClient.transitionIssue() method that calls the Jira API doTransition, handling comment as ADF and optional additional fields.

  async transitionIssue(input: TransitionIssueInput) {
    try {
      const transitionData: IssueUpdateDetails = {
        transition: { id: String(input.transitionId) },
      };
  
      if (input.comment) {
        // Use official ADF format for transition comments
        const adfBody = {
          version: 1,
          type: 'doc',
          content: [
            {
              type: 'paragraph',
              content: [
                {
                  type: 'text',
                  text: input.comment
                }
              ]
            }
          ]
        };
  
        transitionData.update = {
          comment: [{
            add: {
              body: adfBody,
            },
          }],
        };
      }
  
      if (input.fields) {
        transitionData.fields = input.fields;
      }
  
      console.error('Transitioning issue with jira.js:', JSON.stringify(transitionData, null, 2));
  
      const response = await this.jira.issues.doTransition({
        issueIdOrKey: input.issueKey,
        ...transitionData,
      });
  
      return response;
    } catch (error: unknown) {
      const errorDetails = {
        message: (error as Error).message,
        status: (error as JiraError).status,
        statusText: (error as JiraError).statusText,
        response: (error as JiraError).response?.data,
        request: {
          issueKey: input.issueKey,
          transitionId: input.transitionId,
          comment: input.comment,
          fields: input.fields
        }
      };
      console.error('Transition error details:', JSON.stringify(errorDetails, null, 2));
      throw new Error(`Failed to transition issue: ${JSON.stringify(errorDetails, null, 2)}`);
    }
  }

• src/tools/transitions.ts:25-51 (registration)

  Tool definition registration inside createTransitionTools, declaring name 'transition_issue', description, inputSchema with properties and required fields.

    {
      name: 'transition_issue',
      description: 'Move a Jira issue to a different status/state',
      inputSchema: {
        type: 'object',
        properties: {
          issueKey: {
            type: 'string',
            description: 'The issue key to transition',
          },
          transitionId: {
            type: 'number',
            description: 'The ID of the transition to perform (will be converted to string automatically)',
          },
          comment: {
            type: 'string',
            description: 'Optional comment to add during transition',
          },
          fields: {
            type: 'object',
            description: 'Additional fields to update during transition',
          },
        },
        required: ['issueKey', 'transitionId'],
      },
    },
  ];

• src/index.ts:85-89 (registration)

  Routing in the MCP server's CallToolRequestSchema handler: routes 'transition_issue' name prefix to handleTransitionTool.

  } else if (
    name.startsWith('get_transitions') ||
    name.startsWith('transition_issue')
  ) {
    return await handleTransitionTool(name, args || {}, this.jiraClient);