USCardForum MCP Server

Instructions

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)

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