login
Authenticate to access USCardForum features like notifications, bookmarks, and subscriptions using your forum credentials with optional 2FA support.
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.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | Your forum username | |
| password | Yes | Your forum password | |
| second_factor_token | No | 2FA code if you have 2FA enabled |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Error message if failed | |
| success | Yes | Whether login succeeded | |
| username | No | Logged-in username | |
| requires_2fa | No | Whether 2FA is required |
Implementation Reference
- The primary MCP tool handler for the 'login' tool. Defines input schema via Annotated Fields, comprehensive documentation, and delegates execution to the shared DiscourseClient instance.
@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 ) - Pydantic model defining the output schema for login results, including success status, username, error messages, and 2FA requirement.
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)Explicit import of the 'login' tool (line 38) along with all other server tools, which triggers registration via @mcp.tool() decorators when the server starts.
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, providing a unified interface that delegates to AuthAPI.login().
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/api/auth.py:116-164 (helper)Core AuthAPI.login() implementation handling HTTP POST to /session.json with CSRF token, 2FA support, and session state 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 """ 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