avanza-mcp 1.0.0__py3-none-any.whl

avanza_mcp/prompts/analysis.py

@@ -0,0 +1,116 @@
+"""Analysis prompt templates for common workflows."""
+
+from .. import mcp
+
+
+@mcp.prompt()
+def analyze_stock(stock_symbol: str) -> str:
+    """Comprehensive stock analysis workflow.
+
+    Guides the LLM through analyzing a stock including company information,
+    price performance, recent news, and valuation metrics.
+
+    Args:
+        stock_symbol: Stock ticker symbol or name to analyze
+
+    Returns:
+        Prompt text for stock analysis
+    """
+    return f"""Please perform a comprehensive analysis of {stock_symbol}:
+
+1. **Find the stock**: Use search_instruments() to find the stock and get its instrument_id
+2. **Get detailed information**: Use get_stock_info() to retrieve:
+   - Current price and recent performance
+   - Company description and sector
+   - Key financial ratios (P/E, dividend yield, etc.)
+3. **Analyze price trends**: Use get_stock_chart() to get historical data (1 year, daily)
+4. **Check recent news**: Use get_news() to see recent company announcements
+5. **Assess the orderbook**: Use get_orderbook() to check current liquidity
+
+Based on this data, provide:
+- **Current valuation assessment** (is it overvalued/undervalued?)
+- **Price trend analysis** (what's the recent momentum?)
+- **Key risks and opportunities**
+- **Overall investment perspective**
+
+Focus on factual analysis based on the available data.
+"""
+
+
+@mcp.prompt()
+def compare_funds(fund_names: str) -> str:
+    """Compare multiple funds across key metrics.
+
+    Analyzes and compares funds on performance, fees, risk metrics,
+    and characteristics.
+
+    Args:
+        fund_names: Comma-separated list of fund names to compare
+
+    Returns:
+        Prompt text for fund comparison
+    """
+    funds = [f.strip() for f in fund_names.split(",")]
+    funds_list = "\n".join([f"- {fund}" for fund in funds])
+
+    return f"""Compare the following funds:
+{funds_list}
+
+For each fund:
+1. **Find the fund**: Use search_instruments() with instrument_type="fund"
+2. **Get fund details**: Use get_fund_info() to retrieve:
+   - Current NAV and recent performance
+   - Performance over multiple periods (YTD, 1Y, 3Y, 5Y)
+   - Risk rating and metrics
+   - Fees (ongoing charges, entry/exit fees)
+   - Fund characteristics (type, category, AUM)
+
+Then create a comparison showing:
+
+| Metric | {' | '.join(funds)} |
+|--------|{'-|' * len(funds)}
+| NAV | ... | ... |
+| YTD Return | ... | ... |
+| 1Y Return | ... | ... |
+| 3Y Return | ... | ... |
+| 5Y Return | ... | ... |
+| Risk Level (1-7) | ... | ... |
+| Ongoing Charges | ... | ... |
+| Fund Size (AUM) | ... | ... |
+
+Conclude with:
+- Which fund has the best risk-adjusted returns?
+- Which has the lowest fees?
+- Recommendation based on the comparison
+"""
+
+
+@mcp.prompt()
+def screen_dividend_stocks(min_yield: float = 3.0) -> str:
+    """Screen for dividend-paying stocks.
+
+    Helps find stocks with attractive dividend yields.
+
+    Args:
+        min_yield: Minimum dividend yield percentage (default: 3.0)
+
+    Returns:
+        Prompt text for dividend screening
+    """
+    return f"""Help me find dividend stocks with yields above {min_yield}%.
+
+Process:
+1. Search for major Swedish stocks (you might start with well-known companies)
+2. For each stock, use get_stock_info() to check the dividend yield
+3. Filter for stocks with dividend_yield >= {min_yield}%
+
+Present results as a table:
+
+| Stock | Ticker | Price | Dividend Yield | P/E Ratio | Market Cap |
+|-------|--------|-------|----------------|-----------|------------|
+| ...   | ...    | ...   | ...%           | ...       | ...        |
+
+Sort by dividend yield (highest first) and include:
+- Brief assessment of sustainability (based on P/E and other metrics)
+- Any notable risks or observations
+"""

