Jira MCP Server

Instructions

Implementation Reference

• src/tools/list-issues-from-sprint.ts:52-74 (handler)

  The main handler function that constructs the Jira API URL for fetching issues from a specific sprint on a board, makes the request, parses the response, and returns the issues.

  export async function listIssuesFromSprint(input: ListIssuesFromSprintInput) {
    const url = new URL(
      `/rest/agile/1.0/board/${input.boardId}/sprint/${input.sprintId}/issue`,
      env.JIRA_BASE_URL,
    );
  
    if (input.expand) url.searchParams.set("expand", input.expand);
    if (input.startAt) url.searchParams.set("startAt", input.startAt.toString());
    if (input.maxResults)
      url.searchParams.set("maxResults", input.maxResults.toString());
  
    const json = await $jiraJson(url.toString());
  
    if (json.isErr()) return err(json.error);
  
    const result = listIssuesFromSprintSchema.safeParse(json.value);
  
    if (!result.success) {
      return err(new Error("Invalid response from Jira"));
    }
  
    return ok(result.data);
  }

• src/tools/list-issues-from-sprint.ts:19-38 (schema)

  Zod input schema defining parameters for the list_issues_from_sprint tool: sprintId, boardId, optional maxResults, startAt, expand.

  export const listIssuesFromSprintInputSchema = z.object({
    sprintId: z.string().describe("The ID of the sprint"),
    boardId: z.string().describe("The ID of the board"),
    maxResults: z
      .number()
      .optional()
      .describe(
        "The maximum number of results to return, (default: 5, max: 100)",
      ),
    startAt: z
      .number()
      .optional()
      .describe("The starting index of the returned boards"),
    expand: z
      .string()
      .optional()
      .describe(
        "Use this parameter to include additional information in the response. This parameter accepts a comma-separated list. Expand options include: `schema` and `names`. Comma separated list of options.",
      ),
  });

• src/tools/list-issues-from-sprint.ts:40-46 (registration)

  Tool registration object defining the name, description, and input schema for the MCP tool.

  export const LIST_ISSUES_FROM_SPRINT_TOOL: Tool = {
    name: "list_issues_from_sprint",
    description: "List issues from a sprint",
    inputSchema: zodToJsonSchema(
      listIssuesFromSprintInputSchema,
    ) as Tool["inputSchema"],
  };

• src/app.ts:39-48 (registration)

  Array of all tools including LIST_ISSUES_FROM_SPRINT_TOOL, used by the MCP server for listing available tools.

  export const tools = [
    // list
    LIST_PROJECTS_TOOL,
    LIST_BOARDS_TOOL,
    LIST_SPRINTS_FROM_BOARD_TOOL,
    LIST_ISSUES_FROM_SPRINT_TOOL,
  
    // create
    CREATE_ISSUE_TOOL,
  ] satisfies Tool[];

• src/app.ts:61-86 (handler)

  Top-level handler dispatch for the tool: validates input, calls listIssuesFromSprint, handles errors, and formats response.

  if (name === LIST_ISSUES_FROM_SPRINT_TOOL.name) {
    const input = listIssuesFromSprintInputSchema.safeParse(args);
  
    if (!input.success) {
      return {
        isError: true,
        content: [{ type: "text", text: "Invalid input" }],
      };
    }
  
    const result = await listIssuesFromSprint(input.data);
  
    if (result.isErr()) {
      console.error(result.error.message);
      return {
        isError: true,
        content: [{ type: "text", text: "An error occurred" }],
      };
    }
  
    return {
      content: [
        { type: "text", text: JSON.stringify(result.value, null, 2) },
      ],
    };
  }