jira_list_projects

Instructions

Implementation Reference

• src/tools/listProjects.ts:49-106 (handler)

  The main handler function that executes the tool logic: validates credentials, calls Jira API to list projects, formats as Markdown table, handles errors.

  export async function listProjects(args: any) {
      const validatedArgs = await JiraApiRequestSchema.validate(args);
  
      const jiraHost = validatedArgs.jiraHost || process.env.JIRA_HOST;
      const email = validatedArgs.email || process.env.JIRA_EMAIL;
      const apiToken = validatedArgs.apiToken || process.env.JIRA_API_TOKEN;
  
      if (!jiraHost || !email || !apiToken) {
          throw new Error('Missing required authentication credentials. Please provide jiraHost, email, and apiToken.');
      }
  
      validateCredentials(jiraHost, email, apiToken);
  
      const authHeader = createAuthHeader(email, apiToken);
  
      try {
          const response = await axios.get(`https://${jiraHost}/rest/api/3/project`, {
              headers: {
                  'Authorization': authHeader,
                  'Accept': 'application/json',
              },
          });
  
          const projects = response.data;
  
          let formattedResponse = `# Jira Projects\n\n`;
          formattedResponse += `Total projects: ${projects.length}\n\n`;
  
          if (Array.isArray(projects) && projects.length > 0) {
              formattedResponse += `| Project Key | Name | Type | Lead |\n`;
              formattedResponse += `|------------|------|------|------|\n`;
  
              projects.forEach((project: any) => {
                  formattedResponse += `| ${project.key} | ${project.name} | ${project.projectTypeKey || 'N/A'} | ${project.lead?.displayName || 'Unknown'} |\n`;
              });
          } else {
              formattedResponse += "No projects found or you don't have access to any projects.";
          }
  
          return {
              content: [{ type: "text", text: formattedResponse }],
              isError: false,
          };
      } catch (error: any) {
          let errorMsg = "An error occurred while listing projects.";
  
          if (error.response) {
              errorMsg = `Error ${error.response.status}: ${error.response.data?.errorMessages?.join(', ') || error.message}`;
          } else if (error.message) {
              errorMsg = error.message;
          }
  
          return {
              content: [{ type: "text", text: `# Error\n\n${errorMsg}` }],
              isError: true,
          };
      }
  }

• src/validators/index.ts:9-32 (schema)

  Yup validation schema for basic Jira API requests (jiraHost, email, apiToken), used to validate inputs for jira_list_projects.

  export const JiraApiRequestSchema = yup.object({
      jiraHost: yup.string()
          .default(process.env.JIRA_HOST || "")
          .test(
              'check-jira-host',
              'Jira host is required and must be a valid domain (e.g., "company.atlassian.net")',
              (value) => !!value && value.trim().length > 0
          ),
      email: yup.string()
          .email('Invalid email format. Please provide a valid email associated with your Jira account')
          .default(process.env.JIRA_EMAIL || "")
          .test(
              'check-email',
              'Email is required for Jira authentication',
              (value) => !!value && value.trim().length > 0
          ),
      apiToken: yup.string()
          .default(process.env.JIRA_API_TOKEN || "")
          .test(
              'check-api-token',
              'API token is required for Jira authentication',
              (value) => !!value && value.trim().length > 0
          ),
  });

• src/handlers/handlerTools.ts:28-31 (registration)

  Registration of the jira_list_projects tool in the toolConfigs mapping, linking schema and handler for execution in handleCallTool.

  jira_list_projects: {
      schema: JiraApiRequestSchema,
      handler: listProjects
  },

• src/handlers/handlerListTools.ts:36-46 (registration)

  Tool description registration in handleListTools response, providing name, description, and input schema for MCP tool listing.

  {
      name: "jira_list_projects",
      description: "Lists all Jira projects the user has access to",
      inputSchema: {
          type: "object",
          properties: {
              ...getCommonJiraProperties(),
          },
          required: [],
      },
  },

• src/tools/listProjects.ts:12-36 (schema)

  Tool description object exported from the tool file, including name, description, and inline input schema.

  export const listProjectsToolDescription = {
      name: "jira_list_projects",
      description: "Lists all Jira projects the user has access to",
      inputSchema: {
          type: "object",
          properties: {
              jiraHost: {
                  type: "string",
                  description: "The Jira host URL (e.g., 'your-domain.atlassian.net')",
                  default: process.env.JIRA_HOST || "",
              },
              email: {
                  type: "string",
                  description: "Email address associated with the Jira account",
                  default: process.env.JIRA_EMAIL || "",
              },
              apiToken: {
                  type: "string",
                  description: "API token for Jira authentication",
                  default: process.env.JIRA_API_TOKEN || "",
              },
          },
          required: [],
      },
  };