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-118 (handler)

  The primary MCP tool handler for 'get_notifications'. Decorated with @mcp.tool(), defines the input schema using Pydantic's Annotated and Field for parameters (since_id, only_unread, limit), includes detailed docstring, and implements the logic by delegating to the underlying client.get_notifications() method. This is the entrypoint for the MCP tool execution.

  @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/client.py:490-508 (helper)

  Helper method in the Client class that wraps the AuthAPI.get_notifications() call. Directly invoked by the MCP tool handler via get_client().get_notifications().

  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/api/auth.py:181-211 (helper)

  Core helper implementation in AuthAPI class that performs the actual HTTP GET to /notifications.json, parses the JSON response into Notification objects, and applies client-side filtering based on since_id, only_unread, and limit 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/server_tools/__init__.py:52-58 (registration)

  Re-export of the get_notifications tool from auth.py module, making it available in the server_tools namespace for import into the main server.py.

  from .auth import (
      login,
      get_current_session,
      get_notifications,
      bookmark_post,
      subscribe_topic,
  )

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

  Import of get_notifications from server_tools into the main server entrypoint, exposing it to the MCP server runtime (likely auto-registered via decorator or introspection).

  from uscardforum.server_tools import (
      analyze_user,
      bookmark_post,
      compare_cards,
      find_data_points,
      get_all_topic_posts,
      get_categories,
      get_current_session,
      get_hot_topics,
      get_new_topics,
      get_notifications,
      get_top_topics,
      get_topic_info,
      get_topic_posts,
      get_user_actions,
      get_user_badges,
      get_user_followers,
      get_user_following,
      get_user_reactions,
      get_user_replies,
      get_user_summary,
      get_user_topics,
      list_users_with_badge,
      login,
      research_topic,
      resource_categories,
      resource_hot_topics,
      resource_new_topics,
      search_forum,
      subscribe_topic,
  )