List Board Sprints

Instructions

Implementation Reference

• src/server.ts:376-407 (registration)

  Registration of the 'list_board_sprints' MCP tool, including schema and inline handler implementation.

  mcp.registerTool(
    "list_board_sprints",
    {
      title: "List Board Sprints",
      description: "List sprints for a given board with optional state filter.",
      inputSchema: {
        boardId: z.number().int().describe("Board ID"),
        state: z.enum(["active","future","closed"]).optional().describe("Sprint state filter"),
        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)"),
      },
    },
    async (args: { boardId: number; state?: "active"|"future"|"closed"; startAt?: number; maxResults?: number }) => {
      try {
        const params = new URLSearchParams();
        if (args.state) params.set("state", args.state);
        if (typeof args.startAt === "number") params.set("startAt", String(args.startAt));
        if (typeof args.maxResults === "number") params.set("maxResults", String(args.maxResults));
        const url = `${JIRA_URL}/rest/agile/1.0/board/${args.boardId}/sprint${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 sprints for board ${args.boardId}: ${response.status} ${response.statusText}\n${errorText}` }], isError: true };
        }
        const data = await response.json() as any;
        const sprints = (data.values || []).map((s: any) => ({ id: s.id, name: s.name, state: s.state, startDate: s.startDate, endDate: s.endDate, completeDate: s.completeDate }));
        return { content: [{ type: "text", text: `Found ${data.total ?? sprints.length} sprints (showing ${sprints.length}).` }], structuredContent: { total: data.total ?? sprints.length, startAt: data.startAt ?? 0, maxResults: data.maxResults ?? sprints.length, boardId: args.boardId, sprints, raw: data } };
      } catch (error) {
        return { content: [{ type: "text", text: `Error listing sprints for board ${args.boardId}: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

• src/server.ts:388-406 (handler)

  Handler function that fetches and processes sprints for a specified Jira board using the REST Agile API, handling pagination and errors.

  async (args: { boardId: number; state?: "active"|"future"|"closed"; startAt?: number; maxResults?: number }) => {
    try {
      const params = new URLSearchParams();
      if (args.state) params.set("state", args.state);
      if (typeof args.startAt === "number") params.set("startAt", String(args.startAt));
      if (typeof args.maxResults === "number") params.set("maxResults", String(args.maxResults));
      const url = `${JIRA_URL}/rest/agile/1.0/board/${args.boardId}/sprint${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 sprints for board ${args.boardId}: ${response.status} ${response.statusText}\n${errorText}` }], isError: true };
      }
      const data = await response.json() as any;
      const sprints = (data.values || []).map((s: any) => ({ id: s.id, name: s.name, state: s.state, startDate: s.startDate, endDate: s.endDate, completeDate: s.completeDate }));
      return { content: [{ type: "text", text: `Found ${data.total ?? sprints.length} sprints (showing ${sprints.length}).` }], structuredContent: { total: data.total ?? sprints.length, startAt: data.startAt ?? 0, maxResults: data.maxResults ?? sprints.length, boardId: args.boardId, sprints, raw: data } };
    } catch (error) {
      return { content: [{ type: "text", text: `Error listing sprints for board ${args.boardId}: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
    }
  }

• src/server.ts:378-386 (schema)

  Input schema definition using Zod for validating tool arguments: board ID, optional state filter, and pagination parameters.

  {
    title: "List Board Sprints",
    description: "List sprints for a given board with optional state filter.",
    inputSchema: {
      boardId: z.number().int().describe("Board ID"),
      state: z.enum(["active","future","closed"]).optional().describe("Sprint state filter"),
      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)"),
    },