GHAS MCP server (GitHub Advanced Security)

Instructions

Implementation Reference

• src/operations/security.ts:127-143 (handler)

  The core handler function that validates access token and uses Octokit to fetch and return Dependabot alerts for the specified GitHub repository.

  export async function listDependabotAlerts(owner: string, repo: string) {
      const octokit = await validateAccessToken(owner, repo);
  
      console.log(`Fetching Dependabot alerts for repository: [${owner}/${repo}]`);
      console.log("Starting to fetch Dependabot alerts...");
      try {
          const { data } = await octokit.rest.dependabot.listAlertsForRepo({
              owner,
              repo
          });
          console.log(`Fetched [${data.length}] Dependabot alerts.`);
          return data;
      } catch (error) {
          console.error("Error fetching Dependabot alerts:", error);
          throw error;
      }
  }

• src/index.ts:64-71 (registration)

  Registers the tool in the ListTools response with name, description, and Zod-based input schema for owner and repo.

  {
      name: "list_dependabot_alerts",
      description: "List the current GitHub Dependabot alerts for a repository",
      inputSchema: zodToJsonSchema(z.object({
          owner: z.string(),
          repo: z.string(),
      })),
  },

• src/index.ts:96-102 (registration)

  Dispatches the tool call by parsing arguments with Zod schema and invoking the listDependabotAlerts handler, returning JSON-formatted alerts.

  case "list_dependabot_alerts": {
      const args = z.object({ owner: z.string(), repo: z.string() }).parse(request.params.arguments);
      const alerts = await listDependabotAlerts(args.owner, args.repo);
      return {
          content: [{ type: "text", text: JSON.stringify(alerts, null, 2) }],
      };
  }

• src/index.ts:67-70 (schema)

  Zod schema definition for the tool's input parameters: owner and repo strings.

  inputSchema: zodToJsonSchema(z.object({
      owner: z.string(),
      repo: z.string(),
  })),

• src/operations/security.ts:28-72 (helper)

  Helper function called by the handler to validate GitHub token access and permissions for the repository, returning an authenticated Octokit instance.

  async function validateAccessToken(owner: string, repo: string): Promise<Octokit> {
  
      console.log("Validating GitHub Personal Access Token...");
  
      let authToken = null;
      if (process.env.GITHUB_PERSONAL_ACCESS_TOKEN_USE_GHCLI) {
          const token = getGitHubToken();
          authToken = token;
      } else {
          if (!process.env.GITHUB_PERSONAL_ACCESS_TOKEN) {
              throw new Error("GITHUB_PERSONAL_ACCESS_TOKEN is not set in environment variables. This is needed to be able to find code scanning alerts.");
          } else {
              console.log(`GITHUB_PERSONAL_ACCESS_TOKEN is set in environment variables with length: [${process.env.GITHUB_PERSONAL_ACCESS_TOKEN.length}]`);
              authToken = process.env.GITHUB_PERSONAL_ACCESS_TOKEN.trim();
          }
      }
  
      const octokit = new Octokit({
          auth: authToken
      });
  
      // Validate token access and scope
      try {
          console.log("Starting to validate token access and scope...");
          const user = await octokit.rest.users.getAuthenticated();
          console.log(`Authenticated as: [${user.data.login}]`);
          const repoInfo = await octokit.rest.repos.get({
              owner,
              repo
          });
  
          console.log(`Repository information fetched: [${repoInfo.data.name}]`);
          if (!repoInfo.data.permissions || !repoInfo.data.permissions.admin) {
              throw new Error("The provided token does not have admin access to the repository. Admin access is required to fetch security information.");
          } else {
              console.log("Token has admin access to the repository.");
          }
          console.log("Token has sufficient permissions for the repository.");
      } catch (error) {
          console.error("Error validating token or repository access:", error);
          throw new Error("Failed to validate token or repository access. Ensure the token has the necessary scopes and permissions.");
      }
  
      return octokit;
  }