avanza-mcp 1.0.0__py3-none-any.whl

avanza_mcp/__init__.py

@@ -0,0 +1,29 @@
+"""Avanza MCP Server - Public API Access via FastMCP.
+
+This server provides read-only access to Avanza's public market data API.
+No authentication required - all endpoints are publicly accessible.
+
+Provides access to:
+- Stock information, quotes, and charts
+- Fund information, sustainability metrics, and performance
+- Market data including order depth, trades, and broker activity
+- Real-time market status and trading hours
+"""
+
+__version__ = "1.0.0"
+
+from fastmcp import FastMCP
+
+# Create FastMCP instance
+mcp = FastMCP("Avanza MCP Server")
+
+# Import modules to register tools/resources/prompts via decorators
+# The @mcp.tool/@mcp.resource/@mcp.prompt decorators handle registration
+from . import prompts  # noqa: F401, E402
+from . import resources  # noqa: F401, E402
+from . import tools  # noqa: F401, E402
+
+
+def main() -> None:
+    """Entry point for the MCP server."""
+    mcp.run()

avanza_mcp/client/__init__.py

@@ -0,0 +1,25 @@
+"""Avanza API client module."""
+
+from .base import AvanzaClient
+from .endpoints import PublicEndpoint
+from .exceptions import (
+    AvanzaAPIError,
+    AvanzaAuthError,
+    AvanzaError,
+    AvanzaNetworkError,
+    AvanzaNotFoundError,
+    AvanzaRateLimitError,
+    AvanzaTimeoutError,
+)
+
+__all__ = [
+    "AvanzaClient",
+    "PublicEndpoint",
+    "AvanzaError",
+    "AvanzaAPIError",
+    "AvanzaAuthError",
+    "AvanzaNetworkError",
+    "AvanzaNotFoundError",
+    "AvanzaRateLimitError",
+    "AvanzaTimeoutError",
+]

avanza_mcp/client/base.py

