USCardForum MCP Server

Instructions

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,