USCardForum MCP Server

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)

  The main MCP handler function for the 'login' tool. It takes username, password, and optional second_factor_token, calls get_client().login(), and returns a 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 BaseModel defining the output schema for the login tool: success, username, error, requires_2fa fields with from_api_response classmethod.

  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"], username=None, requires_2fa=False)
          if data.get("second_factor_required"):
              return cls(success=False, requires_2fa=True, username=username, error=None)
          return cls(success=True, username=username, error=None, requires_2fa=False)

• src/uscardforum/server_tools/__init__.py:34-40 (registration)

  Imports the login tool (along with other auth tools) from the auth module into server_tools __init__.py, making it available for MCP registration upon import.

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

• src/uscardforum/server_tools/__init__.py:101-106 (registration)

  Adds 'login' to __all__ in server_tools/__init__.py, explicitly exposing the tool for import and MCP auto-registration.

  # 🔐 Auth
  "login",
  "get_current_session",
  "get_notifications",
  "bookmark_post",
  "subscribe_topic",

• src/uscardforum/api/auth.py:128-176 (helper)

  The underlying AuthAPI.login() method called by get_client().login(), handling the HTTP POST request to /session.json with CSRF token and parsing LoginResult.

  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
      """
      token = self.fetch_csrf_token()
  
      data: dict[str, Any] = {
          "login": username,
          "password": password,
          "remember": remember_me,
      }
      if second_factor_token:
          data["second_factor_token"] = second_factor_token
  
      headers = {
          "Accept": "application/json",
          "Content-Type": "application/json",
          "Referer": f"{self._base_url}/login",
          "X-CSRF-Token": token,
          "X-Requested-With": "XMLHttpRequest",
      }
  
      payload = self._post("/session.json", json=data, headers=headers)
      result = LoginResult.from_api_response(payload, username)
  
      if result.success:
          # Verify session and get username
          session = self.get_current_session()
          if session.current_user:
              self._logged_in_username = session.current_user.username
          else:
              self._logged_in_username = username
  
      return result