USCardForum MCP Server

Instructions

Implementation Reference

• src/uscardforum/server_tools/auth.py:176-213 (handler)

  The primary MCP tool handler for 'subscribe_topic'. Decorated with @mcp.tool(), defines input parameters with descriptions (serving as schema), includes comprehensive docstring, and delegates execution to the client implementation.
  @mcp.tool() def subscribe_topic( topic_id: Annotated[ int, Field(description="The topic ID to subscribe to"), ], level: Annotated[ int, Field( default=2, description="Notification level: 0=muted, 1=normal, 2=tracking (default), 3=watching", ), ] = 2, ) -> SubscriptionResult: """ Set your notification level for a topic. REQUIRES AUTHENTICATION. Args: topic_id: The topic ID to subscribe to level: Notification level: - 0: Muted (no notifications) - 1: Normal (only if mentioned) - 2: Tracking (notify on replies to your posts) - 3: Watching (notify on all new posts) Must call login() first. Returns a SubscriptionResult with: - success: Whether subscription succeeded - notification_level: The new notification level Use to: - Watch topics for all updates (level=3) - Mute noisy topics (level=0) - Track topics you've contributed to (level=2) """ return get_client().subscribe_topic(topic_id, level=level)
• src/uscardforum/models/auth.py:119-129 (schema)

  Pydantic model defining the output schema for the subscribe_topic tool response.
  class SubscriptionResult(BaseModel): """Result of subscribing to a topic.""" success: bool = Field(..., description="Whether subscription succeeded") notification_level: NotificationLevel = Field( NotificationLevel.NORMAL, description="New notification level" ) class Config: extra = "ignore"
• src/uscardforum/api/auth.py:321-356 (helper)

  Core implementation logic in AuthAPI class that performs the HTTP POST request to the forum's notifications endpoint to set the topic subscription level.
  def subscribe_topic( self, topic_id: int, level: NotificationLevel = NotificationLevel.TRACKING, ) -> SubscriptionResult: """Set topic notification level (requires auth). Args: topic_id: Topic ID level: Notification level (MUTED, NORMAL, TRACKING, WATCHING) Returns: Subscription result """ self._require_auth() if not isinstance(level, NotificationLevel): level = NotificationLevel(level) token = self._csrf_token or self.fetch_csrf_token() headers = { "Accept": "*/*", "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8", "X-CSRF-Token": token, "X-Requested-With": "XMLHttpRequest", "Referer": f"{self._base_url}/t/{int(topic_id)}", } self._post( f"/t/{int(topic_id)}/notifications", data={"notification_level": str(int(level))}, headers=headers, ) return SubscriptionResult(success=True, notification_level=level)
• src/uscardforum/server.py:15-45 (registration)

  Explicit import of the subscribe_topic tool in the main server entrypoint, which triggers registration via the @mcp.tool() decorator when the module is imported.
  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, )