List Jira Projects

Instructions

Implementation Reference

• src/server.ts:159-180 (handler)

  The handler function for the 'list_jira_projects' tool. It constructs a search query for Jira projects using optional parameters, fetches from the Jira API, processes the response into a list of projects, and returns formatted text content along with structured data including total count and pagination info.

  async (args: { query?: string; startAt?: number; maxResults?: number }) => {
    try {
      const params = new URLSearchParams();
      if (args.query) params.set("query", args.query);
      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/api/3/project/search${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 projects: ${response.status} ${response.statusText}\n${errorText}` }], isError: true };
      }
      const data = await response.json() as any;
      const projects = (data.values || []).map((p: any) => ({ id: p.id, key: p.key, name: p.name, lead: p.lead?.displayName, projectType: p.projectTypeKey }));
      return {
        content: [{ type: "text", text: `Found ${data.total ?? projects.length} projects (showing ${projects.length}).` }],
        structuredContent: { total: data.total ?? projects.length, startAt: data.startAt ?? 0, maxResults: data.maxResults ?? projects.length, projects },
      };
    } catch (error) {
      return { content: [{ type: "text", text: `Error listing projects: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
    }
  }

• src/server.ts:150-157 (schema)

  The schema definition for the 'list_jira_projects' tool, including title, description, and Zod-based input schema for optional query, startAt, and maxResults parameters.

  {
    title: "List Jira Projects",
    description: "List accessible Jira projects with pagination and optional query.",
    inputSchema: {
      query: z.string().optional().describe("Optional search query for project key/name"),
      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:148-181 (registration)

  The full registration of the 'list_jira_projects' tool via mcp.registerTool, including the tool name, schema, and handler implementation.

  mcp.registerTool(
    "list_jira_projects",
    {
      title: "List Jira Projects",
      description: "List accessible Jira projects with pagination and optional query.",
      inputSchema: {
        query: z.string().optional().describe("Optional search query for project key/name"),
        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: { query?: string; startAt?: number; maxResults?: number }) => {
      try {
        const params = new URLSearchParams();
        if (args.query) params.set("query", args.query);
        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/api/3/project/search${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 projects: ${response.status} ${response.statusText}\n${errorText}` }], isError: true };
        }
        const data = await response.json() as any;
        const projects = (data.values || []).map((p: any) => ({ id: p.id, key: p.key, name: p.name, lead: p.lead?.displayName, projectType: p.projectTypeKey }));
        return {
          content: [{ type: "text", text: `Found ${data.total ?? projects.length} projects (showing ${projects.length}).` }],
          structuredContent: { total: data.total ?? projects.length, startAt: data.startAt ?? 0, maxResults: data.maxResults ?? projects.length, projects },
        };
      } catch (error) {
        return { content: [{ type: "text", text: `Error listing projects: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
      }
    }
  );

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

  Helper function used by the tool 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',
    };
  }