USCardForum MCP Server

Instructions

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, )