GHAS MCP server (GitHub Advanced Security)

Instructions

Implementation Reference

• src/operations/security.ts:80-95 (handler)

  The core handler function that validates access token and repository permissions, then fetches and returns the list of code scanning alerts using the GitHub Octokit API.

  export async function listCodeScanningAlerts(owner: string, repo: string) {
      const octokit = await validateAccessToken(owner, repo);
  
      console.log(`Fetching code scanning alerts for repository: [${owner}/${repo}]`);
      try {
          const { data } = await octokit.codeScanning.listAlertsForRepo({
              owner,
              repo
          });
          console.log(`Fetched [${data.length}] code scanning alerts.`);
          return data;
      } catch (error) {
          console.error("Error fetching code scanning alerts:", error);
          throw error;
      }
  }

• src/index.ts:49-55 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining the tool name, description, and input schema (owner and repo strings).

      name: "list_code_scanning_alerts",
      description: "List the current GitHub Advanced Security code scanning alerts for a repository",
      inputSchema: zodToJsonSchema(z.object({
          owner: z.string(),
          repo: z.string(),
      })),
  },

• src/index.ts:82-88 (registration)

  Dispatch logic in the CallToolRequestSchema handler that validates input arguments, calls the handler function, and formats the response as JSON text.

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

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

  Helper function to retrieve and validate the GitHub token (from env or gh CLI), create Octokit instance, and check admin permissions on the repository.

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