avanza_mcp/resources/__init__.py

@@ -0,0 +1,6 @@
+"""MCP resources for Avanza API."""
+
+# Import to register resources via decorators
+from . import instruments  # noqa: F401
+
+__all__ = ["instruments"]

avanza_mcp/resources/instruments.py

@@ -0,0 +1,127 @@
+"""URI-based instrument resources."""
+
+from .. import mcp
+from ..client import AvanzaClient
+from ..services import MarketDataService
+
+
+def format_stock_markdown(stock_data: dict) -> str:
+    """Format stock info as markdown.
+
+    Args:
+        stock_data: Stock information dictionary
+
+    Returns:
+        Formatted markdown string
+    """
+    quote = stock_data.get("quote", {})
+    company = stock_data.get("company", {})
+    listing = stock_data.get("listing", {})
+    key_ratios = stock_data.get("key_ratios") or stock_data.get("keyIndicators", {})
+
+    name = stock_data.get("name", "Unknown")
+    price = quote.get("last", "N/A")
+    change = quote.get("change", 0)
+    change_pct = quote.get("changePercent", 0)
+    currency = listing.get("currency", "SEK")
+
+    md = f"# {name}\n\n"
+    md += f"**Price:** {price} {currency}\n"
+    md += f"**Change:** {change:+.2f} ({change_pct:+.2f}%)\n\n"
+
+    if company:
+        if desc := company.get("description"):
+            md += f"## Company\n{desc}\n\n"
+        if market_cap := company.get("marketCapital"):
+            if isinstance(market_cap, dict):
+                cap_value = market_cap.get("value", 0)
+                cap_currency = market_cap.get("currency", currency)
+                md += f"**Market Cap:** {cap_value:,.0f} {cap_currency}\n"
+            else:
+                md += f"**Market Cap:** {market_cap:,.0f} {currency}\n"
+
+    if key_ratios:
+        md += "\n## Key Ratios\n"
+        if pe := key_ratios.get("priceEarningsRatio"):
+            md += f"- **P/E Ratio:** {pe:.2f}\n"
+        if div_yield := key_ratios.get("directYield"):
+            md += f"- **Dividend Yield:** {div_yield:.2f}%\n"
+
+    return md
+
+
+def format_fund_markdown(fund_data: dict) -> str:
+    """Format fund info as markdown.
+
+    Args:
+        fund_data: Fund information dictionary
+
+    Returns:
+        Formatted markdown string
+    """
+    name = fund_data.get("name", "Unknown")
+    nav = fund_data.get("nav", "N/A")
+    currency = fund_data.get("currency", "SEK")
+
+    md = f"# {name}\n\n"
+    md += f"**NAV:** {nav} {currency}\n\n"
+
+    if desc := fund_data.get("description"):
+        md += f"{desc}\n\n"
+
+    if development := fund_data.get("development"):
+        md += "## Performance\n"
+        if ytd := development.get("thisYear"):
+            md += f"- **YTD:** {ytd:+.2f}%\n"
+        if one_year := development.get("oneYear"):
+            md += f"- **1 Year:** {one_year:+.2f}%\n"
+        if three_years := development.get("threeYears"):
+            md += f"- **3 Years:** {three_years:+.2f}%\n"
+
+    if risk := fund_data.get("risk"):
+        md += f"\n**Risk Level:** {risk}/7\n"
+
+    if fee := fund_data.get("fee", {}).get("ongoingCharges"):
+        md += f"**Ongoing Charges:** {fee:.2f}%\n"
+
+    return md
+
+
+@mcp.resource("avanza://stock/{instrument_id}")
+async def get_stock_resource(instrument_id: str) -> str:
+    """Get stock information as a markdown resource.
+
+    URI: avanza://stock/{instrument_id}
+
+    Args:
+        instrument_id: Avanza stock ID
+
+    Returns:
+        Formatted markdown with stock information
+    """
+    async with AvanzaClient() as client:
+        service = MarketDataService(client)
+        stock_info = await service.get_stock_info(instrument_id)
+
+    stock_data = stock_info.model_dump(by_alias=True, exclude_none=True)
+    return format_stock_markdown(stock_data)
+
+
+@mcp.resource("avanza://fund/{instrument_id}")
+async def get_fund_resource(instrument_id: str) -> str:
+    """Get fund information as a markdown resource.
+
+    URI: avanza://fund/{instrument_id}
+
+    Args:
+        instrument_id: Avanza fund ID
+
+    Returns:
+        Formatted markdown with fund information
+    """
+    async with AvanzaClient() as client:
+        service = MarketDataService(client)
+        fund_info = await service.get_fund_info(instrument_id)
+
+    fund_data = fund_info.model_dump(by_alias=True, exclude_none=True)
+    return format_fund_markdown(fund_data)

