get_notifications

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)

  Primary MCP tool handler for 'get_notifications'. Decorated with @mcp.tool(), defines input parameters with descriptions (serving as input schema), and implements logic by calling the client method.

  @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/models/auth.py:66-80 (schema)

  Pydantic BaseModel defining the structure of a Notification object, used as the return type (list[Notification]) for the tool.

  class Notification(BaseModel):
      """A user notification."""
  
      id: int = Field(..., description="Notification ID")
      notification_type: int = Field(..., description="Type of notification")
      read: bool = Field(False, description="Whether read")
      created_at: datetime | None = Field(None, description="When created")
      topic_id: int | None = Field(None, description="Related topic ID")
      post_number: int | None = Field(None, description="Related post number")
      slug: str | None = Field(None, description="Topic slug")
      data: dict[str, Any] = Field(default_factory=dict, description="Extra data")
  
      class Config:
          extra = "ignore"

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

  Client class method that wraps the AuthAPI.get_notifications() call, providing a high-level interface used by the tool handler.

  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_tools/__init__.py:52-55 (registration)

  Import of get_notifications from auth.py into the server_tools package __init__, making it available for import in server.py and exposing it as part of the tools package.

  from .auth import (
      login,
      get_current_session,
      get_notifications,

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

  Import of get_notifications in the main server entrypoint, ensuring the tool is loaded when the server starts (tools auto-register via decorators).

  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,