avanza-mcp 1.1.0__tar.gz → 1.3.0__tar.gz

{avanza_mcp-1.1.0 → avanza_mcp-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avanza-mcp
-Version: 1.1.0
+Version: 1.3.0
 Summary: MCP server for Avanza public market data API - Swedish stocks, funds, and more
 License-File: LICENSE.md
 Requires-Python: >=3.12
@@ -57,12 +57,67 @@ The author of this software is not responsible for any indirect damages (foresee
 | `get_fund_description` | Detailed fund description |
 | `get_fund_holdings` | Portfolio allocation (country, sector, top holdings) |
 
+### Certificates
+| Tool | Description |
+|------|-------------|
+| `filter_certificates` | Search and filter certificates with pagination |
+| `get_certificate_info` | Get detailed certificate information |
+| `get_certificate_details` | Get extended certificate details |
+
+### Warrants
+| Tool | Description |
+|------|-------------|
+| `filter_warrants` | Search and filter warrants (turbos, minis) |
+| `get_warrant_info` | Get detailed warrant information |
+| `get_warrant_details` | Get extended warrant details |
+
+### ETFs
+| Tool | Description |
+|------|-------------|
+| `filter_etfs` | Search and filter exchange-traded funds |
+| `get_etf_info` | Get detailed ETF information |
+| `get_etf_details` | Get extended ETF details |
+
+### Futures/Forwards
+| Tool | Description |
+|------|-------------|
+| `list_futures_forwards` | List available futures and forwards |
+| `get_future_forward_filter_options` | Get available filter options |
+| `get_future_forward_info` | Get contract information |
+| `get_future_forward_details` | Get extended contract details |
+
+### Additional Data
+| Tool | Description |
+|------|-------------|
+| `get_number_of_owners` | Get owner count for any instrument |
+| `get_short_selling` | Get short selling data for instruments |
+| `get_marketmaker_chart` | Get OHLC price chart data for traded products (certificates, warrants, ETFs) |
+
 ## 💡 MCP Prompts
 
+### Analysis Prompts
 - `analyze_stock` - Comprehensive stock analysis workflow
 - `compare_funds` - Multi-fund comparison template
 - `screen_dividend_stocks` - Dividend stock screening
 
+### Workflow Prompts (Teach AI Efficient Data Fetching)
+- `search_and_analyze_instrument` - Guide for finding and analyzing instruments efficiently
+- `filter_instruments_efficiently` - Guide for filtering large datasets with pagination
+- `compare_multiple_instruments` - Guide for comparing instruments efficiently
+- `explore_market_segment` - Guide for exploring market segments
+- `get_historical_analysis` - Guide for analyzing historical data
+- `screen_by_criteria` - Guide for screening by custom criteria
+
+## 📚 MCP Resources
+
+### Documentation Resources
+- `avanza://docs/usage` - Comprehensive usage guide for AI assistants
+- `avanza://docs/quick-start` - Quick reference for common tasks
+
+### Instrument Resources
+- `avanza://stock/{instrument_id}` - Get stock information as markdown
+- `avanza://fund/{instrument_id}` - Get fund information as markdown
+
 
 ### Configuration for MCP Clients
 

{avanza_mcp-1.1.0 → avanza_mcp-1.3.0}/README.md

@@ -40,12 +40,67 @@ The author of this software is not responsible for any indirect damages (foresee
 | `get_fund_description` | Detailed fund description |
 | `get_fund_holdings` | Portfolio allocation (country, sector, top holdings) |
 
+### Certificates
+| Tool | Description |
+|------|-------------|
+| `filter_certificates` | Search and filter certificates with pagination |
+| `get_certificate_info` | Get detailed certificate information |
+| `get_certificate_details` | Get extended certificate details |
+
+### Warrants
+| Tool | Description |
+|------|-------------|
+| `filter_warrants` | Search and filter warrants (turbos, minis) |
+| `get_warrant_info` | Get detailed warrant information |
+| `get_warrant_details` | Get extended warrant details |
+
+### ETFs
+| Tool | Description |
+|------|-------------|
+| `filter_etfs` | Search and filter exchange-traded funds |
+| `get_etf_info` | Get detailed ETF information |
+| `get_etf_details` | Get extended ETF details |
+
+### Futures/Forwards
+| Tool | Description |
+|------|-------------|
+| `list_futures_forwards` | List available futures and forwards |
+| `get_future_forward_filter_options` | Get available filter options |
+| `get_future_forward_info` | Get contract information |
+| `get_future_forward_details` | Get extended contract details |
+
+### Additional Data
+| Tool | Description |
+|------|-------------|
+| `get_number_of_owners` | Get owner count for any instrument |
+| `get_short_selling` | Get short selling data for instruments |
+| `get_marketmaker_chart` | Get OHLC price chart data for traded products (certificates, warrants, ETFs) |
+
 ## 💡 MCP Prompts
 
+### Analysis Prompts
 - `analyze_stock` - Comprehensive stock analysis workflow
 - `compare_funds` - Multi-fund comparison template
 - `screen_dividend_stocks` - Dividend stock screening
 
+### Workflow Prompts (Teach AI Efficient Data Fetching)
+- `search_and_analyze_instrument` - Guide for finding and analyzing instruments efficiently
+- `filter_instruments_efficiently` - Guide for filtering large datasets with pagination
+- `compare_multiple_instruments` - Guide for comparing instruments efficiently
+- `explore_market_segment` - Guide for exploring market segments
+- `get_historical_analysis` - Guide for analyzing historical data
+- `screen_by_criteria` - Guide for screening by custom criteria
+
+## 📚 MCP Resources
+
+### Documentation Resources
+- `avanza://docs/usage` - Comprehensive usage guide for AI assistants
+- `avanza://docs/quick-start` - Quick reference for common tasks
+
+### Instrument Resources
+- `avanza://stock/{instrument_id}` - Get stock information as markdown
+- `avanza://fund/{instrument_id}` - Get fund information as markdown
+
 
 ### Configuration for MCP Clients
 

{avanza_mcp-1.1.0 → avanza_mcp-1.3.0}/justfile

@@ -63,7 +63,7 @@ release version_part="patch":
     git add src/avanza_mcp/__init__.py
     git commit -m "Bump version to $new_version"
     git tag "v$new_version"
-    git push origin master
+    git push origin main
     git push origin "v$new_version"
 
     echo ""

{avanza_mcp-1.1.0 → avanza_mcp-1.3.0}/src/avanza_mcp/__init__.py

@@ -6,11 +6,13 @@ No authentication required - all endpoints are publicly accessible.
 Provides access to:
 - Stock information, quotes, and charts
 - Fund information, sustainability metrics, and performance
+- Certificates, Warrants, ETFs, Futures/Forwards data
 - Market data including order depth, trades, and broker activity
+- Additional data (number of owners, short selling info)
 - Real-time market status and trading hours
 """
 
-__version__ = "1.1.0"
+__version__ = "1.3.0"
 
 from fastmcp import FastMCP
 

{avanza_mcp-1.1.0 → avanza_mcp-1.3.0}/src/avanza_mcp/client/endpoints.py

@@ -22,6 +22,9 @@ class PublicEndpoint(Enum):
     STOCK_BROKER_TRADES = "/_api/market-guide/stock/{id}/broker-trade-summaries"
     STOCK_CHART = "/_api/price-chart/stock/{id}"  # Requires timePeriod param
 
+    # Market data - Charts (for traded products: certificates, warrants, ETFs)
+    MARKETMAKER_CHART = "/_api/price-chart/marketmaker/{id}"  # Requires timePeriod param
+
     # Market data - Funds
     FUND_INFO = "/_api/fund-guide/guide/{id}"
     FUND_SUSTAINABILITY = "/_api/fund-reference/sustainability/{id}"
@@ -29,6 +32,31 @@ class PublicEndpoint(Enum):
     FUND_CHART_PERIODS = "/_api/fund-guide/chart/timeperiods/{id}"
     FUND_DESCRIPTION = "/_api/fund-guide/description/{id}"
 
+    # Market data - Certificates
+    CERTIFICATE_FILTER = "/_api/market-certificate-filter/"
+    CERTIFICATE_INFO = "/_api/market-guide/certificate/{id}"
+    CERTIFICATE_DETAILS = "/_api/market-guide/certificate/{id}/details"
+
+    # Market data - Warrants
+    WARRANT_FILTER = "/_api/market-warrant-filter/"
+    WARRANT_INFO = "/_api/market-guide/warrant/{id}"
+    WARRANT_DETAILS = "/_api/market-guide/warrant/{id}/details"
+
+    # Market data - ETFs
+    ETF_FILTER = "/_api/market-etf-filter/"
+    ETF_INFO = "/_api/market-etf/{id}"
+    ETF_DETAILS = "/_api/market-etf/{id}/details"
+
+    # Market data - Futures/Forwards
+    FUTURE_FORWARD_MATRIX = "/_api/market-option-future-forward-list/matrix"
+    FUTURE_FORWARD_FILTER_OPTIONS = "/_api/market-option-future-forward-list/filter-options"
+    FUTURE_FORWARD_INFO = "/_api/market-guide/futureforward/{id}"
+    FUTURE_FORWARD_DETAILS = "/_api/market-guide/futureforward/{id}/details"
+
+    # Additional features
+    NUMBER_OF_OWNERS = "/_api/market-guide/number-of-owners/{id}"
+    SHORT_SELLING = "/_api/market-guide/short-selling/{id}"
+
     def format(self, **kwargs: str | int) -> str:
         """Format endpoint path with variables.
 

avanza_mcp-1.3.0/src/avanza_mcp/models/__init__.py

@@ -0,0 +1,121 @@
+"""Pydantic models for Avanza API responses."""
+
+from .certificate import (
+    CertificateDetails,
+    CertificateFilter,
+    CertificateFilterRequest,
+    CertificateFilterResponse,
+    CertificateInfo,
+    CertificateListItem,
+)
+from .chart import ChartData, ChartMetadata, ChartResolution, OHLCDataPoint
+from .common import Direction, InstrumentType, SubType, TimePeriod
+from .etf import (
+    ETFDetails,
+    ETFFilter,
+    ETFFilterRequest,
+    ETFFilterResponse,
+    ETFInfo,
+    ETFListItem,
+)
+from .filter import FilterResponse, PaginationRequest, SortBy, UnderlyingInstrument
+from .fund import (
+    FundChart,
+    FundChartPeriod,
+    FundDescription,
+    FundInfo,
+    FundPerformance,
+    FundSustainability,
+)
+from .future_forward import (
+    FutureForwardDetails,
+    FutureForwardInfo,
+    FutureForwardMatrixFilter,
+    FutureForwardMatrixRequest,
+    FutureForwardMatrixResponse,
+)
+from .instrument_data import NumberOfOwners, ShortSellingData
+from .search import SearchHit, SearchResponse
+from .stock import (
+    BrokerTradeSummary,
+    MarketplaceInfo,
+    OrderDepth,
+    Quote,
+    StockChart,
+    StockInfo,
+    Trade,
+)
+from .warrant import (
+    WarrantDetails,
+    WarrantFilter,
+    WarrantFilterRequest,
+    WarrantFilterResponse,
+    WarrantInfo,
+    WarrantListItem,
+)
+
+__all__ = [
+    # Certificate models
+    "CertificateInfo",
+    "CertificateDetails",
+    "CertificateListItem",
+    "CertificateFilter",
+    "CertificateFilterRequest",
+    "CertificateFilterResponse",
+    # Chart models
+    "ChartData",
+    "OHLCDataPoint",
+    "ChartMetadata",
+    "ChartResolution",
+    # Common
+    "InstrumentType",
+    "TimePeriod",
+    "Direction",
+    "SubType",
+    # ETF models
+    "ETFInfo",
+    "ETFDetails",
+    "ETFListItem",
+    "ETFFilter",
+    "ETFFilterRequest",
+    "ETFFilterResponse",
+    # Filter models
+    "SortBy",
+    "PaginationRequest",
+    "UnderlyingInstrument",
+    "FilterResponse",
+    # Fund models
+    "FundInfo",
+    "FundPerformance",
+    "FundSustainability",
+    "FundChart",
+    "FundChartPeriod",
+    "FundDescription",
+    # Future/Forward models
+    "FutureForwardInfo",
+    "FutureForwardDetails",
+    "FutureForwardMatrixFilter",
+    "FutureForwardMatrixRequest",
+    "FutureForwardMatrixResponse",
+    # Instrument data
+    "NumberOfOwners",
+    "ShortSellingData",
+    # Search models
+    "SearchResponse",
+    "SearchHit",
+    # Stock models
+    "StockInfo",
+    "Quote",
+    "StockChart",
+    "MarketplaceInfo",
+    "BrokerTradeSummary",
+    "Trade",
+    "OrderDepth",
+    # Warrant models
+    "WarrantInfo",
+    "WarrantDetails",
+    "WarrantListItem",
+    "WarrantFilter",
+    "WarrantFilterRequest",
+    "WarrantFilterResponse",
+]

avanza_mcp-1.3.0/src/avanza_mcp/models/certificate.py

@@ -0,0 +1,87 @@
+"""Certificate-related Pydantic models."""
+
+from pydantic import BaseModel, Field
+from .stock import MODEL_CONFIG, Quote, Listing, HistoricalClosingPrices, KeyIndicators
+from .filter import UnderlyingInstrument, SortBy, FilterResponse
+
+
+class CertificateListItem(BaseModel):
+    """Certificate in filter/list results."""
+
+    model_config = MODEL_CONFIG
+
+    orderbookId: str
+    countryCode: str
+    name: str
+    direction: str
+    marketplaceCode: str
+    issuer: str
+    hasPosition: bool
+    totalValueTraded: float | None = None
+    underlyingInstrument: UnderlyingInstrument | None = None
+    leverage: float | None = None
+    spread: float | None = None
+    buyPrice: float | None = None
+    sellPrice: float | None = None
+
+
+class CertificateInfo(BaseModel):
+    """Detailed certificate information."""
+
+    model_config = MODEL_CONFIG
+
+    orderbookId: str
+    name: str
+    isin: str | None = None
+    tradable: str | None = None
+    listing: Listing | None = None
+    historicalClosingPrices: HistoricalClosingPrices | None = None
+    keyIndicators: KeyIndicators | None = None
+    quote: Quote | None = None
+    type: str | None = None
+    assetCategory: str | None = None
+    category: str | None = None
+    subCategory: str | None = None
+
+
+class CertificateDetails(BaseModel):
+    """Detailed certificate extended information."""
+
+    model_config = MODEL_CONFIG
+
+    # Flexible structure to handle various response formats
+    pass
+
+
+class CertificateFilter(BaseModel):
+    """Filter criteria for certificates."""
+
+    model_config = MODEL_CONFIG
+
+    directions: list[str] = Field(default_factory=list)
+    leverages: list[float] = Field(default_factory=list)
+    underlyingInstruments: list[str] = Field(default_factory=list)
+    categories: list[str] = Field(default_factory=list)
+    exposures: list[str] = Field(default_factory=list)
+    issuers: list[str] = Field(default_factory=list)
+
+
+class CertificateFilterRequest(BaseModel):
+    """Complete filter request for certificates."""
+
+    model_config = MODEL_CONFIG
+
+    filter: CertificateFilter
+    offset: int = 0
+    limit: int = 20
+    sortBy: SortBy
+
+
+class CertificateFilterResponse(FilterResponse):
+    """Response from certificate filter endpoint."""
+
+    model_config = MODEL_CONFIG
+
+    certificates: list[CertificateListItem]
+    filter: CertificateFilter | None = None
+    sortBy: SortBy | None = None

avanza_mcp-1.3.0/src/avanza_mcp/models/chart.py

@@ -0,0 +1,51 @@
+"""Chart data models for price charts."""
+
+from pydantic import BaseModel, Field
+
+from .stock import MODEL_CONFIG
+
+
+class OHLCDataPoint(BaseModel):
+    """OHLC (Open-High-Low-Close) candlestick data point."""
+
+    model_config = MODEL_CONFIG
+
+    timestamp: int
+    open: float
+    close: float
+    low: float
+    high: float
+    totalVolumeTraded: int
+
+
+class ChartResolution(BaseModel):
+    """Chart resolution metadata."""
+
+    model_config = MODEL_CONFIG
+
+    chartResolution: str
+    availableResolutions: list[str]
+
+
+class ChartMetadata(BaseModel):
+    """Chart metadata."""
+
+    model_config = MODEL_CONFIG
+
+    resolution: ChartResolution
+
+
+class ChartData(BaseModel):
+    """Price chart data response.
+
+    Used for both stock charts and marketmaker charts.
+    """
+
+    model_config = MODEL_CONFIG
+
+    ohlc: list[OHLCDataPoint]
+    metadata: ChartMetadata
+    from_date: str | None = Field(default=None, alias="from")  # 'from' is a Python keyword
+    to: str | None = None
+    marketMaker: list[dict] | None = None  # Only present in marketmaker charts
+    previousClosingPrice: float | None = None  # Only present in some charts

{avanza_mcp-1.1.0 → avanza_mcp-1.3.0}/src/avanza_mcp/models/common.py

@@ -48,3 +48,18 @@ class Resolution(str, Enum):
     DAY = "DAY"
     WEEK = "WEEK"
     MONTH = "MONTH"
+
+
+class Direction(str, Enum):
+    """Direction for leveraged instruments."""
+
+    LONG = "long"
+    SHORT = "short"
+
+
+class SubType(str, Enum):
+    """Sub-types for warrants and certificates."""
+
+    TURBO = "TURBO"
+    MINI = "MINI"
+    KNOCK_OUT = "KNOCK_OUT"

avanza_mcp-1.3.0/src/avanza_mcp/models/etf.py

@@ -0,0 +1,92 @@
+"""ETF-related Pydantic models."""
+
+from pydantic import BaseModel, Field
+
+from .filter import FilterResponse, SortBy
+from .stock import (
+    MODEL_CONFIG,
+    HistoricalClosingPrices,
+    Listing,
+    MarketPlace,
+    Quote,
+)
+
+
+class ETFListItem(BaseModel):
+    """ETF in filter/list results."""
+
+    model_config = MODEL_CONFIG
+
+    orderbookId: str
+    countryCode: str
+    name: str
+    directYield: float | None = None
+    oneDayChangePercent: float | None = None
+    threeYearsChangePercent: float | None = None
+    managementFee: float | None = None
+    productFee: float | None = None
+    numberOfOwners: int | None = None
+    riskScore: int | None = None
+    hasPosition: bool = False
+
+
+class ETFInfo(BaseModel):
+    """Detailed ETF information."""
+
+    model_config = MODEL_CONFIG
+
+    orderbookId: str
+    name: str
+    isin: str | None = None
+    tradable: str | None = None
+    listing: Listing | None = None
+    marketPlace: MarketPlace | None = None
+    historicalClosingPrices: HistoricalClosingPrices | None = None
+    keyIndicators: dict | None = None
+    quote: Quote | None = None
+    type: str | None = None
+
+
+class ETFDetails(BaseModel):
+    """Detailed ETF extended information."""
+
+    model_config = MODEL_CONFIG
+
+    # Flexible structure to handle various response formats
+    pass
+
+
+class ETFFilter(BaseModel):
+    """Filter criteria for ETFs."""
+
+    model_config = MODEL_CONFIG
+
+    assetCategories: list[str] = Field(default_factory=list)
+    subCategories: list[str] = Field(default_factory=list)
+    exposures: list[str] = Field(default_factory=list)
+    riskScores: list[str] = Field(default_factory=list)
+    directions: list[str] = Field(default_factory=list)
+    issuers: list[str] = Field(default_factory=list)
+    currencyCodes: list[str] = Field(default_factory=list)
+
+
+class ETFFilterRequest(BaseModel):
+    """Complete filter request for ETFs."""
+
+    model_config = MODEL_CONFIG
+
+    filter: ETFFilter
+    offset: int = 0
+    limit: int = 20
+    sortBy: SortBy
+
+
+class ETFFilterResponse(FilterResponse):
+    """Response from ETF filter endpoint."""
+
+    model_config = MODEL_CONFIG
+
+    etfs: list[ETFListItem]
+    filter: ETFFilter | None = None
+    filterOptions: dict | None = None  # Available filter options
+    sortBy: SortBy | None = None

avanza_mcp-1.3.0/src/avanza_mcp/models/filter.py

@@ -0,0 +1,51 @@
+"""Shared filter models for list/filter endpoints."""
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing import Literal
+
+
+# Standard model config for all models
+MODEL_CONFIG = ConfigDict(
+    populate_by_name=True,
+    str_strip_whitespace=True,
+    validate_assignment=True,
+    extra="allow",  # Don't fail on extra fields from API
+)
+
+
+class SortBy(BaseModel):
+    """Sort configuration for filter endpoints."""
+
+    model_config = MODEL_CONFIG
+
+    field: str
+    order: Literal["asc", "desc"]
+
+
+class PaginationRequest(BaseModel):
+    """Pagination parameters for filter endpoints."""
+
+    model_config = MODEL_CONFIG
+
+    offset: int = Field(default=0, ge=0)
+    limit: int = Field(default=20, ge=1, le=100)
+
+
+class UnderlyingInstrument(BaseModel):
+    """Underlying instrument for derivatives."""
+
+    model_config = MODEL_CONFIG
+
+    name: str | None = None
+    orderbookId: str | None = None
+    instrumentType: str | None = None
+    countryCode: str | None = None
+
+
+class FilterResponse(BaseModel):
+    """Base response for filter endpoints with pagination."""
+
+    model_config = MODEL_CONFIG
+
+    pagination: dict | None = None
+    totalNumberOfOrderbooks: int | None = None

avanza_mcp-1.3.0/src/avanza_mcp/models/future_forward.py

@@ -0,0 +1,63 @@
+"""Future and forward contract models."""
+
+from pydantic import BaseModel
+
+from .filter import SortBy
+from .stock import MODEL_CONFIG, HistoricalClosingPrices, Listing, Quote
+
+
+class FutureForwardInfo(BaseModel):
+    """Detailed future/forward information."""
+
+    model_config = MODEL_CONFIG
+
+    orderbookId: str
+    name: str
+    isin: str | None = None
+    tradable: str | None = None
+    listing: Listing | None = None
+    historicalClosingPrices: HistoricalClosingPrices | None = None
+    keyIndicators: dict | None = None
+    quote: Quote | None = None
+    type: str | None = None
+    underlying: dict | None = None
+
+
+class FutureForwardDetails(BaseModel):
+    """Detailed future/forward extended information."""
+
+    model_config = MODEL_CONFIG
+
+    # Flexible structure to handle various response formats
+    pass
+
+
+class FutureForwardMatrixFilter(BaseModel):
+    """Filter criteria for futures/forwards matrix."""
+
+    model_config = MODEL_CONFIG
+
+    underlyingInstruments: list[str] = []
+    optionTypes: list[str] = []
+    endDates: list[str] = []
+    callIndicators: list[str] = []
+
+
+class FutureForwardMatrixRequest(BaseModel):
+    """Request for futures/forwards matrix list."""
+
+    model_config = MODEL_CONFIG
+
+    filter: FutureForwardMatrixFilter
+    offset: int = 0
+    limit: int = 20
+    sortBy: SortBy
+
+
+class FutureForwardMatrixResponse(BaseModel):
+    """Response from futures/forwards matrix endpoint."""
+
+    model_config = MODEL_CONFIG
+
+    # Flexible structure to handle matrix response
+    # The actual structure will be preserved via extra="allow"