mcp-jira-stdio

Instructions

Implementation Reference

• src/tools/get-issue.ts:42-66 (handler)

  Main handler function executing the tool: validates input with schema, extracts issue key from URL or key, fetches issue via API helper, formats response, handles errors.

  export async function handleGetIssue(input: unknown): Promise<McpToolResponse> {
    try {
      const validated = validateInput(GetIssueInputSchema, input);
  
      // Accept either an issue key or a full Jira URL and extract the key
      const trimmedInput = (validated.issueKey || '').trim();
      const key = extractIssueKey(trimmedInput) || trimmedInput;
  
      log.info(`Getting issue ${key}...`);
  
      const getParams: any = {};
  
      if (validated.expand !== undefined) getParams.expand = validated.expand;
      if (validated.fields !== undefined) getParams.fields = validated.fields;
  
      const issue = await getIssue(key, getParams);
  
      log.info(`Retrieved issue ${issue.key}`);
  
      return formatIssueResponse(issue);
    } catch (error) {
      log.error('Error in handleGetIssue:', error);
      return handleError(error);
    }
  }

• src/tools/get-issue.ts:13-40 (schema)

  MCP Tool object definition with name 'jira_get_issue', description, and inputSchema for protocol exposure.

  export const getIssueTool: Tool = {
    name: TOOL_NAMES.GET_ISSUE,
    description:
      'Retrieve details for a specific Jira issue by key or URL. Use this when the user mentions an issue like "PAYWALL-943" or pastes a Jira link (e.g., https://your.atlassian.net/browse/PAYWALL-943). Returns status, assignee, priority, project, type, labels, components, timestamps, and description.',
    inputSchema: {
      type: 'object',
      properties: {
        issueKey: {
          type: 'string',
          description:
            'Issue key or full Jira URL (e.g., PROJECT-123 or https://your.atlassian.net/browse/PROJECT-123)',
        },
        expand: {
          type: 'array',
          items: { type: 'string' },
          description:
            'Additional issue details to include (e.g., ["comments", "attachments", "changelog"])',
          default: [],
        },
        fields: {
          type: 'array',
          items: { type: 'string' },
          description: 'Specific fields to retrieve (e.g., ["summary", "status", "assignee"])',
        },
      },
      required: ['issueKey'],
    },
  };

• src/index.ts:32-49 (registration)

  Registration of tool handlers in a Map, mapping 'jira_get_issue' to handleGetIssue via TOOL_NAMES.GET_ISSUE.

  const toolHandlers = new Map<string, (input: unknown) => Promise<any>>([
    [TOOL_NAMES.GET_VISIBLE_PROJECTS, tools.handleGetVisibleProjects],
    [TOOL_NAMES.GET_ISSUE, tools.handleGetIssue],
    [TOOL_NAMES.SEARCH_ISSUES, tools.handleSearchIssues],
    [TOOL_NAMES.GET_MY_ISSUES, tools.handleGetMyIssues],
    [TOOL_NAMES.GET_ISSUE_TYPES, tools.handleGetIssueTypes],
    [TOOL_NAMES.GET_USERS, tools.handleGetUsers],
    [TOOL_NAMES.GET_PRIORITIES, tools.handleGetPriorities],
    [TOOL_NAMES.GET_STATUSES, tools.handleGetStatuses],
    [TOOL_NAMES.CREATE_ISSUE, tools.handleCreateIssue],
    [TOOL_NAMES.UPDATE_ISSUE, tools.handleUpdateIssue],
    [TOOL_NAMES.ADD_COMMENT, tools.handleAddComment],
    [TOOL_NAMES.GET_PROJECT_INFO, tools.handleGetProjectInfo],
    [TOOL_NAMES.CREATE_SUBTASK, tools.handleCreateSubtask],
    [TOOL_NAMES.GET_CREATE_META, tools.handleGetCreateMeta],
    [TOOL_NAMES.GET_CUSTOM_FIELDS, tools.handleGetCustomFields],
    [TOOL_NAMES.CREATE_ISSUE_LINK, tools.handleCreateIssueLink],
  ]);

• src/index.ts:52-69 (registration)

  Registration of tool definitions in allTools array for ListTools, including getIssueTool.

  const allTools = [
    tools.getVisibleProjectsTool,
    tools.getIssueTool,
    tools.searchIssuesTool,
    tools.getMyIssuesTool,
    tools.getIssueTypesTool,
    tools.getUsersTool,
    tools.getPrioritiesTool,
    tools.getStatusesTool,
    tools.createIssueTool,
    tools.updateIssueTool,
    tools.addCommentTool,
    tools.getProjectInfoTool,
    tools.createSubtaskTool,
    tools.getCreateMetaTool,
    tools.getCustomFieldsTool,
    tools.createIssueLinkTool,
  ];

• src/types/tools.ts:13-22 (schema)

  Zod schema (GetIssueInputSchema) for internal input validation in the handler.

  export const GetIssueInputSchema = z.object({
    issueKey: z
      .string()
      .min(1)
      .describe(
        'Issue key or full Jira URL (e.g., PROJECT-123 or https://your.atlassian.net/browse/PROJECT-123)'
      ),
    expand: z.array(z.string()).optional().describe('Additional issue details to include'),
    fields: z.array(z.string()).optional().describe('Specific fields to retrieve'),
  });

• src/utils/api-helpers.ts:219-243 (helper)

  API helper function that makes the actual Jira REST API call to retrieve the issue.

  export async function getIssue(
    issueKey: string,
    options: {
      expand?: string[];
      fields?: string[];
    } = {}
  ): Promise<JiraIssue> {
    const params: Record<string, any> = {};
  
    if (options.expand) {
      params.expand = options.expand.join(',');
    }
  
    if (options.fields) {
      params.fields = options.fields.join(',');
    }
  
    const config: AxiosRequestConfig = {
      method: 'GET',
      url: `/issue/${issueKey}`,
      params,
    };
  
    return await makeJiraRequest<JiraIssue>(config);
  }