list-repo-notifications
Retrieve and manage GitHub notifications for a specific repository, including filtering by participation status, read/unread status, and time ranges.
Instructions
List GitHub notifications for a specific repository
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | The account owner of the repository | |
| repo | Yes | The name of the repository | |
| 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
- 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) }] }; } }
- 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);