list-notifications
Retrieve GitHub notifications for the authenticated user, with options to filter by read status, participation, time range, and pagination.
Instructions
List GitHub notifications for the authenticated user
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | If true, show notifications marked as read | |
| participating | No | If true, only shows notifications where user is directly participating | |
| since | No | ISO 8601 timestamp - only show notifications updated after this time | |
| before | No | ISO 8601 timestamp - only show notifications updated before this time | |
| page | No | Page number for pagination | |
| per_page | No | Number of results per page (max 100) |
Implementation Reference
- src/tools/list-notifications.ts:24-79 (handler)The handler function that fetches GitHub notifications using the GitHub API, handles parameters like all, participating, since, before, page, per_page, formats them using formatNotification, handles pagination info, and returns formatted text or error.export async function listNotificationsHandler(args: z.infer<typeof listNotificationsSchema>) { try { const perPage = args.per_page || 50; const page = args.page || 1; // Make request to GitHub API const notifications = await githubGet<NotificationResponse[]>("/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 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: ${formattedNotifications}${paginationInfo}` }] }; } catch (error) { return { isError: true, content: [{ type: "text", text: formatError("Failed to fetch notifications", error) }] }; } }
- Zod schema defining the input parameters for the list-notifications tool.export const listNotificationsSchema = z.object({ 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-notifications.ts:84-91 (registration)Registration function that adds the list-notifications tool to the MCP server using server.tool, referencing the schema and handler.export function registerListNotificationsTool(server: any) { server.tool( "list-notifications", "List GitHub notifications for the authenticated user", listNotificationsSchema.shape, listNotificationsHandler ); }
- src/server.ts:38-38 (registration)Invocation of the registration function during server initialization.registerListNotificationsTool(server);