login

Instructions

Authenticate with USCardForum credentials.

Args:
    username: Your forum username
    password: Your forum password
    second_factor_token: 2FA code if you have 2FA enabled (optional)

IMPORTANT: Only use this if you need authenticated features like:
- Reading notifications
- Bookmarking posts
- Subscribing to topics

Most read operations work without authentication.

Returns a LoginResult with:
- success: Whether login succeeded
- username: Logged-in username
- error: Error message if failed
- requires_2fa: Whether 2FA is required

The session remains authenticated for subsequent calls.

Security note: Credentials are used only for this session
and are not persisted.

Implementation Reference

• src/uscardforum/server_tools/auth.py:18-62 (handler)

  MCP tool handler for 'login'. Decorated with @mcp.tool(), defines input schema via Annotated Fields, calls DiscourseClient.login, returns LoginResult.

  @mcp.tool()
  def login(
      username: Annotated[
          str,
          Field(description="Your forum username"),
      ],
      password: Annotated[
          str,
          Field(description="Your forum password"),
      ],
      second_factor_token: Annotated[
          str | None,
          Field(default=None, description="2FA code if you have 2FA enabled"),
      ] = None,
  ) -> LoginResult:
      """
      Authenticate with USCardForum credentials.
  
      Args:
          username: Your forum username
          password: Your forum password
          second_factor_token: 2FA code if you have 2FA enabled (optional)
  
      IMPORTANT: Only use this if you need authenticated features like:
      - Reading notifications
      - Bookmarking posts
      - Subscribing to topics
  
      Most read operations work without authentication.
  
      Returns a LoginResult with:
      - success: Whether login succeeded
      - username: Logged-in username
      - error: Error message if failed
      - requires_2fa: Whether 2FA is required
  
      The session remains authenticated for subsequent calls.
  
      Security note: Credentials are used only for this session
      and are not persisted.
      """
      return get_client().login(
          username, password, second_factor_token=second_factor_token
      )

• src/uscardforum/models/auth.py:82-103 (schema)

  Pydantic model for LoginResult, used as output type for the login tool. Includes fields for success status, username, error, 2FA requirement, and factory method from API response.

  class LoginResult(BaseModel):
      """Result of a login attempt."""
  
      success: bool = Field(..., description="Whether login succeeded")
      username: str | None = Field(None, description="Logged-in username")
      error: str | None = Field(None, description="Error message if failed")
      requires_2fa: bool = Field(False, description="Whether 2FA is required")
  
      class Config:
          extra = "ignore"
  
      @classmethod
      def from_api_response(
          cls, data: dict[str, Any], username: str
      ) -> "LoginResult":
          """Parse from raw API response."""
          if "error" in data:
              return cls(success=False, error=data["error"])
          if data.get("second_factor_required"):
              return cls(success=False, requires_2fa=True, username=username)
          return cls(success=True, username=username)

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

  Imports all server tools including 'login' from server_tools modules. Importing the decorated functions registers them with the global mcp instance from server_core.py.

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

• src/uscardforum/client.py:460-481 (helper)

  DiscourseClient.login method called by the tool handler. Delegates to AuthAPI.login for the actual HTTP request and session management.

  def login(
      self,
      username: str,
      password: str,
      second_factor_token: str | None = None,
      remember_me: bool = True,
  ) -> LoginResult:
      """Login to the forum.
  
      Args:
          username: Forum username
          password: Forum password
          second_factor_token: Optional 2FA token
          remember_me: Remember session (default: True)
  
      Returns:
          Login result with success status
      """
      return self._auth.login(
          username, password, second_factor_token=second_factor_token, remember_me=remember_me
      )

• src/uscardforum/server_tools/auth.py:15-62 (helper)

  Imports global mcp for tool decorator and get_client() which provides the shared DiscourseClient instance.

  from uscardforum.server_core import get_client, mcp
  
  
  @mcp.tool()
  def login(
      username: Annotated[
          str,
          Field(description="Your forum username"),
      ],
      password: Annotated[
          str,
          Field(description="Your forum password"),
      ],
      second_factor_token: Annotated[
          str | None,
          Field(default=None, description="2FA code if you have 2FA enabled"),
      ] = None,
  ) -> LoginResult:
      """
      Authenticate with USCardForum credentials.
  
      Args:
          username: Your forum username
          password: Your forum password
          second_factor_token: 2FA code if you have 2FA enabled (optional)
  
      IMPORTANT: Only use this if you need authenticated features like:
      - Reading notifications
      - Bookmarking posts
      - Subscribing to topics
  
      Most read operations work without authentication.
  
      Returns a LoginResult with:
      - success: Whether login succeeded
      - username: Logged-in username
      - error: Error message if failed
      - requires_2fa: Whether 2FA is required
  
      The session remains authenticated for subsequent calls.
  
      Security note: Credentials are used only for this session
      and are not persisted.
      """
      return get_client().login(
          username, password, second_factor_token=second_factor_token
      )