USCardForum MCP Server

Instructions

Fetch your notifications. REQUIRES AUTHENTICATION.

Args:
    since_id: Only get notifications newer than this ID (optional)
    only_unread: Only return unread notifications (default: False)
    limit: Maximum number to return (optional)

Must call login() first.

Returns a list of Notification objects with:
- id: Notification ID
- notification_type: Type of notification
- read: Whether read
- topic_id: Related topic
- post_number: Related post
- created_at: When created

Use to:
- Check for new replies to your posts
- See mentions and likes
- Track topic updates you're watching

Implementation Reference

• src/uscardforum/server_tools/auth.py:78-119 (handler)

  The main MCP tool handler for 'get_notifications'. Defines input schema with Pydantic Field annotations and delegates execution to the DiscourseClient instance via get_client().

  @mcp.tool()
  def get_notifications(
      since_id: Annotated[
          int | None,
          Field(default=None, description="Only get notifications newer than this ID"),
      ] = None,
      only_unread: Annotated[
          bool,
          Field(default=False, description="Only return unread notifications"),
      ] = False,
      limit: Annotated[
          int | None,
          Field(default=None, description="Maximum number to return"),
      ] = None,
  ) -> list[Notification]:
      """
      Fetch your notifications. REQUIRES AUTHENTICATION.
  
      Args:
          since_id: Only get notifications newer than this ID (optional)
          only_unread: Only return unread notifications (default: False)
          limit: Maximum number to return (optional)
  
      Must call login() first.
  
      Returns a list of Notification objects with:
      - id: Notification ID
      - notification_type: Type of notification
      - read: Whether read
      - topic_id: Related topic
      - post_number: Related post
      - created_at: When created
  
      Use to:
      - Check for new replies to your posts
      - See mentions and likes
      - Track topic updates you're watching
      """
      return get_client().get_notifications(
          since_id=since_id, only_unread=only_unread, limit=limit
      )

• src/uscardforum/api/auth.py:181-212 (helper)

  Core API implementation in AuthAPI that fetches notifications from /notifications.json, parses them into Notification models, and applies client-side filtering based on parameters.

  def get_notifications(
      self,
      since_id: int | None = None,
      only_unread: bool = False,
      limit: int | None = None,
  ) -> list[Notification]:
      """Fetch notifications (requires auth).
  
      Args:
          since_id: Only notifications after this ID
          only_unread: Only unread notifications
          limit: Maximum notifications to return
  
      Returns:
          List of notification objects
      """
      self._require_auth()
      payload = self._get("/notifications.json")
      raw_notifications = payload.get("notifications", [])
  
      notifications = [Notification(**n) for n in raw_notifications]
  
      # Apply filters
      if since_id is not None:
          notifications = [n for n in notifications if n.id > since_id]
      if only_unread:
          notifications = [n for n in notifications if not n.read]
      if limit is not None:
          notifications = notifications[: max(0, int(limit))]
  
      return notifications

• src/uscardforum/client.py:490-508 (helper)

  Client-side wrapper method in DiscourseClient that delegates the get_notifications call to the underlying AuthAPI instance.

  def get_notifications(
      self,
      since_id: int | None = None,
      only_unread: bool = False,
      limit: int | None = None,
  ) -> list[Notification]:
      """Fetch notifications (requires auth).
  
      Args:
          since_id: Only notifications after this ID
          only_unread: Only unread notifications
          limit: Maximum notifications to return
  
      Returns:
          List of notification objects
      """
      return self._auth.get_notifications(
          since_id=since_id, only_unread=only_unread, limit=limit
      )

• src/uscardforum/server.py:25-25 (registration)

  Import of the get_notifications tool in the main server entrypoint, ensuring it is loaded and registered via the @mcp.tool() decorator.

  get_notifications,

• src/uscardforum/server_tools/__init__.py:55-55 (registration)

  Export of get_notifications from server_tools.auth in the tools __init__.py, making it available for import in server.py.

  get_notifications,