USCardForum MCP Server

Instructions

Implementation Reference

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

  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 )
• src/uscardforum/models/auth.py:82-103 (schema)

  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