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)

  MCP tool handler for 'subscribe_topic'. Decorated with @mcp.tool(), includes input schema via Annotated[Field] parameters for topic_id (int) and level (int, default 2), detailed docstring, returns SubscriptionResult, delegates to get_client().subscribe_topic() which handles the actual API call.

  @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/api/auth.py:308-343 (helper)

  Core implementation in AuthAPI.subscribe_topic(). Performs the HTTP POST request to /t/{topic_id}/notifications with notification_level, handles CSRF token, requires authentication, returns SubscriptionResult(success=True). Called by client.subscribe_topic().

  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/client.py:556-571 (helper)

  Client wrapper method DiscourseClient.subscribe_topic() that converts level to NotificationLevel enum and delegates to self._auth (AuthAPI).subscribe_topic().

  def subscribe_topic(
      self,
      topic_id: int,
      level: int = 2,
  ) -> SubscriptionResult:
      """Set topic notification level (requires auth).
  
      Args:
          topic_id: Topic ID
          level: 0=muted, 1=normal, 2=tracking, 3=watching
  
      Returns:
          Subscription result
      """
      return self._auth.subscribe_topic(topic_id, level=NotificationLevel(level))

• src/uscardforum/server_tools/__init__.py:52-58 (registration)

  Re-export of subscribe_topic from server_tools.auth into the server_tools package, making it available for import in server.py.

  from .auth import (
      login,
      get_current_session,
      get_notifications,
      bookmark_post,
      subscribe_topic,
  )

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

  Import of subscribe_topic (among other tools) from server_tools in the main FastMCP server entrypoint. Importing the @mcp.tool()-decorated function registers it as an MCP tool.

  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,