USCardForum MCP Server

Instructions

Implementation Reference

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

  The primary handler function for the 'login' MCP tool. Decorated with @mcp.tool(), defines input parameters with descriptions via Annotated[Field], detailed docstring, and delegates to get_client().login() 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 output schema for the login tool: success, username, error, requires_2fa fields with descriptions and 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_tools/__init__.py:52-58 (registration)

  Registration/ export of the login tool by importing from .auth in server_tools __init__.py, making it available for higher-level imports.
  from .auth import ( login, get_current_session, get_notifications, bookmark_post, subscribe_topic, )
• src/uscardforum/server.py:15-45 (registration)

  Explicit import of the 'login' tool in the main server entrypoint, ensuring it is registered with the FastMCP server when running.
  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/server_core.py:136-168 (helper)

  Helper function get_client() used by the login handler to obtain the shared DiscourseClient instance, which performs the actual login API call. Includes auto-login logic.
  def get_client() -> DiscourseClient: """Get or create the Discourse client instance.""" global _client, _login_attempted if _client is None: base_url = os.environ.get("USCARDFORUM_URL", "https://www.uscardforum.com") timeout = float(os.environ.get("USCARDFORUM_TIMEOUT", "15.0")) _client = DiscourseClient(base_url=base_url, timeout_seconds=timeout) # Auto-login if credentials are provided if not _login_attempted: _login_attempted = True username = os.environ.get("NITAN_USERNAME") password = os.environ.get("NITAN_PASSWORD") if username and password: try: result = _client.login(username, password) if result.success: print(f"[uscardforum] Auto-login successful as '{result.username}'") elif result.requires_2fa: print( "[uscardforum] Auto-login failed: 2FA required. Use login() tool with second_factor_token." ) else: print( f"[uscardforum] Auto-login failed: {result.error or 'Unknown error'}" ) except Exception as e: # pragma: no cover - logging side effect print(f"[uscardforum] Auto-login error: {e}") return _client