GitHub Notifications MCP Server

Instructions

Implementation Reference

• src/tools/list-repo-notifications.ts:26-81 (handler)

  The handler function that fetches repository notifications from the GitHub API, handles pagination and errors, and formats the response.

  export async function listRepoNotificationsHandler(args: z.infer<typeof listRepoNotificationsSchema>) {
    try {
      const perPage = args.per_page || 30;
      const page = args.page || 1;
      
      // Make request to GitHub API
      const notifications = await githubGet<NotificationResponse[]>(`/repos/${args.owner}/${args.repo}/notifications`, {
        params: {
          all: args.all,
          participating: args.participating,
          since: args.since,
          before: args.before,
          page: page,
          per_page: perPage,
        }
      });
  
      // If no notifications, return simple message
      if (notifications.length === 0) {
        return {
          content: [{
            type: "text",
            text: `No notifications found for repository ${args.owner}/${args.repo} with the given criteria.`
          }]
        };
      }
  
      // Format the notifications for better readability
      const formattedNotifications = notifications.map(formatNotification).join("\n\n");
      
      // Check for pagination - simplified approach without headers
      let paginationInfo = "";
      
      if (notifications.length === perPage) {
        paginationInfo = "\n\nMore notifications may be available. You can view the next page by specifying 'page: " + 
          (page + 1) + "' in the request.";
      }
  
      return {
        content: [{
          type: "text",
          text: `${notifications.length} notifications found for repository ${args.owner}/${args.repo}:
  
  ${formattedNotifications}${paginationInfo}`
        }]
      };
    } catch (error) {
      return {
        isError: true,
        content: [{
          type: "text",
          text: formatError(`Failed to fetch notifications for repository ${args.owner}/${args.repo}`, error)
        }]
      };
    }
  }

• src/tools/list-repo-notifications.ts:12-21 (schema)

  Zod schema defining the input parameters for the list-repo-notifications tool, including repository details and filtering options.

  export const listRepoNotificationsSchema = z.object({
    owner: z.string().describe("The account owner of the repository"),
    repo: z.string().describe("The name of the repository"),
    all: z.boolean().optional().describe("If true, show notifications marked as read"),
    participating: z.boolean().optional().describe("If true, only shows notifications where user is directly participating"),
    since: z.string().optional().describe("ISO 8601 timestamp - only show notifications updated after this time"),
    before: z.string().optional().describe("ISO 8601 timestamp - only show notifications updated before this time"),
    page: z.number().optional().describe("Page number for pagination"),
    per_page: z.number().optional().describe("Number of results per page (max 100)")
  });

• src/tools/list-repo-notifications.ts:86-93 (registration)

  Registers the tool with the MCP server by calling server.tool with the name, description, schema, and handler.

  export function registerListRepoNotificationsTool(server: any) {
    server.tool(
      "list-repo-notifications",
      "List GitHub notifications for a specific repository",
      listRepoNotificationsSchema.shape,
      listRepoNotificationsHandler
    );
  }

• src/server.ts:46-46 (registration)

  Invokes the registration function during server initialization to add the tool.

  registerListRepoNotificationsTool(server);