Notifications System
Relevant source files
The following files were used as context for generating this wiki page:
The Notifications System within the GitHub MCP server provides a comprehensive suite of tools for discovering, filtering, and managing user activity on GitHub. It serves as the primary mechanism for the server to identify actionable items, such as unread mentions, review requests, and updates on issues or pull requests, enabling agentic workflows to respond to environmental changes.
The system encapsulates the GitHub Activity API to allow unread notification discovery, thread-level detail retrieval, and state management (marking items as read or done). It also includes granular controls for notification subscriptions at both the individual thread and repository levels.
Architecture and Discovery Logic
The system is built around the list_notifications tool, which acts as the entry point for discovery. It utilizes the github.NotificationListOptions to provide flexible filtering based on user participation and read status.
Discovery Flow
When an agent needs to determine the next task or summarize recent activity, it initiates a listing request. The logic branches based on whether the scope is global or restricted to a specific repository.
Notification Filters
The system supports three primary filter states defined as constants:
| Filter Constant | MCP Parameter Value | Description |
|---|---|---|
FilterDefault | default | Standard view of unread notifications. |
FilterIncludeRead | include_read_notifications | Includes notifications already acknowledged. |
FilterOnlyParticipating | only_participating | Limits results to items where the user is directly involved. |
Sources: pkg/github/notifications.go:18-22, pkg/github/notifications.go:40-43
Notification State Management
Managing the lifecycle of a notification involves transitioning it through different states. The MCP server distinguishes between marking a notification as "read" versus "done" (dismissed).
Dismissal Logic
The dismiss_notification tool handles state transitions for specific threads.
- Read: Marks the thread as read to remove it from the default unread list.
- Done: Dismisses the notification entirely. Due to API variations, "done" requires an integer conversion of the thread ID, whereas "read" accepts it as a string.
Subscription Management
The system allows agents to programmatically control the volume of future notifications by managing subscriptions. This is implemented via two distinct tools targeting different resource granularities.
Subscription Levels
- Thread Subscription: Managed via
manage_notification_subscription, targeting a specificnotificationID. - Repository Subscription: Managed via
manage_repository_notification_subscription, targeting anowner/repopair.
Actions and Results
Both tools support a standardized set of actions:
| Action | API Behavior | Data Structure Impact |
|---|---|---|
watch | Subscribes to the resource. | Ignored: false, Subscribed: true |
ignore | Ignores the resource. | Ignored: true |
delete | Removes the subscription. | Resource record deleted. |
Sources: pkg/github/notifications.go:245-385, pkg/github/notifications_test.go:137-279
Integration with Development Workflows
Notifications are tightly coupled with the Issues and Pull Request systems. For instance, when an agent assigns an issue to a coding agent, notifications are generated for the actors involved.
Key Data Structures
The system primary returns github.Notification objects which contain:
ID: The unique thread identifier.Reason: The cause of the notification (e.g.,mention,author,assign).Subject: Information about the underlying resource (Issue, PR, or Discussion).Repository: Metadata about the source repository.
Sources: pkg/github/notifications.go:100-110, pkg/github/notifications_test.go:38-41
Conclusion
The Notifications System enables the GitHub MCP server to act as an active participant in development cycles. By providing tools to list, detail, and manage the state of notifications, it allows automated agents to monitor repository health and user requirements without manual polling of the GitHub web interface.