@@ -0,0 +1,375 @@
+"""Base HTTP client for Avanza API."""
+
+import logging
+import uuid
+from typing import Any
+
+import httpx
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from .. import __version__
+from .exceptions import (
+    AvanzaAPIError,
+    AvanzaAuthError,
+    AvanzaNetworkError,
+    AvanzaNotFoundError,
+    AvanzaRateLimitError,
+    AvanzaRetryableError,
+    AvanzaTimeoutError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AvanzaClient:
+    """Async HTTP client for Avanza public API."""
+
+    # Default configuration
+    DEFAULT_BASE_URL = "https://www.avanza.se"
+    DEFAULT_TIMEOUT = 30.0
+    DEFAULT_CONNECT_TIMEOUT = 5.0
+    DEFAULT_MAX_CONNECTIONS = 10
+    DEFAULT_MAX_KEEPALIVE = 5
+    DEFAULT_MAX_RETRIES = 3
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+        max_connections: int = DEFAULT_MAX_CONNECTIONS,
+        max_keepalive_connections: int = DEFAULT_MAX_KEEPALIVE,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        """Initialize Avanza client.
+
+        Args:
+            base_url: Base URL for Avanza API
+            timeout: Read timeout in seconds
+            connect_timeout: Connection timeout in seconds
+            max_connections: Maximum number of concurrent connections
+            max_keepalive_connections: Maximum number of keepalive connections
+            max_retries: Maximum number of retry attempts for transient failures
+        """
+        self._base_url = base_url
+        self._timeout = timeout
+        self._connect_timeout = connect_timeout
+        self._max_connections = max_connections
+        self._max_keepalive_connections = max_keepalive_connections
+        self._max_retries = max_retries
+        self._client: httpx.AsyncClient | None = None
+
+    async def __aenter__(self) -> "AvanzaClient":
+        """Initialize httpx client with connection pooling.
+
+        Returns:
+            Self for context manager usage
+        """
+        headers = self._build_headers()
+
+        # Configure timeouts with separate connect and read values
+        timeout = httpx.Timeout(
+            self._timeout,
+            connect=self._connect_timeout,
+        )
+
+        # Configure connection pooling limits
+        limits = httpx.Limits(
+            max_connections=self._max_connections,
+            max_keepalive_connections=self._max_keepalive_connections,
+        )
+
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=headers,
+            timeout=timeout,
+            limits=limits,
+            follow_redirects=True,
+        )
+
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Clean up httpx client.
+
+        Args:
+            exc_type: Exception type if an error occurred
+            exc_val: Exception value if an error occurred
+            exc_tb: Exception traceback if an error occurred
+        """
+        if self._client:
+            await self._client.aclose()
+
+    def _build_headers(self) -> dict[str, str]:
+        """Build request headers.
+
+        Returns:
+            Dictionary of HTTP headers
+        """
+        return {
+            "User-Agent": f"avanza-mcp/{__version__}",
+            "Accept": "application/json",
+        }
+
+    def _generate_request_id(self) -> str:
+        """Generate a unique request ID for debugging.
+
+        Returns:
+            Short unique identifier string
+        """
+        return str(uuid.uuid4())[:8]
+
+    def _handle_error(
+        self,
+        response: httpx.Response,
+        path: str,
+        request_id: str,
+        params: dict[str, Any] | None = None,
+    ) -> None:
+        """Handle HTTP error responses with enhanced context.
+
+        Args:
+            response: HTTP response object
+            path: Request path for error context
+            request_id: Request ID for debugging
+            params: Query parameters for error context
+
+        Raises:
+            AvanzaNotFoundError: If resource not found (404)
+            AvanzaAuthError: If authentication failed (401, 403)
+            AvanzaRateLimitError: If rate limit exceeded (429)
+            AvanzaAPIError: For other API errors
+        """
+        status_code = response.status_code
+
+        # Try to extract error message from response
+        try:
+            error_data = response.json()
+            message = error_data.get("message", response.text)
+        except Exception:
+            message = response.text or f"HTTP {status_code}"
+
+        # Add request context to error message
+        context = f"[{request_id}] {path}"
+        if params:
+            context += f" params={params}"
+
+        logger.warning(
+            "API error: status=%d path=%s request_id=%s message=%s",
+            status_code,
+            path,
+            request_id,
+            message[:200],  # Truncate long messages
+        )
+
+        # Handle specific error types
+        if status_code == 404:
+            raise AvanzaNotFoundError(f"{context}: {message}")
+        elif status_code in (401, 403):
+            raise AvanzaAuthError(f"{context}: {message}")
+        elif status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            retry_after_int = int(retry_after) if retry_after else None
+            raise AvanzaRateLimitError(retry_after_int, f"{context}: {message}")
+        else:
+            try:
+                response_dict = response.json()
+            except Exception:
+                response_dict = None
+            raise AvanzaAPIError(status_code, f"{context}: {message}", response_dict)
+
+    def _is_retryable_status(self, status_code: int) -> bool:
+        """Check if HTTP status code is retryable.
+
+        Args:
+            status_code: HTTP status code
+
+        Returns:
+            True if request should be retried
+        """
+        # Retry on server errors (5xx) but not client errors (4xx)
+        # Exception: 429 (rate limit) is handled separately with backoff
+        return status_code >= 500
+
+    async def get(
+        self, path: str, params: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """GET request with retry logic, error handling, and JSON parsing.
+
+        Automatically retries on transient failures (network errors, timeouts,
+        server errors) with exponential backoff.
+
+        Args:
+            path: API endpoint path
+            params: Optional query parameters
+
+        Returns:
+            JSON response as dictionary
+
+        Raises:
+            AvanzaError: If request fails after all retries
+        """
+        if not self._client:
+            raise RuntimeError("Client not initialized. Use async context manager.")
+
+        request_id = self._generate_request_id()
+
+        @retry(
+            retry=retry_if_exception_type(
+                (httpx.TimeoutException, httpx.NetworkError, AvanzaRetryableError)
+            ),
+            stop=stop_after_attempt(self._max_retries),
+            wait=wait_exponential(multiplier=1, min=2, max=10),
+            reraise=True,
+            before_sleep=lambda retry_state: logger.info(
+                "Retrying request [%s] %s, attempt %d after %s",
+                request_id,
+                path,
+                retry_state.attempt_number,
+                type(retry_state.outcome.exception()).__name__
+                if retry_state.outcome
+                else "unknown",
+            ),
+        )
+        async def _get_with_retry() -> dict[str, Any]:
+            try:
+                response = await self._client.get(path, params=params)  # type: ignore
+            except httpx.TimeoutException as e:
+                logger.warning(
+                    "Request timeout [%s] %s: %s", request_id, path, str(e)
+                )
+                raise AvanzaTimeoutError(
+                    f"[{request_id}] Request timeout after {self._timeout}s: {path}"
+                ) from e
+            except httpx.NetworkError as e:
+                logger.warning(
+                    "Network error [%s] %s: %s", request_id, path, str(e)
+                )
+                raise AvanzaNetworkError(
+                    f"[{request_id}] Network error: {path} - {str(e)}"
+                ) from e
+
+            if not response.is_success:
+                # Check if this is a retryable server error
+                if self._is_retryable_status(response.status_code):
+                    # Raise specific retryable error to trigger retry
+                    raise AvanzaRetryableError(
+                        response.status_code,
+                        f"[{request_id}] Server error (will retry): {path}",
+                    )
+                # Non-retryable errors
+                self._handle_error(response, path, request_id, params)
+
+            # Handle empty responses
+            if not response.content:
+                logger.debug("Empty response [%s] %s", request_id, path)
+                return {}
+
+            # Parse JSON response
+            try:
+                return response.json()
+            except Exception as e:
+                logger.error(
+                    "JSON parse error [%s] %s: %s", request_id, path, str(e)
+                )
+                raise AvanzaAPIError(
+                    response.status_code,
+                    f"[{request_id}] Invalid JSON response: {path}",
+                ) from e
+
+        logger.debug("GET [%s] %s params=%s", request_id, path, params)
+        return await _get_with_retry()
+
+    async def post(
+        self, path: str, json: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """POST request with retry logic, error handling, and JSON parsing.
+
+        Automatically retries on transient failures (network errors, timeouts,
+        server errors) with exponential backoff.
+
+        Args:
+            path: API endpoint path
+            json: Optional JSON body
+
+        Returns:
+            JSON response as dictionary
+
+        Raises:
+            AvanzaError: If request fails after all retries
+        """
+        if not self._client:
+            raise RuntimeError("Client not initialized. Use async context manager.")
+
+        request_id = self._generate_request_id()
+
+        @retry(
+            retry=retry_if_exception_type(
+                (httpx.TimeoutException, httpx.NetworkError, AvanzaRetryableError)
+            ),
+            stop=stop_after_attempt(self._max_retries),
+            wait=wait_exponential(multiplier=1, min=2, max=10),
+            reraise=True,
+            before_sleep=lambda retry_state: logger.info(
+                "Retrying POST request [%s] %s, attempt %d after %s",
+                request_id,
+                path,
+                retry_state.attempt_number,
+                type(retry_state.outcome.exception()).__name__
+                if retry_state.outcome
+                else "unknown",
+            ),
+        )
+        async def _post_with_retry() -> dict[str, Any]:
+            try:
+                response = await self._client.post(path, json=json)  # type: ignore
+            except httpx.TimeoutException as e:
+                logger.warning(
+                    "POST timeout [%s] %s: %s", request_id, path, str(e)
+                )
+                raise AvanzaTimeoutError(
+                    f"[{request_id}] Request timeout after {self._timeout}s: {path}"
+                ) from e
+            except httpx.NetworkError as e:
+                logger.warning(
+                    "POST network error [%s] %s: %s", request_id, path, str(e)
+                )
+                raise AvanzaNetworkError(
+                    f"[{request_id}] Network error: {path} - {str(e)}"
+                ) from e
+
+            if not response.is_success:
+                if self._is_retryable_status(response.status_code):
+                    raise AvanzaRetryableError(
+                        response.status_code,
+                        f"[{request_id}] Server error (will retry): {path}",
+                    )
+                self._handle_error(response, path, request_id)
+
+            if not response.content:
+                logger.debug("Empty POST response [%s] %s", request_id, path)
+                return {}
+
+            try:
+                return response.json()
+            except Exception as e:
+                logger.error(
+                    "POST JSON parse error [%s] %s: %s", request_id, path, str(e)
+                )
+                raise AvanzaAPIError(
+                    response.status_code,
+                    f"[{request_id}] Invalid JSON response: {path}",
+                ) from e
+
+        logger.debug("POST [%s] %s", request_id, path)
+        return await _post_with_retry()

avanza_mcp/client/endpoints.py

@@ -0,0 +1,41 @@
+"""Avanza API endpoint definitions.
+
+All endpoints are public and require no authentication.
+"""
+
+from enum import Enum
+
+
+class PublicEndpoint(Enum):
+    """Public Avanza API endpoints - no authentication required."""
+
+    # Search
+    SEARCH = "/_api/search/filtered-search"
+
+    # Market data - Stocks
+    STOCK_INFO = "/_api/market-guide/stock/{id}"
+    STOCK_ANALYSIS = "/_api/market-guide/stock/{id}/analysis"
+    STOCK_QUOTE = "/_api/market-guide/stock/{id}/quote"
+    STOCK_MARKETPLACE = "/_api/market-guide/stock/{id}/marketplace"
+    STOCK_ORDERDEPTH = "/_api/market-guide/stock/{id}/orderdepth"
+    STOCK_TRADES = "/_api/market-guide/stock/{id}/trades"
+    STOCK_BROKER_TRADES = "/_api/market-guide/stock/{id}/broker-trade-summaries"
+    STOCK_CHART = "/_api/price-chart/stock/{id}"  # Requires timePeriod param
+
+    # Market data - Funds
+    FUND_INFO = "/_api/fund-guide/guide/{id}"
+    FUND_SUSTAINABILITY = "/_api/fund-reference/sustainability/{id}"
+    FUND_CHART = "/_api/fund-guide/chart/{id}/{time_period}"  # time_period: three_years, etc.
+    FUND_CHART_PERIODS = "/_api/fund-guide/chart/timeperiods/{id}"
+    FUND_DESCRIPTION = "/_api/fund-guide/description/{id}"
+
+    def format(self, **kwargs: str | int) -> str:
+        """Format endpoint path with variables.
+
+        Args:
+            **kwargs: Variables to format into the endpoint path
+
+        Returns:
+            Formatted endpoint path
+        """
+        return self.value.format(**kwargs)

avanza_mcp/client/exceptions.py

@@ -0,0 +1,66 @@
+"""Custom exceptions for Avanza client."""
+
+
+class AvanzaError(Exception):
+    """Base exception for Avanza API errors."""
+
+    pass
+
+
+class AvanzaAPIError(AvanzaError):
+    """API returned an error response."""
+
+    def __init__(
+        self, status_code: int, message: str, response: dict | None = None
+    ) -> None:
+        self.status_code = status_code
+        self.message = message
+        self.response = response
+        super().__init__(f"API error {status_code}: {message}")
+
+
+class AvanzaAuthError(AvanzaError):
+    """Authentication failed or token expired."""
+
+    pass
+
+
+class AvanzaNotFoundError(AvanzaError):
+    """Requested resource not found."""
+
+    pass
+
+
+class AvanzaRateLimitError(AvanzaError):
+    """Rate limit exceeded."""
+
+    def __init__(self, retry_after: int | None = None, message: str | None = None) -> None:
+        self.retry_after = retry_after
+        msg = message or "Rate limit exceeded"
+        if retry_after and not message:
+            msg += f", retry after {retry_after}s"
+        super().__init__(msg)
+
+
+class AvanzaTimeoutError(AvanzaError):
+    """Request timed out."""
+
+    pass
+
+
+class AvanzaNetworkError(AvanzaError):
+    """Network error occurred during request."""
+
+    pass
+
+
+class AvanzaRetryableError(AvanzaError):
+    """Transient error that should trigger a retry.
+
+    This is an internal exception used for retry logic.
+    """
+
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"Retryable error {status_code}: {message}")

avanza_mcp/models/__init__.py

@@ -0,0 +1,41 @@
+"""Pydantic models for Avanza API responses."""
+
+from .common import InstrumentType, TimePeriod
+from .fund import (
+    FundChart,
+    FundChartPeriod,
+    FundDescription,
+    FundInfo,
+    FundPerformance,
+    FundSustainability,
+)
+from .search import SearchResponse, SearchHit
+from .stock import (
+    BrokerTradeSummary,
+    MarketplaceInfo,
+    OrderDepth,
+    Quote,
+    StockChart,
+    StockInfo,
+    Trade,
+)
+
+__all__ = [
+    "InstrumentType",
+    "TimePeriod",
+    "SearchResponse",
+    "SearchHit",
+    "Quote",
+    "StockInfo",
+    "FundInfo",
+    "FundPerformance",
+    "FundChart",
+    "FundChartPeriod",
+    "FundDescription",
+    "FundSustainability",
+    "StockChart",
+    "MarketplaceInfo",
+    "BrokerTradeSummary",
+    "Trade",
+    "OrderDepth",
+]

avanza_mcp/models/common.py

@@ -0,0 +1,50 @@
+"""Common models and enums shared across Avanza API."""
+
+from enum import Enum
+
+
+class InstrumentType(str, Enum):
+    """Types of financial instruments available on Avanza."""
+
+    STOCK = "STOCK"
+    FUND = "FUND"
+    BOND = "BOND"
+    OPTION = "OPTION"
+    FUTURE_FORWARD = "FUTURE_FORWARD"
+    CERTIFICATE = "CERTIFICATE"
+    WARRANT = "WARRANT"
+    ETF = "ETF"
+    EXCHANGE_TRADED_FUND = "EXCHANGE_TRADED_FUND"
+    INDEX = "INDEX"
+    PREMIUM_BOND = "PREMIUM_BOND"
+    SUBSCRIPTION_OPTION = "SUBSCRIPTION_OPTION"
+    EQUITY_LINKED_BOND = "EQUITY_LINKED_BOND"
+    CONVERTIBLE = "CONVERTIBLE"
+    FAQ = "FAQ"
+
+
+class TimePeriod(str, Enum):
+    """Time periods for chart data and performance metrics."""
+
+    TODAY = "TODAY"
+    ONE_WEEK = "ONE_WEEK"
+    ONE_MONTH = "ONE_MONTH"
+    THREE_MONTHS = "THREE_MONTHS"
+    THIS_YEAR = "THIS_YEAR"
+    ONE_YEAR = "ONE_YEAR"
+    THREE_YEARS = "THREE_YEARS"
+    FIVE_YEARS = "FIVE_YEARS"
+    ALL_TIME = "ALL_TIME"
+
+
+class Resolution(str, Enum):
+    """Chart resolution/granularity."""
+
+    MINUTE = "MINUTE"
+    FIVE_MINUTES = "FIVE_MINUTES"
+    TEN_MINUTES = "TEN_MINUTES"
+    THIRTY_MINUTES = "THIRTY_MINUTES"
+    HOUR = "HOUR"
+    DAY = "DAY"
+    WEEK = "WEEK"
+    MONTH = "MONTH"