Proposal: Complete Notification Management API for Autonomous Agents #85

New issue

Closed

opened 2026-03-08 09:38:06 +00:00 by byteflavour · 0 comments

byteflavour commented

2026-03-08 09:38:06 +00:00

(Migrated from codeberg.org)

Proposal: Complete Notification Management API for Autonomous Agents

The Need

Currently, the forgejo-mcp server exposes the check_notifications tool, which is excellent for passively polling unread notifications. However, for fully autonomous agents that rely heavily on the MCP server to interact with Forgejo, merely reading notifications is insufficient.

Once an agent reads a notification, it needs a way to act upon it and, crucially, acknowledge it so that it doesn't process the same event in an endless loop. Without write access to the notification API, agents eventually get stuck or require manual GUI intervention.

The Solution

The Forgejo SDK already supports the full notification suite. We propose expanding the User/Notifications toolset in forgejo-mcp to expose these capabilities, allowing 100% headless notification management.

We've designed and implemented the following 5 new tools:

get_notification_thread (Fetches a single thread by ID)
mark_notification_read (Marks a specific thread as read)
mark_all_notifications_read (Global acknowledgment)
list_repo_notifications (Filters notifications scoped to a specific repository)
mark_repo_notifications_read (Marks all notifications in a specific repository as read)

Implementation Details

The implementation strictly adheres to the existing architecture in operation/user/notification.go:

Context/Logging: Follows the established log.LogMCPToolStart/LogMCPToolComplete and forgejo.LogAPICall patterns.
TDD: The mockNotificationServer in notification_test.go has been expanded to test all HTTP endpoints (including PUT and PATCH methods) and handles empty JSON responses correctly.
Documentation: README.md is updated, and a Showboat demo (demos/notifications-management.md) is provided.

Next Steps

We have the code ready on our side. I will link a Pull Request to this issue shortly that contains the complete implementation, passing tests, and documentation updates.

Would love to get your thoughts on this expansion!

# Proposal: Complete Notification Management API for Autonomous Agents ## The Need Currently, the `forgejo-mcp` server exposes the `check_notifications` tool, which is excellent for passively polling unread notifications. However, for fully autonomous agents that rely heavily on the MCP server to interact with Forgejo, merely *reading* notifications is insufficient. Once an agent reads a notification, it needs a way to act upon it and, crucially, **acknowledge** it so that it doesn't process the same event in an endless loop. Without write access to the notification API, agents eventually get stuck or require manual GUI intervention. ## The Solution The [Forgejo SDK](https://codeberg.org/mvdkleijn/forgejo-sdk) already supports the full notification suite. We propose expanding the `User/Notifications` toolset in `forgejo-mcp` to expose these capabilities, allowing 100% headless notification management. We've designed and implemented the following 5 new tools: 1. `get_notification_thread` (Fetches a single thread by ID) 2. `mark_notification_read` (Marks a specific thread as read) 3. `mark_all_notifications_read` (Global acknowledgment) 4. `list_repo_notifications` (Filters notifications scoped to a specific repository) 5. `mark_repo_notifications_read` (Marks all notifications in a specific repository as read) ## Implementation Details The implementation strictly adheres to the existing architecture in `operation/user/notification.go`: - **Context/Logging:** Follows the established `log.LogMCPToolStart`/`LogMCPToolComplete` and `forgejo.LogAPICall` patterns. - **TDD:** The `mockNotificationServer` in `notification_test.go` has been expanded to test all HTTP endpoints (including `PUT` and `PATCH` methods) and handles empty JSON responses correctly. - **Documentation:** `README.md` is updated, and a `Showboat` demo (`demos/notifications-management.md`) is provided. ## Next Steps We have the code ready on our side. I will link a Pull Request to this issue shortly that contains the complete implementation, passing tests, and documentation updates. Would love to get your thoughts on this expansion!