ForexFactory MCP Server

"""
settings.py

Centralized application configuration for ForexFactory MCP.

This module uses Pydantic's BaseSettings to define strongly-typed configuration
values with sensible defaults. Environment variables (and .env files) override
these defaults automatically.

We also expose a `get_settings()` function (cached with @lru_cache) to ensure
the Settings object is created only once per process. This avoids the pitfalls
of manual globals or singletons while keeping access simple and consistent.

Usage:
    from forexfactory_mcp.settings import get_settings

    settings = get_settings()
    print(settings.BASE_URL)
    timeout = settings.SCRAPER_TIMEOUT_MS
    headers = settings.EXTRA_HTTP_HEADERS
"""

from functools import lru_cache
from typing import List, Optional
from zoneinfo import ZoneInfo

from pydantic import field_validator
from pydantic_settings import BaseSettings, SettingsConfigDict
from tzlocal import get_localzone


class Settings(BaseSettings):
    """
    Application configuration class.

    Values are:
      - Pulled from environment variables if available.
      - Otherwise, fallback defaults defined here are used.
      - Optionally loaded from a `.env` file in the project root.

    Example:
        export SCRAPER_TIMEOUT_MS=10000
        → overrides default timeout (5s → 10s).
    """

    # === Core configuration values ===
    BASE_URL: str = "https://www.forexfactory.com"
    SCRAPER_TIMEOUT_MS: int = 5000  # Default 5s (Playwright expects ms)

    # === MCP namespace ===
    NAMESPACE: str = "ffcal"

    # === MCP server transport ===
    MCP_TRANSPORT: str = "stdio"  # stdio | http | sse
    MCP_HOST: str = "127.0.0.1"  # only relevant for http/sse
    MCP_PORT: int = 8000  # only relevant for http/sse

    # === Default HTTP headers for Playwright ===
    USER_AGENT: str = (
        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
        "AppleWebKit/537.36 (KHTML, like Gecko) "
        "Chrome/127.0.0.0 Safari/537.36"
    )
    ACCEPT: str = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
    ACCEPT_LANGUAGE: str = "en-US,en;q=0.9"

    # === Event field filtering ===
    INCLUDE_FIELDS: Optional[List[str]] = None
    EXCLUDE_FIELDS: Optional[List[str]] = None

    LOCAL_TIMEZONE: str = "UTC"

    # Tell Pydantic to look for environment variables in `.env`
    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")

    @field_validator("INCLUDE_FIELDS", "EXCLUDE_FIELDS", mode="before")
    @classmethod
    def split_comma_or_blank(cls, v):
        """
        Normalize values:
        - blank string → None
        - comma separated → list
        - JSON array → list
        """
        if v is None:
            return None
        if isinstance(v, str):
            v = v.strip()
            if not v:  # blank string
                return None
            return [x.strip() for x in v.split(",") if x.strip()]
        return v

    @property
    def default_fields(self) -> list[str]:
        """Default lean set of fields if INCLUDE_FIELDS not set."""
        return [
            "id",
            "title",
            "currency",
            "impact",
            "datetime",
            "forecast",
            "previous",
            "actual",
        ]

    @property
    def extra_http_headers(self) -> dict[str, str]:
        """
        Build the HTTP headers dict for Playwright requests.
        Returns values that can be directly passed to `page.set_extra_http_headers()`.
        """
        return {
            "User-Agent": self.USER_AGENT,
            "Accept": self.ACCEPT,
            "Accept-Language": self.ACCEPT_LANGUAGE,
        }

    @property
    def local_tz(self) -> ZoneInfo:
        try:
            return ZoneInfo(self.LOCAL_TIMEZONE)
        except Exception:
            # fallback to system local timezone
            try:
                return get_localzone()
            except Exception:
                return ZoneInfo("UTC")


@lru_cache
def get_settings() -> Settings:
    """
    Cached accessor for the global Settings instance.

    Using @lru_cache ensures:
      - Settings are instantiated only once per process.
      - No accidental recreation of config objects on every import.
      - Easy reset in tests (`get_settings.cache_clear()`).

    Returns:
        Settings: The singleton configuration instance.
    """
    return Settings()