list-notifications
Retrieve and manage GitHub notifications for the authenticated user, with options to filter by participation status, read state, and time range.
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 main handler function that executes the tool logic: fetches GitHub notifications based on parameters, formats them for readability, handles pagination info, and manages errors.
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, including optional filters like all, participating, timestamps, and pagination.
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)The registration function that adds the list-notifications tool to the MCP server, specifying name, description, 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 to register the tool.
registerListNotificationsTool(server);