avanza_mcp/services/__init__.py

@@ -0,0 +1,6 @@
+"""Business logic services for Avanza API."""
+
+from .market_data_service import MarketDataService
+from .search_service import SearchService
+
+__all__ = ["SearchService", "MarketDataService"]

avanza_mcp/services/market_data_service.py

@@ -0,0 +1,298 @@
+"""Market data service for retrieving stock and fund information."""
+
+from typing import Any
+
+from ..client.base import AvanzaClient
+from ..client.endpoints import PublicEndpoint
+from ..models.fund import (
+    FundChart,
+    FundChartPeriod,
+    FundDescription,
+    FundInfo,
+    FundSustainability,
+)
+from ..models.stock import (
+    BrokerTradeSummary,
+    MarketplaceInfo,
+    OrderDepth,
+    Quote,
+    StockChart,
+    StockInfo,
+    Trade,
+)
+
+
+class MarketDataService:
+    """Service for retrieving market data."""
+
+    def __init__(self, client: AvanzaClient) -> None:
+        """Initialize market data service.
+
+        Args:
+            client: Avanza HTTP client
+        """
+        self._client = client
+
+    async def get_stock_info(self, instrument_id: str) -> StockInfo:
+        """Fetch detailed stock information.
+
+        Args:
+            instrument_id: Avanza instrument ID
+
+        Returns:
+            Detailed stock information
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.STOCK_INFO.format(id=instrument_id)
+        raw_data = await self._client.get(endpoint)
+        return StockInfo.model_validate(raw_data)
+
+    async def get_fund_info(self, instrument_id: str) -> FundInfo:
+        """Fetch detailed fund information.
+
+        Args:
+            instrument_id: Avanza fund ID
+
+        Returns:
+            Detailed fund information
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.FUND_INFO.format(id=instrument_id)
+        raw_data = await self._client.get(endpoint)
+        return FundInfo.model_validate(raw_data)
+
+    async def get_order_depth(self, instrument_id: str) -> OrderDepth:
+        """Fetch real-time order book depth data.
+
+        Args:
+            instrument_id: Avanza instrument ID
+
+        Returns:
+            Order book depth with buy and sell levels
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.STOCK_ORDERDEPTH.format(id=instrument_id)
+        raw_data = await self._client.get(endpoint)
+        return OrderDepth.model_validate(raw_data)
+
+    async def get_chart_data(
+        self,
+        instrument_id: str,
+        time_period: str = "one_year",
+    ) -> StockChart:
+        """Fetch historical chart data with OHLC values.
+
+        Args:
+            instrument_id: Avanza instrument ID
+            time_period: Time period - one_week, one_month, three_months, one_year, etc.
+
+        Returns:
+            Chart data with OHLC values
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.STOCK_CHART.format(id=instrument_id)
+        params = {"timePeriod": time_period}
+        raw_data = await self._client.get(endpoint, params=params)
+        return StockChart.model_validate(raw_data)
+
+    async def get_marketplace_info(self, instrument_id: str) -> MarketplaceInfo:
+        """Fetch marketplace status and trading hours.
+
+        Args:
+            instrument_id: Avanza instrument ID
+
+        Returns:
+            Marketplace information including open/close times
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.STOCK_MARKETPLACE.format(id=instrument_id)
+        raw_data = await self._client.get(endpoint)
+        return MarketplaceInfo.model_validate(raw_data)
+
+    async def get_trades(self, instrument_id: str) -> list[Trade]:
+        """Fetch recent trades for an instrument.
+
+        Args:
+            instrument_id: Avanza instrument ID
+
+        Returns:
+            List of recent trades
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.STOCK_TRADES.format(id=instrument_id)
+        raw_data = await self._client.get(endpoint)
+        return [Trade.model_validate(trade) for trade in raw_data]
+
+    async def get_broker_trades(self, instrument_id: str) -> list[BrokerTradeSummary]:
+        """Fetch broker trade summaries.
+
+        Args:
+            instrument_id: Avanza instrument ID
+
+        Returns:
+            List of broker trade summaries with buy/sell volumes
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.STOCK_BROKER_TRADES.format(id=instrument_id)
+        raw_data = await self._client.get(endpoint)
+        return [BrokerTradeSummary.model_validate(trade) for trade in raw_data]
+
+    async def get_stock_analysis(self, instrument_id: str) -> dict[str, Any]:
+        """Fetch stock analysis with key ratios by year and quarter.
+
+        Args:
+            instrument_id: Avanza instrument ID
+
+        Returns:
+            Stock analysis data with key ratios grouped by time periods
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.STOCK_ANALYSIS.format(id=instrument_id)
+        return await self._client.get(endpoint)
+
+    async def get_dividends(self, instrument_id: str) -> dict[str, Any]:
+        """Fetch dividend history from stock analysis data.
+
+        Args:
+            instrument_id: Avanza instrument ID
+
+        Returns:
+            Dividend data by year including:
+            - dividend: Dividend amount per share
+            - exDate: Ex-dividend date
+            - paymentDate: Payment date
+            - yield: Dividend yield percentage
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.STOCK_ANALYSIS.format(id=instrument_id)
+        analysis = await self._client.get(endpoint)
+        return {
+            "dividendsByYear": analysis.get("dividendsByYear", []),
+        }
+
+    async def get_company_financials(self, instrument_id: str) -> dict[str, Any]:
+        """Fetch company financial data from stock analysis.
+
+        Args:
+            instrument_id: Avanza instrument ID
+
+        Returns:
+            Company financials by year and quarter including revenue,
+            profit margins, earnings, and other financial metrics
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.STOCK_ANALYSIS.format(id=instrument_id)
+        analysis = await self._client.get(endpoint)
+        return {
+            "companyFinancialsByYear": analysis.get("companyFinancialsByYear", []),
+            "companyFinancialsByQuarter": analysis.get("companyFinancialsByQuarter", []),
+            "companyFinancialsByQuarterTTM": analysis.get(
+                "companyFinancialsByQuarterTTM", []
+            ),
+        }
+
+    async def get_stock_quote(self, instrument_id: str) -> Quote:
+        """Fetch real-time stock quote with current pricing.
+
+        Args:
+            instrument_id: Avanza instrument ID
+
+        Returns:
+            Real-time quote with buy, sell, last price, and trading volumes
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.STOCK_QUOTE.format(id=instrument_id)
+        raw_data = await self._client.get(endpoint)
+        return Quote.model_validate(raw_data)
+
+    async def get_fund_sustainability(self, instrument_id: str) -> FundSustainability:
+        """Fetch fund sustainability and ESG metrics.
+
+        Args:
+            instrument_id: Avanza fund ID
+
+        Returns:
+            Sustainability metrics including ESG scores and environmental data
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.FUND_SUSTAINABILITY.format(id=instrument_id)
+        raw_data = await self._client.get(endpoint)
+        return FundSustainability.model_validate(raw_data)
+
+    async def get_fund_chart(
+        self, instrument_id: str, time_period: str = "three_years"
+    ) -> FundChart:
+        """Fetch fund chart data for a specific time period.
+
+        Args:
+            instrument_id: Avanza fund ID
+            time_period: Time period (e.g., three_years, five_years, etc.)
+
+        Returns:
+            Fund chart with historical performance data
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.FUND_CHART.format(
+            id=instrument_id, time_period=time_period
+        )
+        raw_data = await self._client.get(endpoint)
+        return FundChart.model_validate(raw_data)
+
+    async def get_fund_chart_periods(self, instrument_id: str) -> list[FundChartPeriod]:
+        """Fetch available fund chart periods with performance data.
+
+        Args:
+            instrument_id: Avanza fund ID
+
+        Returns:
+            List of time periods with performance changes
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.FUND_CHART_PERIODS.format(id=instrument_id)
+        raw_data = await self._client.get(endpoint)
+        return [FundChartPeriod.model_validate(period) for period in raw_data]
+
+    async def get_fund_description(self, instrument_id: str) -> FundDescription:
+        """Fetch fund description and category information.
+
+        Args:
+            instrument_id: Avanza fund ID
+
+        Returns:
+            Fund description with detailed category information
+
+        Raises:
+            AvanzaError: If request fails
+        """
+        endpoint = PublicEndpoint.FUND_DESCRIPTION.format(id=instrument_id)
+        raw_data = await self._client.get(endpoint)
+        return FundDescription.model_validate(raw_data)
+

