webull-openapi-mcp 0.1.0__py3-none-any.whl

webull_openapi_mcp/config.py

@@ -0,0 +1,164 @@
+"""Configuration management for Webull MCP Server."""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+
+from dotenv import load_dotenv
+
+from webull_openapi_mcp.errors import ConfigError
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ServerConfig:
+    """Immutable server configuration loaded from environment variables / .env file."""
+
+    app_key: str
+    app_secret: str
+    region_id: str = "us"
+    environment: str = "uat"  # "uat" | "prod"
+    # Market-specific notional limits (by currency)
+    max_order_notional_usd: float = 10_000.0  # For US market
+    max_order_notional_hkd: float = 80_000.0  # For HK market
+    max_order_notional_cnh: float = 70_000.0  # For CN market
+    max_order_quantity: float = 1_000.0
+    symbol_whitelist: list[str] | None = None
+    audit_log_file: str | None = None
+    token_dir: str | None = None  # Passed to SDK's api_client.set_token_dir(), None uses SDK's built-in priority resolution
+    toolsets: frozenset[str] | None = None  # None = all toolsets enabled
+    
+    # Legacy property for backward compatibility
+    @property
+    def max_order_notional(self) -> float:
+        """Return USD limit for backward compatibility."""
+        return self.max_order_notional_usd
+    
+    def get_max_notional_for_market(self, market: str | None) -> tuple[float, str]:
+        """Get max notional limit and currency for a specific market.
+        
+        Parameters
+        ----------
+        market
+            Market code: US, HK, or CN
+            
+        Returns
+        -------
+        tuple[float, str]
+            (max_notional, currency) for the market
+        """
+        if market == "HK":
+            return (self.max_order_notional_hkd, "HKD")
+        elif market == "CN":
+            return (self.max_order_notional_cnh, "CNH")
+        else:  # US or default
+            return (self.max_order_notional_usd, "USD")
+
+
+def _parse_whitelist(raw: str | None) -> list[str] | None:
+    """Parse comma-separated whitelist string into a list, or None if empty."""
+    if not raw or not raw.strip():
+        return None
+    items = [s.strip() for s in raw.split(",") if s.strip()]
+    return items if items else None
+
+
+def _parse_toolsets(raw: str | None) -> frozenset[str] | None:
+    """Parse comma-separated toolsets string into a frozenset, or None if empty."""
+    if not raw or not raw.strip():
+        return None
+    items = frozenset(s.strip() for s in raw.split(",") if s.strip())
+    return items if items else None
+
+
+def _parse_float(raw: str | None, default: float) -> float:
+    """Parse a string to float, returning *default* on None or invalid input."""
+    if raw is None:
+        return default
+    try:
+        return float(raw)
+    except (ValueError, TypeError):
+        return default
+
+
+def load_config(env_file: str | None = None) -> ServerConfig:
+    """Load configuration from environment variables / .env file.
+
+    Parameters
+    ----------
+    env_file:
+        Optional path to a ``.env`` file.  When provided the file is loaded
+        **before** reading ``os.environ`` so that file values act as defaults
+        that real env-vars can override (``python-dotenv`` default behaviour).
+    """
+    if env_file is not None:
+        load_dotenv(env_file, override=False)
+    else:
+        # Try loading a .env in the current directory as a convenience default
+        load_dotenv(override=False)
+
+    app_key = os.environ.get("WEBULL_APP_KEY", "")
+    app_secret = os.environ.get("WEBULL_APP_SECRET", "")
+    region_id = os.environ.get("WEBULL_REGION_ID", "us")
+    environment = os.environ.get("WEBULL_ENVIRONMENT", "uat")
+    # Market-specific notional limits
+    max_order_notional_usd = _parse_float(os.environ.get("WEBULL_MAX_ORDER_NOTIONAL_USD"), 10_000.0)
+    max_order_notional_hkd = _parse_float(os.environ.get("WEBULL_MAX_ORDER_NOTIONAL_HKD"), 80_000.0)
+    max_order_notional_cnh = _parse_float(os.environ.get("WEBULL_MAX_ORDER_NOTIONAL_CNH"), 70_000.0)
+    max_order_quantity = _parse_float(os.environ.get("WEBULL_MAX_ORDER_QUANTITY"), 1_000.0)
+    symbol_whitelist = _parse_whitelist(os.environ.get("WEBULL_SYMBOL_WHITELIST"))
+    audit_log_file = os.environ.get("WEBULL_AUDIT_LOG_FILE") or None
+    token_dir = os.environ.get("WEBULL_TOKEN_DIR") or None
+    toolsets = _parse_toolsets(os.environ.get("WEBULL_TOOLSETS"))
+
+    return ServerConfig(
+        app_key=app_key,
+        app_secret=app_secret,
+        region_id=region_id,
+        environment=environment,
+        max_order_notional_usd=max_order_notional_usd,
+        max_order_notional_hkd=max_order_notional_hkd,
+        max_order_notional_cnh=max_order_notional_cnh,
+        max_order_quantity=max_order_quantity,
+        symbol_whitelist=symbol_whitelist,
+        audit_log_file=audit_log_file,
+        token_dir=token_dir,
+        toolsets=toolsets,
+    )
+
+
+def validate_config(config: ServerConfig) -> None:
+    """Validate that required credentials are present.
+
+    Raises
+    ------
+    ConfigError
+        If ``app_key`` or ``app_secret`` is empty / missing.
+    """
+    if not config.app_key:
+        raise ConfigError(
+            "WEBULL_APP_KEY is required but not set. "
+            "Provide it via environment variable or .env file."
+        )
+    if not config.app_secret:
+        raise ConfigError(
+            "WEBULL_APP_SECRET is required but not set. "
+            "Provide it via environment variable or .env file."
+        )
+    
+    # Validate region configuration
+    from webull_openapi_mcp.region_config import get_region_config, SUPPORTED_REGIONS
+    from webull_openapi_mcp.errors import UnsupportedRegionError
+    
+    try:
+        region_config = get_region_config(config.region_id)
+        logger.info(
+            "Region configuration validated: region=%s, environment=%s",
+            region_config.region_id,
+            config.environment,
+        )
+    except UnsupportedRegionError as e:
+        raise ConfigError(str(e)) from e

