List Boards

Instructions

Implementation Reference

• src/server.ts:353-372 (handler)

  Handler function that implements the list_boards tool by querying the Jira Agile API endpoint /rest/agile/1.0/board with optional filters for type, project, pagination, processes the response, and returns formatted content and structured data.

  async (args: { type?: "scrum"|"kanban"; projectKeyOrId?: string; startAt?: number; maxResults?: number }) => {
    try {
      const params = new URLSearchParams();
      if (args.type) params.set("type", args.type);
      if (args.projectKeyOrId) params.set("projectKeyOrId", args.projectKeyOrId);
      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${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 boards: ${response.status} ${response.statusText}\n${errorText}` }], isError: true };
      }
      const data = await response.json() as any;
      const boards = (data.values || []).map((b: any) => ({ id: b.id, name: b.name, type: b.type, location: b.location }));
      return { content: [{ type: "text", text: `Found ${data.total ?? boards.length} boards (showing ${boards.length}).` }], structuredContent: { total: data.total ?? boards.length, startAt: data.startAt ?? 0, maxResults: data.maxResults ?? boards.length, boards, raw: data } };
    } catch (error) {
      return { content: [{ type: "text", text: `Error listing boards: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
    }
  }

• src/server.ts:346-351 (schema)

  Input schema defining the parameters for the list_boards tool using Zod validation: optional type (scrum/kanban), projectKeyOrId, startAt, and maxResults.

  inputSchema: {
    type: z.enum(["scrum","kanban"]).optional().describe("Board type filter"),
    projectKeyOrId: z.string().optional().describe("Filter boards by project key or 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)"),
  },

• src/server.ts:341-373 (registration)

  Registration of the list_boards tool using mcp.registerTool, including name, tool specification (title, description, schema), and handler function reference.

  mcp.registerTool(
    "list_boards",
    {
      title: "List Boards",
      description: "List Jira boards with optional type and project filter.",
      inputSchema: {
        type: z.enum(["scrum","kanban"]).optional().describe("Board type filter"),
        projectKeyOrId: z.string().optional().describe("Filter boards by project key or 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)"),
      },
    },
    async (args: { type?: "scrum"|"kanban"; projectKeyOrId?: string; startAt?: number; maxResults?: number }) => {
      try {
        const params = new URLSearchParams();
        if (args.type) params.set("type", args.type);
        if (args.projectKeyOrId) params.set("projectKeyOrId", args.projectKeyOrId);
        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${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 boards: ${response.status} ${response.statusText}\n${errorText}` }], isError: true };
        }
        const data = await response.json() as any;
        const boards = (data.values || []).map((b: any) => ({ id: b.id, name: b.name, type: b.type, location: b.location }));
        return { content: [{ type: "text", text: `Found ${data.total ?? boards.length} boards (showing ${boards.length}).` }], structuredContent: { total: data.total ?? boards.length, startAt: data.startAt ?? 0, maxResults: data.maxResults ?? boards.length, boards, raw: data } };
      } catch (error) {
        return { content: [{ type: "text", text: `Error listing boards: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

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

  Helper function used by the list_boards handler (and others) to generate HTTP headers with Basic Auth for Jira API requests.

  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',
    };
  }