avanza_mcp/services/search_service.py

@@ -0,0 +1,64 @@
+"""Search service for finding financial instruments."""
+
+from typing import Any
+
+from ..client.base import AvanzaClient
+from ..client.endpoints import PublicEndpoint
+from ..models.common import InstrumentType
+from ..models.search import SearchResponse
+
+
+class SearchService:
+    """Service for searching financial instruments."""
+
+    def __init__(self, client: AvanzaClient) -> None:
+        """Initialize search service.
+
+        Args:
+            client: Avanza HTTP client
+        """
+        self._client = client
+
+    async def search(
+        self,
+        query: str,
+        instrument_type: str | InstrumentType | None = None,
+        limit: int = 10,
+    ) -> SearchResponse:
+        """Search for financial instruments.
+
+        Args:
+            query: Search term (company name, ticker, ISIN)
+            instrument_type: Optional type filter (stock, fund, etc.)
+            limit: Maximum number of results
+
+        Returns:
+            Complete search response with hits, facets, and pagination
+        """
+        # Build search payload
+        payload: dict[str, Any] = {
+            "query": query,
+            "limit": limit,
+        }
+
+        # Add instrument type filter if specified
+        if instrument_type and instrument_type != "all":
+            if isinstance(instrument_type, str):
+                # Convert string to InstrumentType enum
+                try:
+                    type_value = InstrumentType[instrument_type.upper()].value
+                except KeyError:
+                    type_value = instrument_type.upper()
+            else:
+                type_value = instrument_type.value
+
+            payload["instrumentType"] = type_value
+
+        # Make search request
+        response = await self._client.post(
+            PublicEndpoint.SEARCH.value,
+            json=payload,
+        )
+
+        # Parse and return typed response
+        return SearchResponse.model_validate(response)

avanza_mcp/tools/__init__.py

@@ -0,0 +1,8 @@
+"""MCP tools for Avanza API."""
+
+# Import to register tools via decorators
+from . import funds  # noqa: F401
+from . import market_data  # noqa: F401
+from . import search  # noqa: F401
+
+__all__ = ["search", "market_data", "funds"]