USCardForum MCP Server

Instructions

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