Jira MCP Server

Instructions

Implementation Reference

• src/handlers/issue-handlers.ts:68-149 (handler)

  The handler function that executes the create_issue tool. It validates required parameters, constructs the issue payload (converting description to ADF if needed, resolving assignee to account ID), posts to the Jira API, and returns a formatted success or error response.

  async handleCreateIssue(args: any) {
    try {
      const { projectKey, summary, issueType, description, priority, assignee, labels, customFields } = args;
  
      if (!projectKey || !summary || !issueType) {
        throw new Error('projectKey, summary, and issueType are required');
      }
  
      const issueData: any = {
        fields: {
          project: { key: projectKey },
          summary,
          issuetype: { name: issueType },
        },
      };
  
      // Handle description - convert to ADF format if it's plain text
      if (description) {
        if (typeof description === 'string') {
          // Convert plain text to Atlassian Document Format
          issueData.fields.description = {
            type: 'doc',
            version: 1,
            content: [
              {
                type: 'paragraph',
                content: [
                  {
                    type: 'text',
                    text: description,
                  },
                ],
              },
            ],
          };
        } else {
          // Already in ADF format
          issueData.fields.description = description;
        }
      }
  
      if (priority) {
        issueData.fields.priority = { name: priority };
      }
  
      if (assignee) {
        // Auto-resolve email to account ID if needed
        const accountId = await this.userHandlers.resolveUserToAccountId(assignee);
        issueData.fields.assignee = { id: accountId };
      }
  
      if (labels && Array.isArray(labels)) {
        issueData.fields.labels = labels;
      }
  
      // Merge custom fields
      if (customFields && typeof customFields === 'object') {
        Object.assign(issueData.fields, customFields);
      }
  
      const result = await this.apiClient.post('/issue', issueData);
  
      return {
        content: [
          {
            type: 'text',
            text: `✅ Issue created successfully!\n\n**Key**: ${result.key}\n**ID**: ${result.id}\n**URL**: ${this.apiClient.getBaseUrl()}/browse/${result.key}`,
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: 'text',
            text: JiraFormatters.formatError(error),
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/definitions.ts:17-58 (schema)

  The input schema definition for the create_issue tool, specifying parameters like projectKey, summary, issueType (required), and optional fields like description, priority, assignee, labels, customFields.

  {
    name: 'create_issue',
    description: 'Create a new Jira issue with specified fields. IMPORTANT: Always use get_create_metadata first to discover required fields, custom fields, and allowed values for the project and issue type.',
    inputSchema: {
      type: 'object',
      properties: {
        projectKey: {
          type: 'string',
          description: 'The project key where the issue will be created (e.g., PROJ, DEV)',
        },
        summary: {
          type: 'string',
          description: 'The issue summary/title',
        },
        issueType: {
          type: 'string',
          description: 'The issue type (e.g., Bug, Task, Story)',
        },
        description: {
          description: 'The issue description in Atlassian Document Format (ADF). Can be a simple string for plain text, or an ADF object for rich formatting. Example ADF: {"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Description text"}]}]}',
        },
        priority: {
          type: 'string',
          description: 'Priority name (e.g., High, Medium, Low) - optional',
        },
        assignee: {
          type: 'string',
          description: 'Assignee account ID or email (will auto-lookup account ID from email) - optional',
        },
        labels: {
          type: 'array',
          items: { type: 'string' },
          description: 'Array of labels - 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: ['projectKey', 'summary', 'issueType'],
    },
  },

• src/index.ts:100-101 (registration)

  The switch case in the tool request handler that dispatches create_issue calls to the IssueHandlers.handleCreateIssue method.

  case 'create_issue':
    return this.issueHandlers.handleCreateIssue(request.params.arguments);