jira_check_user_issues

Instructions

Implementation Reference

• src/tools/checkUserIssues.ts:60-216 (handler)

  Main handler function that validates input, authenticates with Jira API, retrieves project roles to check user membership, and if member, fetches and lists their assigned issues in a formatted Markdown response.

  export async function checkUserIssues(args: any) {
      const validatedArgs = await JiraCheckUserIssuesRequestSchema.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;
      const projectKey = validatedArgs.projectKey;
      const userName = validatedArgs.userName;
  
      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);
  
      const rolesResponse = await axios.get(`https://${jiraHost}/rest/api/3/project/${projectKey}/role`, {
          headers: {
              'Authorization': authHeader,
              'Accept': 'application/json',
          },
      });
  
      const projectRoles = rolesResponse.data;
  
      let formattedResponse = `# Checking User "${userName}" in Project "${projectKey}"\n\n`;
  
      const allMembers = new Map<string, {
          displayName: string;
          type: string;
          email: string;
          roles: string[];
      }>();
  
      let userFound = false;
  
      if (Object.keys(projectRoles).length > 0) {
          const roleDetailsPromises: Promise<{
              roleName: string;
              data: ProjectRole;
          }>[] = [];
  
          for (const [roleName, roleUrl] of Object.entries(projectRoles)) {
              if (typeof roleUrl === 'string') {
                  const roleId = roleUrl.split('/').pop();
                  const detailUrl = `https://${jiraHost}/rest/api/3/project/${projectKey}/role/${roleId}`;
  
                  roleDetailsPromises.push(
                      axios.get<ProjectRole>(detailUrl, {
                          headers: {
                              'Authorization': authHeader,
                              'Accept': 'application/json',
                          },
                      }).then(response => ({
                          roleName,
                          data: response.data
                      }))
                  );
              }
          }
  
          const roleDetails = await Promise.all(roleDetailsPromises);
  
          for (const { roleName, data } of roleDetails) {
              if (data.actors && data.actors.length > 0) {
                  data.actors.forEach((actor: RoleActor) => {
                      if (actor.displayName) {
                          if (!allMembers.has(actor.displayName)) {
                              allMembers.set(actor.displayName, {
                                  displayName: actor.displayName,
                                  type: actor.type,
                                  email: actor.emailAddress || 'N/A',
                                  roles: [roleName]
                              });
                          } else {
                              const member = allMembers.get(actor.displayName);
                              if (member) {
                                  member.roles.push(roleName);
                              }
                          }
  
                          if (actor.displayName.toLowerCase() === userName.toLowerCase()) {
                              userFound = true;
                          }
                      }
                  });
              }
          }
  
          formattedResponse += `## Step 1: Checking if user "${userName}" is a member of project "${projectKey}"\n\n`;
  
          if (userFound) {
              const userInfo = allMembers.get(Array.from(allMembers.keys()).find(
                  name => name.toLowerCase() === userName.toLowerCase()
              ) || "");
  
              formattedResponse += `✅ User "${userName}" found in project with the following roles: ${userInfo?.roles.join(', ')}\n\n`;
  
              formattedResponse += `## Step 2: Fetching issues assigned to "${userName}" in project "${projectKey}"\n\n`;
  
              const jql = `project = "${projectKey}" AND assignee = "${userName}" ORDER BY created DESC`;
  
              const response = await axios.get(`https://${jiraHost}/rest/api/3/search`, {
                  params: {
                      jql,
                      maxResults: 50,
                      fields: "summary,status,assignee,created,issuetype,priority",
                  },
                  headers: {
                      'Authorization': authHeader,
                      'Accept': 'application/json',
                  },
              });
  
              const searchResults = response.data;
              const issues = searchResults.issues || [];
  
              if (issues.length > 0) {
                  formattedResponse += "| Issue Key | Summary | Status | Type | Created |\n";
                  formattedResponse += "|-----------|---------|--------|------|--------|\n";
  
                  issues.forEach((issue: any) => {
                      const key = issue.key;
                      const summary = issue.fields.summary || 'No summary';
                      const status = issue.fields.status?.name || 'Unknown';
                      const type = issue.fields.issuetype?.name || 'Unknown';
                      const created = new Date(issue.fields.created).toLocaleDateString();
  
                      formattedResponse += `| ${key} | ${summary} | ${status} | ${type} | ${created} |\n`;
                  });
              } else {
                  formattedResponse += "No issues found assigned to this user in the project.";
              }
          } else {
              formattedResponse += `❌ User "${userName}" is NOT a member of project "${projectKey}". No issues will be fetched.\n\n`;
              formattedResponse += "### Available Project Members:\n\n";
              formattedResponse += "| Name | Roles |\n";
              formattedResponse += "|------|-------|\n";
  
              allMembers.forEach(member => {
                  if (member.type !== "atlassian-user-role-actor" ||
                      (!member.displayName.includes("for Jira") &&
                          !member.displayName.includes("Atlassian"))) {
                      formattedResponse += `| ${member.displayName} | ${member.roles.join(', ')} |\n`;
                  }
              });
          }
      } else {
          formattedResponse += "⚠️ No project roles found. Unable to determine project membership.";
      }
  
      return {
          content: [{ type: "text", text: formattedResponse }],
          isError: false,
      };
  }

• src/validators/index.ts:79-87 (schema)

  Yup validation schema extending JiraApiRequestSchema with required projectKey and userName fields, ensuring proper format and presence.

  export const JiraCheckUserIssuesRequestSchema = JiraApiRequestSchema.shape({
      projectKey: yup.string()
          .required("Project key is required")
          .matches(/^[A-Z][A-Z0-9_]+$/, "Invalid project key format. Only uppercase letters, numbers, and underscores are allowed"),
      userName: yup.string()
          .required("Username is required")
          .min(2, "Username must be at least 2 characters long"),
  });

• src/handlers/handlerTools.ts:44-47 (registration)

  Registers the 'jira_check_user_issues' tool in the toolConfigs object, associating it with its schema for validation and handler function for execution in handleCallTool.

  jira_check_user_issues: {
      schema: JiraCheckUserIssuesRequestSchema,
      handler: checkUserIssues
  },

• src/handlers/handlerListTools.ts:96-114 (registration)

  Registers the tool description for the MCP listTools handler, providing name, description, and inputSchema for tool discovery.

  {
      name: "jira_check_user_issues",
      description: "Checks if a user is a member of a project and lists their assigned issues",
      inputSchema: {
          type: "object",
          properties: {
              ...getCommonJiraProperties(),
              projectKey: {
                  type: "string",
                  description: "The Jira project key (e.g., 'PROJECT')",
              },
              userName: {
                  type: "string",
                  description: "The display name of the user to check for in the project",
              },
          },
          required: ["projectKey", "userName"],
      },
  },