webull_openapi_mcp/constants.py

@@ -0,0 +1,94 @@
+"""Enum constants used throughout the Webull MCP Server."""
+
+from __future__ import annotations
+
+# Trading sides
+VALID_SIDES: frozenset[str] = frozenset({"BUY", "SELL", "SHORT"})
+
+# Stock/crypto/futures order types
+VALID_ORDER_TYPES: frozenset[str] = frozenset({
+    "MARKET", "LIMIT", "STOP_LOSS", "STOP_LOSS_LIMIT", "TRAILING_STOP_LOSS",
+})
+
+# Option order types (subset of stock order types)
+VALID_OPTION_ORDER_TYPES: frozenset[str] = frozenset({
+    "MARKET", "LIMIT", "STOP_LOSS", "STOP_LOSS_LIMIT",
+})
+
+# Time-in-force for option orders (subset)
+VALID_OPTION_TIF: frozenset[str] = frozenset({"DAY", "GTC"})
+
+# Entrust (order quantity) types
+VALID_ENTRUST_TYPES: frozenset[str] = frozenset({"QTY", "AMOUNT"})
+
+# Trading session types
+VALID_TRADING_SESSIONS: frozenset[str] = frozenset({"ALL", "CORE", "NIGHT"})
+
+# Option types
+VALID_OPTION_TYPES: frozenset[str] = frozenset({"CALL", "PUT"})
+
+# Stock categories
+VALID_STOCK_CATEGORIES: frozenset[str] = frozenset({"US_STOCK", "US_ETF"})
+
+# K-line timeframes for stocks
+VALID_TIMEFRAMES: frozenset[str] = frozenset({
+    "1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w",
+})
+
+# K-line timeframes for crypto
+VALID_CRYPTO_TIMEFRAMES: frozenset[str] = frozenset({
+    "1m", "5m", "1h", "4h", "1d",
+})
+
+# Option strategies
+VALID_OPTION_STRATEGIES: frozenset[str] = frozenset({
+    "SINGLE", "COVERED_STOCK", "STRADDLE", "STRANGLE", "VERTICAL",
+    "CALENDAR", "BUTTERFLY", "CONDOR", "COLLAR_WITH_STOCK",
+    "IRON_BUTTERFLY", "IRON_CONDOR", "DIAGONAL",
+})
+
+# Min/max leg count per option strategy
+STRATEGY_LEG_COUNT: dict[str, tuple[int, int]] = {
+    "SINGLE": (1, 1),
+    "COVERED_STOCK": (2, 2),
+    "STRADDLE": (2, 2),
+    "STRANGLE": (2, 2),
+    "VERTICAL": (2, 2),
+    "CALENDAR": (2, 2),
+    "BUTTERFLY": (3, 4),
+    "CONDOR": (4, 4),
+    "COLLAR_WITH_STOCK": (3, 3),
+    "IRON_BUTTERFLY": (4, 4),
+    "IRON_CONDOR": (4, 4),
+    "DIAGONAL": (2, 2),
+}
+
+
+# =============================================================================
+# Account label to asset type mapping (US region)
+# =============================================================================
+
+# Account labels that support stock and option trading
+STOCK_OPTION_ACCOUNT_LABELS: frozenset[str] = frozenset({
+    "Individual Cash",
+    "Individual Margin",
+    "Roth IRA",
+    "Traditional IRA",
+    "Rollover IRA",
+    "Managed Roth IRA",
+    "Managed Traditional IRA",
+})
+
+# Account labels for specific asset types
+FUTURES_ACCOUNT_LABEL = "Futures"
+CRYPTO_ACCOUNT_LABEL = "Crypto"
+EVENT_ACCOUNT_LABEL = "Events Cash"
+
+# Mapping from order asset type to valid account labels
+ASSET_TYPE_ACCOUNT_LABELS: dict[str, frozenset[str]] = {
+    "stock": STOCK_OPTION_ACCOUNT_LABELS,
+    "option": STOCK_OPTION_ACCOUNT_LABELS,
+    "futures": frozenset({FUTURES_ACCOUNT_LABEL}),
+    "crypto": frozenset({CRYPTO_ACCOUNT_LABEL}),
+    "event": frozenset({EVENT_ACCOUNT_LABEL}),
+}

