Jira MCP Server

Instructions

Implementation Reference

• src/server.ts:422-440 (handler)

  The handler function that executes the tool logic: fetches issues from the Jira Agile API for a given sprint ID, handles pagination and optional JQL query, processes the response into structured content.

  async (args: { sprintId: number; startAt?: number; maxResults?: number; jql?: string }) => {
    try {
      const params = new URLSearchParams();
      if (typeof args.startAt === "number") params.set("startAt", String(args.startAt));
      if (typeof args.maxResults === "number") params.set("maxResults", String(args.maxResults));
      if (args.jql) params.set("jql", args.jql);
      const url = `${JIRA_URL}/rest/agile/1.0/sprint/${args.sprintId}/issue${params.toString() ? `?${params.toString()}` : ""}`;
      const response = await fetch(url, { method: "GET", headers: getJiraHeaders() });
      if (!response.ok) {
        const errorText = await response.text();
        return { content: [{ type: "text", text: `Failed to list sprint issues: ${response.status} ${response.statusText}\n${errorText}` }], isError: true };
      }
      const data = await response.json() as any;
      const items = (data.issues || []).map((it: any) => ({ key: it.key, summary: it.fields?.summary, status: it.fields?.status?.name, assignee: it.fields?.assignee?.displayName, priority: it.fields?.priority?.name, type: it.fields?.issuetype?.name, updated: it.fields?.updated, url: `${JIRA_URL}/browse/${it.key}` }));
      return { content: [{ type: "text", text: `Found ${data.total ?? items.length} issues in sprint ${args.sprintId} (showing ${items.length}).` }], structuredContent: { sprintId: args.sprintId, total: data.total ?? items.length, startAt: data.startAt ?? 0, maxResults: data.maxResults ?? items.length, issues: items, raw: data } };
    } catch (error) {
      return { content: [{ type: "text", text: `Error listing sprint issues: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
    }
  }

• src/server.ts:412-421 (schema)

  Input schema definition using Zod for the tool's parameters: sprintId (required), optional pagination and JQL filter.

  {
    title: "List Sprint Issues",
    description: "List issues in a given sprint with pagination.",
    inputSchema: {
      sprintId: z.number().int().describe("Sprint ID"),
      startAt: z.number().int().min(0).optional().describe("Pagination start index (default 0)"),
      maxResults: z.number().int().min(1).max(100).optional().describe("Page size (1-100, default 50)"),
      jql: z.string().optional().describe("Optional additional JQL to filter sprint issues"),
    },
  },

• src/server.ts:410-441 (registration)

  MCP tool registration call including the tool name, schema, and inline handler function.

  mcp.registerTool(
    "list_sprint_issues",
    {
      title: "List Sprint Issues",
      description: "List issues in a given sprint with pagination.",
      inputSchema: {
        sprintId: z.number().int().describe("Sprint ID"),
        startAt: z.number().int().min(0).optional().describe("Pagination start index (default 0)"),
        maxResults: z.number().int().min(1).max(100).optional().describe("Page size (1-100, default 50)"),
        jql: z.string().optional().describe("Optional additional JQL to filter sprint issues"),
      },
    },
    async (args: { sprintId: number; startAt?: number; maxResults?: number; jql?: string }) => {
      try {
        const params = new URLSearchParams();
        if (typeof args.startAt === "number") params.set("startAt", String(args.startAt));
        if (typeof args.maxResults === "number") params.set("maxResults", String(args.maxResults));
        if (args.jql) params.set("jql", args.jql);
        const url = `${JIRA_URL}/rest/agile/1.0/sprint/${args.sprintId}/issue${params.toString() ? `?${params.toString()}` : ""}`;
        const response = await fetch(url, { method: "GET", headers: getJiraHeaders() });
        if (!response.ok) {
          const errorText = await response.text();
          return { content: [{ type: "text", text: `Failed to list sprint issues: ${response.status} ${response.statusText}\n${errorText}` }], isError: true };
        }
        const data = await response.json() as any;
        const items = (data.issues || []).map((it: any) => ({ key: it.key, summary: it.fields?.summary, status: it.fields?.status?.name, assignee: it.fields?.assignee?.displayName, priority: it.fields?.priority?.name, type: it.fields?.issuetype?.name, updated: it.fields?.updated, url: `${JIRA_URL}/browse/${it.key}` }));
        return { content: [{ type: "text", text: `Found ${data.total ?? items.length} issues in sprint ${args.sprintId} (showing ${items.length}).` }], structuredContent: { sprintId: args.sprintId, total: data.total ?? items.length, startAt: data.startAt ?? 0, maxResults: data.maxResults ?? items.length, issues: items, raw: data } };
      } catch (error) {
        return { content: [{ type: "text", text: `Error listing sprint issues: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

• src/server.ts:37-44 (helper)

  Shared helper function to generate authentication headers for Jira API requests, used by the list_sprint_issues handler.

  function getJiraHeaders(): Record<string, string> {
    const auth = Buffer.from(`${JIRA_EMAIL}:${JIRA_API_TOKEN}`).toString('base64');
    return {
      'Authorization': `Basic ${auth}`,
      'Accept': 'application/json',
      'Content-Type': 'application/json',
    };
  }