USCardForum MCP Server

Instructions

Implementation Reference

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

  The main handler function for the 'login' MCP tool. Decorated with @mcp.tool(), defines input parameters with descriptions and calls the underlying client.login() method returning 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 LoginResult schema used as the return type for the login tool, including fields for success, username, error, requires_2fa, and a 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)

  Import statement block in the MCP server entrypoint that imports the 'login' tool (line 38) from server_tools, triggering its registration via the @mcp.tool() decorator.
  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)

  Helper method in DiscourseClient that performs the actual login API call via AuthAPI, invoked by the MCP tool handler.
  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 )