webull_openapi_mcp/errors.py

@@ -0,0 +1,160 @@
+"""Exception definitions and SDK error handling for Webull MCP Server."""
+
+from __future__ import annotations
+
+
+class ConfigError(Exception):
+    """Configuration error (missing credentials, invalid values, etc.)."""
+    pass
+
+
+class AuthenticationError(Exception):
+    """Authentication-related errors (token, 2FA, etc.)."""
+    pass
+
+
+class ValidationError(Exception):
+    """Order local validation failure."""
+
+    def __init__(self, message: str, field: str | None = None):
+        self.message = message
+        self.field = field
+        super().__init__(message)
+
+
+# =============================================================================
+# Region-Specific Errors
+# =============================================================================
+
+class RegionError(Exception):
+    """Base class for region-related errors."""
+    pass
+
+
+class UnsupportedRegionError(RegionError):
+    """Raised when an unsupported region is configured."""
+
+    def __init__(self, region_id: str, supported: list[str] | None = None) -> None:
+        self.region_id = region_id
+        self.supported = supported or ["us", "hk"]
+        super().__init__(
+            f"Unsupported region '{region_id}'. "
+            f"Supported regions: {', '.join(sorted(self.supported))}"
+        )
+
+
+class RegionValidationError(ValidationError):
+    """Raised when a parameter is invalid for the configured region."""
+
+    def __init__(
+        self,
+        param_name: str,
+        value: str,
+        region_id: str,
+        valid_values: set[str] | frozenset[str],
+    ) -> None:
+        self.param_name = param_name
+        self.value = value
+        self.region_id = region_id
+        self.valid_values = valid_values
+        message = (
+            f"Invalid {param_name} '{value}' for region '{region_id}'. "
+            f"Valid values: {', '.join(sorted(valid_values))}"
+        )
+        super().__init__(message, field=param_name)
+
+
+class FeatureNotSupportedError(RegionError):
+    """Raised when a feature is not supported in the configured region."""
+
+    def __init__(self, feature: str, region_id: str) -> None:
+        self.feature = feature
+        self.region_id = region_id
+        super().__init__(
+            f"Feature '{feature}' is not supported in region '{region_id}'"
+        )
+
+
+# Market data tools that need subscription special handling
+MARKET_DATA_TOOLS = frozenset({
+    "get_stock_snapshot",
+    "get_stock_quotes",
+    "get_stock_bars",
+    "get_stock_bars_single",
+    "get_stock_tick",
+    "get_stock_footprint",
+    "get_futures_tick",
+    "get_futures_snapshot",
+    "get_futures_depth",
+    "get_futures_bars",
+    "get_futures_footprint",
+    "get_crypto_snapshot",
+    "get_crypto_bars",
+    "get_event_tick",
+    "get_event_snapshot",
+    "get_event_depth",
+    "get_event_bars",
+})
+
+# Region-specific subscription guidance
+MARKET_DATA_SUBSCRIPTION_HINTS: dict[str, str] = {
+    "hk": (
+        "Market data requires quotes subscription.\n"
+        "Subscribe at: https://www.webullapp.hk/quote\n"
+        "Guide: https://developer.webull.hk/apis/docs/market-data-api/subscribe-quotes"
+    ),
+    "us": (
+        "Market data requires quotes subscription.\n"
+        "Subscribe at: https://www.webullapp.com/quote\n"
+        "Guide: https://developer.webull.com/apis/docs/market-data-api/subscribe-quotes"
+    ),
+}
+
+
+def _get_market_data_hint(region_id: str | None = None) -> str:
+    """Get market data subscription hint for the given region."""
+    if region_id and region_id.lower() in MARKET_DATA_SUBSCRIPTION_HINTS:
+        return MARKET_DATA_SUBSCRIPTION_HINTS[region_id.lower()]
+    # Fallback: show both
+    return (
+        "Market data requires quotes subscription.\n\n"
+        "HK region:\n"
+        "  Subscribe: https://www.webullapp.hk/quote\n"
+        "  Guide: https://developer.webull.hk/apis/docs/market-data-api/subscribe-quotes\n\n"
+        "US region:\n"
+        "  Subscribe: https://www.webullapp.com/quote\n"
+        "  Guide: https://developer.webull.com/apis/docs/market-data-api/subscribe-quotes"
+    )
+
+
+def handle_sdk_exception(e: Exception, tool_name: str, region_id: str | None = None) -> str:
+    """Unified SDK exception handler.
+
+    Handles:
+    - ServerException: extract http_status + error_code + message,
+      with special handling for market data 401/403 and cancel_order 404/403.
+    - ClientException: extract parameter error description.
+    - Other exceptions: generic error message.
+    """
+    from webull.core.exception.exceptions import ClientException, ServerException
+
+    if isinstance(e, ServerException):
+        http_status = e.http_status
+
+        # Market data 401/403 → subscription hint
+        if http_status in (401, 403) and tool_name in MARKET_DATA_TOOLS:
+            return _get_market_data_hint(region_id)
+
+        # cancel_order special messages
+        if tool_name == "cancel_order":
+            if http_status == 404:
+                return "Order not found; it may have been filled or already cancelled"
+            if http_status == 403:
+                return "Permission denied; please check account permissions"
+
+        return f"Server error (HTTP {http_status}): [{e.error_code}] {e.error_msg}"
+
+    if isinstance(e, ClientException):
+        return f"Parameter error: [{e.error_code}] {e.error_msg}"
+
+    return f"Internal error: {type(e).__name__}: {e}"