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

webull_openapi_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Webull OpenAPI MCP Server - AI assistant integration for Webull OpenAPI."""
+
+__version__ = "0.1.0"

webull_openapi_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m webull_openapi_mcp`."""
+
+from webull_openapi_mcp.cli import main
+
+if __name__ == "__main__":
+    main()

webull_openapi_mcp/audit.py

@@ -0,0 +1,161 @@
+"""Audit logging for Webull MCP Server.
+
+All audit events are emitted as single-line JSON to stderr (always) and
+optionally to a rotating log file when ``WEBULL_AUDIT_LOG_FILE`` is configured.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import logging
+import sys
+from datetime import datetime, timezone
+from logging.handlers import RotatingFileHandler
+from typing import Any
+
+from webull_openapi_mcp.config import ServerConfig
+
+# Fields whose *values* must never appear in any log output.
+_CREDENTIAL_KEYS = frozenset({"app_key", "app_secret", "access_token"})
+
+# Fields that are replaced with "***" in TOOL_CALL params.
+_PRICE_SENSITIVE_KEYS = frozenset({"price", "stop_price"})
+
+
+class _JsonFormatter(logging.Formatter):
+    """Emit each log record as a single JSON line."""
+
+    def format(self, record: logging.LogRecord) -> str:  # noqa: A003
+        return record.getMessage()
+
+
+class AuditLogger:
+    """Structured audit logger for tool calls, order events and validation errors."""
+
+    def __init__(self, config: ServerConfig) -> None:
+        self._logger = logging.getLogger("webull_openapi_mcp.audit")
+        self._logger.setLevel(logging.INFO)
+        self._logger.propagate = False
+
+        # Remove any pre-existing handlers (important for tests / re-init).
+        self._logger.handlers.clear()
+
+        formatter = _JsonFormatter()
+
+        # stderr handler — always enabled
+        stderr_handler = logging.StreamHandler(sys.stderr)
+        stderr_handler.setFormatter(formatter)
+        self._logger.addHandler(stderr_handler)
+
+        # Optional rotating file handler
+        if config.audit_log_file:
+            file_handler = RotatingFileHandler(
+                config.audit_log_file,
+                maxBytes=10 * 1024 * 1024,  # 10 MB
+                backupCount=5,
+                encoding="utf-8",
+            )
+            file_handler.setFormatter(formatter)
+            self._logger.addHandler(file_handler)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def log_tool_call(self, tool_name: str, params: dict[str, Any]) -> None:
+        """Record a ``TOOL_CALL`` event with sanitised parameters."""
+        sanitised = self._sanitize_params(params)
+        self._emit({"event": "TOOL_CALL", "tool": tool_name, "params": sanitised})
+
+    def log_order_attempt(
+        self,
+        symbol: str,
+        side: str,
+        quantity: float,
+        order_type: str,
+        client_order_id: str,
+        account_id: str,
+    ) -> None:
+        """Record an ``ORDER_ATTEMPT`` event."""
+        self._emit(
+            {
+                "event": "ORDER_ATTEMPT",
+                "symbol": symbol,
+                "side": side,
+                "quantity": quantity,
+                "order_type": order_type,
+                "client_order_id": client_order_id,
+                "account_id": account_id,
+            }
+        )
+
+    def log_order_result(
+        self, client_order_id: str, success: bool, response: dict[str, Any]
+    ) -> None:
+        """Record an ``ORDER_RESULT`` event."""
+        safe_response = self._strip_credentials(response)
+        self._emit(
+            {
+                "event": "ORDER_RESULT",
+                "client_order_id": client_order_id,
+                "success": success,
+                "response": safe_response,
+            }
+        )
+
+    def log_validation_error(
+        self, tool_name: str, error: str, params: dict[str, Any]
+    ) -> None:
+        """Record a ``VALIDATION_ERROR`` event."""
+        sanitised = self._sanitize_params(params)
+        self._emit(
+            {
+                "event": "VALIDATION_ERROR",
+                "tool": tool_name,
+                "error": error,
+                "params": sanitised,
+            }
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _emit(self, payload: dict[str, Any]) -> None:
+        """Add timestamp and write a single JSON line via the logger."""
+        payload["timestamp"] = datetime.now(timezone.utc).isoformat()
+        self._logger.info(json.dumps(payload, default=str))
+
+    @staticmethod
+    def _sanitize_params(params: dict[str, Any]) -> dict[str, Any]:
+        """Return a copy with price fields masked and credential keys removed."""
+        result: dict[str, Any] = {}
+        for key, value in params.items():
+            if key in _CREDENTIAL_KEYS:
+                continue
+            if key in _PRICE_SENSITIVE_KEYS:
+                result[key] = "***"
+            else:
+                result[key] = value
+        return result
+
+    @staticmethod
+    def _strip_credentials(data: dict[str, Any]) -> dict[str, Any]:
+        """Return a deep copy with all credential keys removed recursively."""
+        cleaned = copy.deepcopy(data)
+        AuditLogger._remove_keys_recursive(cleaned, _CREDENTIAL_KEYS)
+        return cleaned
+
+    @staticmethod
+    def _remove_keys_recursive(obj: Any, keys: frozenset[str]) -> None:
+        """Recursively remove *keys* from nested dicts/lists in-place."""
+        if isinstance(obj, dict):
+            for k in list(obj.keys()):
+                if k in keys:
+                    del obj[k]
+                else:
+                    AuditLogger._remove_keys_recursive(obj[k], keys)
+        elif isinstance(obj, list):
+            for item in obj:
+                AuditLogger._remove_keys_recursive(item, keys)

webull_openapi_mcp/cli.py

@@ -0,0 +1,451 @@
+"""Command-line interface for Webull OpenAPI MCP Server.
+
+Provides commands for initialization, server startup, status checking,
+and tool listing.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from pathlib import Path
+
+import click
+
+from webull_openapi_mcp import __version__
+from webull_openapi_mcp.config import ServerConfig, load_config, validate_config
+from webull_openapi_mcp.errors import ConfigError
+
+
+def _mask_secret(value: str, visible_chars: int = 4) -> str:
+    """Mask a secret value, showing only the first few characters."""
+    if not value:
+        return "(not set)"
+    if len(value) <= visible_chars:
+        return "*" * len(value)
+    return value[:visible_chars] + "*" * (len(value) - visible_chars)
+
+
+def _is_posix() -> bool:
+    """Check if running on a POSIX system."""
+    return os.name == "posix"
+
+
+# ---------------------------------------------------------------------------
+# Common options
+# ---------------------------------------------------------------------------
+
+_env_file_option = click.option(
+    "--env-file",
+    type=click.Path(exists=False),
+    default=None,
+    help="Path to .env file (default: .env in current directory)",
+)
+
+
+# ---------------------------------------------------------------------------
+# CLI group
+# ---------------------------------------------------------------------------
+
+@click.group(invoke_without_command=True)
+@click.option("--version", is_flag=True, help="Show version and exit")
+@click.pass_context
+def main(ctx: click.Context, version: bool) -> None:
+    """Webull OpenAPI MCP Server - AI assistant integration for Webull OpenAPI."""
+    if version:
+        click.echo(f"webull-openapi-mcp {__version__}")
+        ctx.exit(0)
+    
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+# ---------------------------------------------------------------------------
+# init command — helpers
+# ---------------------------------------------------------------------------
+
+def _load_existing_env(path: Path) -> dict[str, str]:
+    """Load key=value pairs from an existing .env file."""
+    values: dict[str, str] = {}
+    if not path.exists():
+        return values
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    key, _, value = line.partition("=")
+                    values[key.strip()] = value.strip()
+    except Exception:
+        pass
+    return values
+
+
+def _prompt_credential(
+    value: str | None,
+    existing: dict[str, str],
+    env_key: str,
+    label: str,
+    *,
+    hidden: bool = False,
+) -> str:
+    """Prompt for a credential if not provided, with existing value fallback."""
+    if value is not None:
+        return value
+    existing_val = existing.get(env_key, "")
+    if existing_val:
+        click.echo(f"{label} [current: {_mask_secret(existing_val)}]")
+        new_val = click.prompt(
+            "Enter new value or press Enter to keep current",
+            default="",
+            hide_input=hidden,
+            show_default=False,
+        )
+        return new_val if new_val else existing_val
+    return click.prompt(label, hide_input=hidden)
+
+
+def _build_env_content(app_key: str, app_secret: str, environment: str) -> str:
+    """Build .env file content string."""
+    return f"""# Webull MCP Server Configuration
+# Generated by: webull-mcp-server init
+
+# Required: Webull API credentials
+WEBULL_APP_KEY={app_key}
+WEBULL_APP_SECRET={app_secret}
+
+# API environment: uat or prod (default: prod)
+WEBULL_ENVIRONMENT={environment}
+
+# Optional: Region ID (default: us)
+# WEBULL_REGION_ID=us
+
+# Optional: Risk control parameters
+# WEBULL_MAX_ORDER_NOTIONAL=10000
+# WEBULL_MAX_ORDER_QUANTITY=1000
+
+# Optional: Symbol whitelist (comma-separated, empty = no restriction)
+# WEBULL_SYMBOL_WHITELIST=AAPL,MSFT,GOOGL
+
+# Optional: Token storage directory (default: SDK default ./conf/)
+# WEBULL_TOKEN_DIR=
+
+# Optional: Audit log file path (default: stderr only)
+# WEBULL_AUDIT_LOG_FILE=
+"""
+
+
+def _write_env_file(
+    target_path: Path, content: str, app_key: str, app_secret: str, environment: str,
+) -> None:
+    """Write .env file and set permissions."""
+    try:
+        with open(target_path, "w", encoding="utf-8") as f:
+            f.write(content)
+        if _is_posix():
+            os.chmod(target_path, stat.S_IRUSR | stat.S_IWUSR)
+            click.echo(f"Created {target_path} with permissions 0600")
+        else:
+            click.echo(f"Created {target_path}")
+        click.echo(f"\nConfiguration saved:")
+        click.echo(f"  App Key: {_mask_secret(app_key)}")
+        click.echo(f"  App Secret: {_mask_secret(app_secret)}")
+        click.echo(f"  Environment: {environment}")
+        click.echo(f"\nRun 'webull-mcp-server serve' to start the MCP server.")
+    except Exception as e:
+        click.echo(f"Error writing {target_path}: {e}", err=True)
+        raise SystemExit(1)
+
+
+# ---------------------------------------------------------------------------
+# init command
+# ---------------------------------------------------------------------------
+
+@main.command()
+@click.option("--app-key", default=None, help="Webull App Key")
+@click.option("--app-secret", default=None, help="Webull App Secret")
+@click.option(
+    "--environment",
+    type=click.Choice(["uat", "prod"]),
+    default="prod",
+    help="API environment (default: prod)",
+)
+def init(
+    app_key: str | None,
+    app_secret: str | None,
+    environment: str,
+    env_file: str | None,
+) -> None:
+    """Initialize configuration by creating or updating .env file.
+
+    Interactively prompts for credentials if not provided via options.
+    On POSIX systems, sets file permissions to 0600 (owner read/write only).
+    """
+    target_path = Path(env_file) if env_file else Path(".env")
+    existing_values = _load_existing_env(target_path)
+
+    app_key = _prompt_credential(
+        app_key, existing_values, "WEBULL_APP_KEY", "Webull App Key", hidden=False,
+    )
+    app_secret = _prompt_credential(
+        app_secret, existing_values, "WEBULL_APP_SECRET", "Webull App Secret", hidden=True,
+    )
+
+    env_content = _build_env_content(app_key, app_secret, environment)
+    _write_env_file(target_path, env_content, app_key, app_secret, environment)
+
+
+# ---------------------------------------------------------------------------
+# serve command
+# ---------------------------------------------------------------------------
+
+def _check_token_status(config: ServerConfig) -> str | None:
+    """Check local token file status.
+    
+    Returns:
+        None if token is valid (NORMAL) or doesn't exist
+        Error message if token is PENDING (needs 2FA)
+    """
+    token_dir = config.token_dir or "./conf"
+    token_file = Path(token_dir) / "token.txt"
+    
+    if not token_file.exists():
+        return None  # No token file, SDK will create one
+    
+    try:
+        with open(token_file, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+            if len(lines) >= 3:
+                status = lines[2].strip()
+                if status == "PENDING":
+                    return (
+                        "2FA Authentication Required\n"
+                        "===========================\n"
+                        "\n"
+                        "Your token status is PENDING - waiting for 2FA approval.\n"
+                        "The MCP server cannot wait for 2FA approval in stdio mode.\n"
+                        "\n"
+                        "Please run the following command first:\n"
+                        "  webull-openapi-mcp auth\n"
+                        "\n"
+                        "This will allow you to complete 2FA interactively.\n"
+                        "After authentication succeeds, restart the MCP server.\n"
+                    )
+    except Exception:
+        pass  # Ignore read errors, let SDK handle it
+    
+    return None
+
+
+@main.command()
+@_env_file_option
+def serve(env_file: str | None) -> None:
+    """Start the MCP server in stdio mode.
+    
+    Loads configuration from .env file, initializes the Webull SDK,
+    and starts the MCP stdio server for AI client communication.
+    """
+    from webull_openapi_mcp.sdk_client import (
+        DeviceNotRegisteredError,
+        TwoFactorAuthRequiredError,
+    )
+    
+    try:
+        config = load_config(env_file)
+        validate_config(config)
+    except ConfigError as e:
+        click.echo(f"Configuration error: {e}", err=True)
+        raise SystemExit(1)
+    
+    # Check token status before starting - fail fast if 2FA pending
+    token_error = _check_token_status(config)
+    if token_error:
+        click.echo(f"\n{token_error}", err=True)
+        raise SystemExit(1)
+    
+    from webull_openapi_mcp.server import build_server
+    
+    try:
+        server = build_server(config)
+        server.run(transport="stdio")
+    except KeyboardInterrupt:
+        # Graceful shutdown on Ctrl+C
+        pass
+    except DeviceNotRegisteredError as e:
+        # No device registered - guide user to register device first
+        click.echo(f"\n{e}", err=True)
+        raise SystemExit(1)
+    except TwoFactorAuthRequiredError as e:
+        # 2FA required - guide user to run auth command first
+        click.echo(f"\n{e}", err=True)
+        raise SystemExit(1)
+    except Exception as e:
+        click.echo(f"Server error: {e}", err=True)
+        raise SystemExit(1)
+
+
+# ---------------------------------------------------------------------------
+# auth command
+# ---------------------------------------------------------------------------
+
+@main.command()
+@_env_file_option
+def auth(env_file: str | None) -> None:
+    """Authenticate with Webull API and obtain access token.
+    
+    This command handles the token creation and 2FA flow:
+    1. Loads configuration from .env file
+    2. Initiates token creation with Webull API
+    3. If 2FA is required, SDK polls until user approves in Webull App
+    4. Saves token locally for future use
+    
+    The token is valid for 15 days and auto-refreshes on use.
+    """
+    from webull_openapi_mcp.sdk_client import DeviceNotRegisteredError, WebullSDKClient
+    
+    try:
+        config = load_config(env_file)
+        validate_config(config)
+    except ConfigError as e:
+        click.echo(f"Configuration error: {e}", err=True)
+        raise SystemExit(1)
+    
+    click.echo("Webull OpenAPI Authentication")
+    click.echo("=" * 40)
+    click.echo(f"\nRegion: {config.region_id.upper()}")
+    click.echo(f"Environment: {config.environment.upper()}")
+    click.echo(f"Token Directory: {config.token_dir or './conf (default)'}")
+    
+    click.echo("\nInitiating authentication...")
+    click.echo("If 2FA is required, please approve the request in your Webull app.")
+    click.echo("The SDK will wait for your approval (up to 5 minutes)...\n")
+    
+    sdk = WebullSDKClient(config)
+    try:
+        # Use interactive mode for longer timeout (300s vs 10s)
+        sdk.initialize(interactive=True)
+        click.echo("✓ Authentication successful!")
+        click.echo(f"\nYou can now start the MCP server:")
+        click.echo(f"  webull-openapi-mcp serve")
+    except DeviceNotRegisteredError as e:
+        # NO_AVAILABLE_DEVICE - device not registered, need to register first
+        click.echo(f"\n✗ {e}", err=True)
+        raise SystemExit(1)
+    except Exception as e:
+        click.echo(f"\n✗ Authentication failed: {e}", err=True)
+        raise SystemExit(1)
+
+
+# ---------------------------------------------------------------------------
+# status command
+# ---------------------------------------------------------------------------
+
+@main.command()
+@_env_file_option
+def status(env_file: str | None) -> None:
+    """Show configuration status and environment information.
+    
+    Displays configuration validity, masked credentials summary,
+    and current environment settings.
+    """
+    click.echo("Webull MCP Server Status")
+    click.echo("=" * 40)
+    
+    # Try to load config
+    try:
+        config = load_config(env_file)
+        config_loaded = True
+    except Exception as e:
+        click.echo(f"\nConfiguration: FAILED to load")
+        click.echo(f"  Error: {e}")
+        config_loaded = False
+        config = None
+    
+    if config_loaded and config is not None:
+        # Validate config
+        try:
+            validate_config(config)
+            click.echo(f"\nConfiguration: VALID")
+        except ConfigError as e:
+            click.echo(f"\nConfiguration: INVALID")
+            click.echo(f"  Error: {e}")
+        
+        # Show masked credentials
+        click.echo(f"\nCredentials:")
+        click.echo(f"  App Key: {_mask_secret(config.app_key)}")
+        click.echo(f"  App Secret: {_mask_secret(config.app_secret)}")
+        
+        # Show environment settings
+        click.echo(f"\nEnvironment:")
+        click.echo(f"  Region: {config.region_id}")
+        click.echo(f"  Environment: {config.environment}")
+        click.echo(f"  Token Dir: {config.token_dir or '(SDK default)'}")
+        
+        # Show risk control settings
+        click.echo(f"\nRisk Control:")
+        click.echo(f"  Max Order Notional: ${config.max_order_notional:,.2f}")
+        click.echo(f"  Max Order Quantity: {config.max_order_quantity:,.0f}")
+        if config.symbol_whitelist:
+            click.echo(f"  Symbol Whitelist: {', '.join(config.symbol_whitelist)}")
+        else:
+            click.echo(f"  Symbol Whitelist: (no restriction)")
+        
+        # Show audit settings
+        click.echo(f"\nAudit:")
+        click.echo(f"  Log File: {config.audit_log_file or '(stderr only)'}")
+    
+    # Show system info
+    click.echo(f"\nSystem:")
+    click.echo(f"  Python: {sys.version.split()[0]}")
+    click.echo(f"  Platform: {sys.platform}")
+    click.echo(f"  Version: {__version__}")
+    
+    # Show env file path
+    env_path = env_file or ".env"
+    if Path(env_path).exists():
+        click.echo(f"  Env File: {env_path} (exists)")
+    else:
+        click.echo(f"  Env File: {env_path} (not found)")
+
+
+# ---------------------------------------------------------------------------
+# tools command
+# ---------------------------------------------------------------------------
+
+@main.command()
+@_env_file_option
+def tools(env_file: str | None) -> None:
+    """List all available MCP tools with descriptions.
+    
+    Shows the tools provided by the Webull MCP Server,
+    organized by Webull OpenAPI structure.
+    """
+    from webull_openapi_mcp.server import build_server
+    
+    try:
+        config = load_config(env_file)
+    except Exception:
+        # Use minimal config for listing tools
+        config = load_config(None)
+    
+    server = build_server(config)
+    
+    click.echo("Webull OpenAPI MCP Server Tools")
+    click.echo("=" * 60)
+    
+    # List registered tools from the FastMCP server
+    import asyncio
+    tool_list = asyncio.get_event_loop().run_until_complete(server.list_tools())
+    click.echo(f"\nTotal: {len(tool_list)} tools\n")
+    
+    for tool in sorted(tool_list, key=lambda t: t.name):
+        description = tool.description or ""
+        summary = description.split("\n")[0].strip()
+        click.echo(f"  {tool.name}")
+        click.echo(f"    {summary}")
+        click.echo()
+
+
+if __name__ == "__main__":
+    main()