yfin-mcp 0.2.4__py3-none-any.whl → 0.2.5__py3-none-any.whl

yfin_mcp/__init__.py

@@ -0,0 +1 @@
+# yfin_mcp package

yfin_mcp/__main__.py

@@ -0,0 +1,4 @@
+from .server import main
+
+if __name__ == "__main__":
+    main()

yfin_mcp/cache_manager.py

@@ -0,0 +1,150 @@
+"""
+Thread-safe LRU cache manager with TTL support for Yahoo Finance MCP server.
+"""
+
+import threading
+import time
+from collections import OrderedDict
+from typing import Any, Callable, Optional, Tuple
+
+
+class CacheManager:
+    """Thread-safe LRU cache with TTL (Time To Live) support."""
+    
+    def __init__(self, max_size: int = 100):
+        """
+        Initialize cache manager.
+        
+        Args:
+            max_size: Maximum number of entries in cache (LRU eviction)
+        """
+        self._cache: OrderedDict[str, Tuple[Any, float, float]] = OrderedDict()
+        self._max_size = max_size
+        self._lock = threading.Lock()
+        self._hits = 0
+        self._misses = 0
+    
+    def get(self, key: str) -> Optional[Tuple[Any, float]]:
+        """
+        Get value from cache if it exists and hasn't expired.
+        
+        Args:
+            key: Cache key
+            
+        Returns:
+            Tuple of (value, age_seconds) if found and valid, None otherwise
+        """
+        with self._lock:
+            if key not in self._cache:
+                self._misses += 1
+                return None
+            
+            value, timestamp, ttl = self._cache[key]
+            age = time.time() - timestamp
+            
+            # Check if expired
+            if age > ttl:
+                del self._cache[key]
+                self._misses += 1
+                return None
+            
+            # Move to end (most recently used)
+            self._cache.move_to_end(key)
+            self._hits += 1
+            return (value, age)
+    
+    def set(self, key: str, value: Any, ttl_seconds: float):
+        """
+        Set value in cache with TTL.
+        
+        Args:
+            key: Cache key
+            value: Value to cache
+            ttl_seconds: Time to live in seconds
+        """
+        with self._lock:
+            # Remove oldest if at capacity
+            if len(self._cache) >= self._max_size and key not in self._cache:
+                self._cache.popitem(last=False)
+            
+            self._cache[key] = (value, time.time(), ttl_seconds)
+            self._cache.move_to_end(key)
+    
+    def get_or_set(
+        self,
+        key: str,
+        factory_func: Callable[[], Any],
+        ttl_seconds: float
+    ) -> Tuple[Any, Optional[float]]:
+        """
+        Get from cache or compute and cache if missing/expired.
+        
+        Args:
+            key: Cache key
+            factory_func: Function to call if cache miss
+            ttl_seconds: TTL for new cache entries
+            
+        Returns:
+            Tuple of (value, age_seconds). age_seconds is None for cache miss.
+        """
+        # Try to get from cache
+        cached = self.get(key)
+        if cached is not None:
+            return cached
+        
+        # Cache miss - compute value
+        try:
+            value = factory_func()
+            self.set(key, value, ttl_seconds)
+            return (value, None)  # None age indicates fresh data
+        except Exception as e:
+            # Don't cache errors
+            raise e
+    
+    def clear(self):
+        """Clear all cache entries."""
+        with self._lock:
+            self._cache.clear()
+            self._hits = 0
+            self._misses = 0
+    
+    def get_stats(self) -> dict:
+        """
+        Get cache statistics.
+        
+        Returns:
+            Dict with hits, misses, size, and hit rate
+        """
+        with self._lock:
+            total = self._hits + self._misses
+            hit_rate = (self._hits / total * 100) if total > 0 else 0
+            
+            return {
+                "hits": self._hits,
+                "misses": self._misses,
+                "size": len(self._cache),
+                "max_size": self._max_size,
+                "hit_rate": f"{hit_rate:.1f}%"
+            }
+
+
+# Global cache instance
+_global_cache: Optional[CacheManager] = None
+_cache_lock = threading.Lock()
+
+
+def get_cache() -> CacheManager:
+    """
+    Get the global cache instance (singleton pattern).
+    
+    Returns:
+        Global CacheManager instance
+    """
+    global _global_cache
+    
+    if _global_cache is None:
+        with _cache_lock:
+            if _global_cache is None:
+                _global_cache = CacheManager(max_size=100)
+    
+    return _global_cache

yfin_mcp/pagination_utils.py

@@ -0,0 +1,285 @@
+"""
+Pagination utilities for Yahoo Finance MCP server.
+Provides token-based pagination and plain text formatting for LLM-friendly responses.
+"""
+
+import json
+from dataclasses import dataclass
+from typing import Any, List, Optional, Union
+
+import pandas as pd
+
+
+@dataclass
+class PaginationResult:
+    """Result of pagination operation."""
+    formatted_text: str
+    page: int
+    total_pages: int
+    total_items: int
+    items_on_page: int
+
+
+def estimate_tokens(text: str) -> int:
+    """
+    Estimate token count for text.
+    Uses conservative estimate of ~4 characters per token.
+    
+    Args:
+        text: Text to estimate tokens for
+        
+    Returns:
+        Estimated token count
+    """
+    return len(text) // 4
+
+
+def format_dataframe_as_table(df: pd.DataFrame, max_col_width: int = 15) -> str:
+    """
+    Format DataFrame as plain text table with fixed-width columns.
+    
+    Args:
+        df: DataFrame to format
+        max_col_width: Maximum column width
+        
+    Returns:
+        Formatted table string
+    """
+    if df.empty:
+        return "No data available"
+    
+    # Convert all columns to string and truncate
+    formatted_data = []
+    for _, row in df.iterrows():
+        formatted_row = []
+        for val in row:
+            str_val = str(val)
+            if len(str_val) > max_col_width:
+                str_val = str_val[:max_col_width-2] + ".."
+            formatted_row.append(str_val)
+        formatted_data.append(formatted_row)
+    
+    # Get column names
+    columns = [str(col)[:max_col_width] for col in df.columns]
+    
+    # Build table
+    lines = []
+    
+    # Header
+    header = " | ".join(f"{col:<{max_col_width}}" for col in columns)
+    lines.append(header)
+    lines.append("-" * len(header))
+    
+    # Rows
+    for row in formatted_data:
+        row_str = " | ".join(f"{val:<{max_col_width}}" for val in row)
+        lines.append(row_str)
+    
+    return "\n".join(lines)
+
+
+def format_dict_as_text(data: dict, indent: int = 0) -> str:
+    """
+    Format dictionary as plain text with key-value pairs.
+    
+    Args:
+        data: Dictionary to format
+        indent: Indentation level
+        
+    Returns:
+        Formatted text string
+    """
+    lines = []
+    indent_str = "  " * indent
+    
+    for key, value in data.items():
+        if isinstance(value, dict):
+            lines.append(f"{indent_str}{key}:")
+            lines.append(format_dict_as_text(value, indent + 1))
+        elif isinstance(value, list):
+            lines.append(f"{indent_str}{key}: {len(value)} items")
+        else:
+            lines.append(f"{indent_str}{key}: {value}")
+    
+    return "\n".join(lines)
+
+
+def paginate_by_tokens(
+    data: Union[pd.DataFrame, List[dict], dict],
+    page: int,
+    max_tokens: int = 6000,
+    data_type: str = "table",
+    title: Optional[str] = None,
+    cache_age: Optional[float] = None,
+) -> PaginationResult:
+    """
+    Paginate data based on token limit.
+    
+    Args:
+        data: Data to paginate (DataFrame, list of dicts, or dict)
+        page: Page number (1-indexed)
+        max_tokens: Maximum tokens per page
+        data_type: Type of data ("table" or "dict")
+        title: Optional title for the page
+        cache_age: Optional cache age in seconds
+        
+    Returns:
+        PaginationResult with formatted text and metadata
+    """
+    # Convert data to list of items for pagination
+    if isinstance(data, pd.DataFrame):
+        total_items = len(data)
+        items = data
+    elif isinstance(data, list):
+        total_items = len(data)
+        items = data
+    elif isinstance(data, dict):
+        total_items = len(data)
+        items = data
+    else:
+        raise ValueError(f"Unsupported data type: {type(data)}")
+    
+    if total_items == 0:
+        return PaginationResult(
+            formatted_text="No data available",
+            page=1,
+            total_pages=1,
+            total_items=0,
+            items_on_page=0
+        )
+    
+    # Calculate items per page dynamically
+    # Start with all items and reduce until under token limit
+    items_per_page = total_items
+    test_data = items
+    
+    while items_per_page > 0:
+        # Get subset for this page size
+        if isinstance(data, pd.DataFrame):
+            test_data = data.iloc[:items_per_page]
+            test_text = format_dataframe_as_table(test_data)
+        elif isinstance(data, dict):
+            test_items = dict(list(data.items())[:items_per_page])
+            test_text = format_dict_as_text(test_items)
+        else:
+            test_items = data[:items_per_page]
+            test_text = "\n".join(str(item) for item in test_items)
+        
+        # Check token count
+        if estimate_tokens(test_text) <= max_tokens * 0.8:  # Leave 20% margin
+            break
+        
+        # Reduce page size
+        items_per_page = max(1, items_per_page // 2)
+    
+    # Calculate pagination
+    total_pages = (total_items + items_per_page - 1) // items_per_page
+    page = max(1, min(page, total_pages))  # Clamp page number
+    
+    start_idx = (page - 1) * items_per_page
+    end_idx = min(start_idx + items_per_page, total_items)
+    
+    # Get page data
+    if isinstance(data, pd.DataFrame):
+        page_data = data.iloc[start_idx:end_idx]
+        content = format_dataframe_as_table(page_data)
+    elif isinstance(data, dict):
+        page_items = dict(list(data.items())[start_idx:end_idx])
+        content = format_dict_as_text(page_items)
+    else:
+        page_items = data[start_idx:end_idx]
+        content = "\n".join(str(item) for item in page_items)
+    
+    # Build formatted output
+    lines = []
+    lines.append("=" * 70)
+    if title:
+        lines.append(f"📊 {title}")
+        lines.append("=" * 70)
+    lines.append("")
+    lines.append(content)
+    lines.append("")
+    lines.append("─" * 70)
+    lines.append(f"📄 PAGE {page} of {total_pages} | Showing items {start_idx + 1}-{end_idx} of {total_items} total")
+    lines.append(f"📊 Estimated tokens: {estimate_tokens(content)} / {max_tokens} max")
+    lines.append("─" * 70)
+    lines.append("")
+    
+    # Navigation guidance
+    if total_pages > 1:
+        lines.append("🔍 NAVIGATION:")
+        if page < total_pages:
+            lines.append(f"  • Next page: Use page={page + 1} to see items {end_idx + 1}-{min(end_idx + items_per_page, total_items)}")
+        if page > 1:
+            lines.append(f"  • Previous page: Use page={page - 1}")
+        lines.append(f"  • Export all data: Add export_path=\"./data.json\"")
+        lines.append("")
+    
+    # Cache info
+    if cache_age is not None:
+        if cache_age == 0 or cache_age is None:
+            lines.append("💾 CACHE: Fresh data (not cached)")
+        else:
+            lines.append(f"💾 CACHE: Data cached (age: {cache_age:.1f} seconds)")
+    
+    lines.append("=" * 70)
+    
+    formatted_text = "\n".join(lines)
+    
+    return PaginationResult(
+        formatted_text=formatted_text,
+        page=page,
+        total_pages=total_pages,
+        total_items=total_items,
+        items_on_page=end_idx - start_idx
+    )
+
+
+def export_to_json(data: Union[pd.DataFrame, List[dict], dict], file_path: str) -> str:
+    """
+    Export data to JSON file.
+    
+    Args:
+        data: Data to export
+        file_path: Path to save JSON file
+        
+    Returns:
+        Success message with file info
+    """
+    # Convert DataFrame to dict
+    if isinstance(data, pd.DataFrame):
+        export_data = data.to_dict(orient="records")
+    else:
+        export_data = data
+    
+    # Write to file
+    with open(file_path, 'w', encoding='utf-8') as f:
+        json.dump(export_data, f, indent=2, default=str)
+    
+    # Get file size
+    import os
+    file_size = os.path.getsize(file_path)
+    size_kb = file_size / 1024
+    
+    # Count items
+    if isinstance(export_data, list):
+        item_count = len(export_data)
+    elif isinstance(export_data, dict):
+        item_count = len(export_data)
+    else:
+        item_count = 1
+    
+    # Build response
+    lines = []
+    lines.append("=" * 70)
+    lines.append("✅ DATA EXPORTED SUCCESSFULLY")
+    lines.append("=" * 70)
+    lines.append("")
+    lines.append(f"📁 File: {file_path}")
+    lines.append(f"📊 Size: {size_kb:.2f} KB")
+    lines.append(f"📝 Items: {item_count}")
+    lines.append("")
+    lines.append("The complete dataset has been saved to the specified file.")
+    lines.append("=" * 70)
+    
+    return "\n".join(lines)

yfin_mcp/server.py

@@ -0,0 +1,566 @@
+import json
+from enum import Enum
+from typing import Optional
+
+import pandas as pd
+import yfinance as yf
+from mcp.server.fastmcp import FastMCP
+
+from .cache_manager import get_cache
+from .pagination_utils import paginate_by_tokens, export_to_json
+
+
+# Define an enum for the type of financial statement
+class FinancialType(str, Enum):
+    income_stmt = "income_stmt"
+    quarterly_income_stmt = "quarterly_income_stmt"
+    balance_sheet = "balance_sheet"
+    quarterly_balance_sheet = "quarterly_balance_sheet"
+    cashflow = "cashflow"
+    quarterly_cashflow = "quarterly_cashflow"
+
+
+class HolderType(str, Enum):
+    major_holders = "major_holders"
+    institutional_holders = "institutional_holders"
+    mutualfund_holders = "mutualfund_holders"
+    insider_transactions = "insider_transactions"
+    insider_purchases = "insider_purchases"
+    insider_roster_holders = "insider_roster_holders"
+
+
+class RecommendationType(str, Enum):
+    recommendations = "recommendations"
+    upgrades_downgrades = "upgrades_downgrades"
+
+
+# Initialize FastMCP server
+yfinance_server = FastMCP(
+    "yfinance",
+    instructions="""
+# Yahoo Finance MCP Server
+
+This server is used to get information about a given ticker symbol from yahoo finance.
+
+Available tools:
+- get_historical_stock_prices: Get historical stock prices for a given ticker symbol from yahoo finance. Include the following information: Date, Open, High, Low, Close, Volume, Adj Close.
+- get_stock_info: Get stock information for a given ticker symbol from yahoo finance. Include the following information: Stock Price & Trading Info, Company Information, Financial Metrics, Earnings & Revenue, Margins & Returns, Dividends, Balance Sheet, Ownership, Analyst Coverage, Risk Metrics, Other.
+- get_yahoo_finance_news: Get news for a given ticker symbol from yahoo finance.
+- get_stock_actions: Get stock dividends and stock splits for a given ticker symbol from yahoo finance.
+- get_financial_statement: Get financial statement for a given ticker symbol from yahoo finance. You can choose from the following financial statement types: income_stmt, quarterly_income_stmt, balance_sheet, quarterly_balance_sheet, cashflow, quarterly_cashflow.
+- get_holder_info: Get holder information for a given ticker symbol from yahoo finance. You can choose from the following holder types: major_holders, institutional_holders, mutualfund_holders, insider_transactions, insider_purchases, insider_roster_holders.
+- get_option_expiration_dates: Fetch the available options expiration dates for a given ticker symbol.
+- get_option_chain: Fetch the option chain for a given ticker symbol, expiration date, and option type.
+- get_recommendations: Get recommendations or upgrades/downgrades for a given ticker symbol from yahoo finance. You can also specify the number of months back to get upgrades/downgrades for, default is 12.
+""",
+)
+
+
+@yfinance_server.tool(
+    name="get_historical_stock_prices",
+    description="""Get historical stock prices for a given ticker symbol from yahoo finance. Include the following information: Date, Open, High, Low, Close, Volume, Adj Close.
+Args:
+    ticker: str
+        The ticker symbol of the stock to get historical prices for, e.g. "AAPL"
+    period : str
+        Valid periods: 1d,5d,1mo,3mo,6mo,1y,2y,5y,10y,ytd,max
+        Either Use period parameter or use start and end
+        Default is "1mo"
+    interval : str
+        Valid intervals: 1m,2m,5m,15m,30m,60m,90m,1h,1d,5d,1wk,1mo,3mo
+        Intraday data cannot extend last 60 days
+        Default is "1d"
+""",
+)
+async def get_historical_stock_prices(
+    ticker: str,
+    period: str = "1mo",
+    interval: str = "1d",
+    page: int = 1,
+    export_path: Optional[str] = None,
+) -> str:
+    """Get historical stock prices for a given ticker symbol with pagination
+
+    Args:
+        ticker: The ticker symbol, e.g. "AAPL"
+        period: Valid periods: 1d,5d,1mo,3mo,6mo,1y,2y,5y,10y,ytd,max (default: "1mo")
+        interval: Valid intervals: 1m,2m,5m,15m,30m,60m,90m,1h,1d,5d,1wk,1mo,3mo (default: "1d")
+        page: Page number for pagination (default: 1)
+        export_path: Optional path to export full data as JSON file
+    """
+    cache = get_cache()
+    cache_key = f"hist_{ticker}_{period}_{interval}"
+    
+    # Try to get from cache
+    hist_data, cache_age = cache.get_or_set(
+        cache_key,
+        lambda: yf.Ticker(ticker).history(period=period, interval=interval),
+        ttl_seconds=300  # 5 minutes for price data
+    )
+    
+    if hist_data is None or hist_data.empty:
+        return f"No historical data available for {ticker}"
+    
+    # Reset index to make Date a column
+    hist_data = hist_data.reset_index()
+    
+    # Export if requested
+    if export_path:
+        return export_to_json(hist_data, export_path)
+    
+    # Paginate the response
+    result = paginate_by_tokens(
+        data=hist_data,
+        page=page,
+        max_tokens=6000,
+        data_type="table",
+        title=f"HISTORICAL STOCK PRICES - {ticker} ({period}, {interval})",
+        cache_age=cache_age,
+    )
+    
+    return result.formatted_text
+
+
+@yfinance_server.tool(
+    name="get_stock_info",
+    description="""Get stock information for a given ticker symbol from yahoo finance. Include the following information:
+Stock Price & Trading Info, Company Information, Financial Metrics, Earnings & Revenue, Margins & Returns, Dividends, Balance Sheet, Ownership, Analyst Coverage, Risk Metrics, Other.
+
+Args:
+    ticker: str
+        The ticker symbol of the stock to get information for, e.g. "AAPL"
+""",
+)
+async def get_stock_info(
+    ticker: str,
+    fields: Optional[list] = None,
+    page: int = 1,
+    export_path: Optional[str] = None,
+) -> str:
+    """Get stock information with optional field filtering and pagination"""
+    cache = get_cache()
+    cache_key = f"info_{ticker}"
+    
+    info, cache_age = cache.get_or_set(
+        cache_key,
+        lambda: yf.Ticker(ticker).info,
+        ttl_seconds=300
+    )
+    
+    if not info:
+        return f"No information available for {ticker}"
+    
+    # Filter fields if specified
+    info_to_display = {k: info.get(k) for k in fields if k in info} if fields else info
+    
+    if export_path:
+        return export_to_json(info_to_display, export_path)
+    
+    result = paginate_by_tokens(
+        data=info_to_display,
+        page=page,
+        max_tokens=6000,
+        data_type="dict",
+        title=f"STOCK INFO - {ticker}",
+        cache_age=cache_age,
+    )
+    
+    return result.formatted_text
+
+
+@yfinance_server.tool(
+    name="get_yahoo_finance_news",
+    description="""Get news for a given ticker symbol from yahoo finance.
+
+Args:
+    ticker: str
+        The ticker symbol of the stock to get news for, e.g. "AAPL"
+""",
+)
+async def get_yahoo_finance_news(
+    ticker: str,
+    page: int = 1,
+    export_path: Optional[str] = None,
+) -> str:
+    """Get news for a given ticker symbol with pagination"""
+    cache = get_cache()
+    cache_key = f"news_{ticker}"
+    
+    news_data, cache_age = cache.get_or_set(
+        cache_key,
+        lambda: yf.Ticker(ticker).news,
+        ttl_seconds=300  # 5 minutes
+    )
+    
+    if not news_data:
+        return f"No news found for {ticker}"
+    
+    # Convert to structured format
+    news_list = []
+    for item in news_data:
+        if item.get("content", {}).get("contentType", "") == "STORY":
+            news_list.append({
+                "title": item.get("content", {}).get("title", ""),
+                "summary": item.get("content", {}).get("summary", ""),
+                "url": item.get("content", {}).get("canonicalUrl", {}).get("url", ""),
+                "provider": item.get("content", {}).get("provider", {}).get("displayName", "")
+            })
+    
+    if not news_list:
+        return f"No news articles found for {ticker}"
+    
+    if export_path:
+        return export_to_json(news_list, export_path)
+    
+    result = paginate_by_tokens(
+        data=pd.DataFrame(news_list),
+        page=page,
+        max_tokens=6000,
+        data_type="table",
+        title=f"YAHOO FINANCE NEWS - {ticker}",
+        cache_age=cache_age,
+    )
+    
+    return result.formatted_text
+
+
+@yfinance_server.tool(
+    name="get_stock_actions",
+    description="""Get stock dividends and stock splits for a given ticker symbol from yahoo finance.
+
+Args:
+    ticker: str
+        The ticker symbol of the stock to get stock actions for, e.g. "AAPL"
+""",
+)
+async def get_stock_actions(
+    ticker: str,
+    page: int = 1,
+    export_path: Optional[str] = None,
+) -> str:
+    """Get stock dividends and splits with pagination"""
+    cache = get_cache()
+    cache_key = f"actions_{ticker}"
+    
+    actions_data, cache_age = cache.get_or_set(
+        cache_key,
+        lambda: yf.Ticker(ticker).actions,
+        ttl_seconds=3600  # 1 hour - less volatile
+    )
+    
+    if actions_data is None or actions_data.empty:
+        return f"No stock actions available for {ticker}"
+    
+    actions_data = actions_data.reset_index()
+    
+    if export_path:
+        return export_to_json(actions_data, export_path)
+    
+    result = paginate_by_tokens(
+        data=actions_data,
+        page=page,
+        max_tokens=6000,
+        data_type="table",
+        title=f"STOCK ACTIONS - {ticker}",
+        cache_age=cache_age,
+    )
+    
+    return result.formatted_text
+
+
+@yfinance_server.tool(
+    name="get_financial_statement",
+    description="""Get financial statement for a given ticker symbol from yahoo finance. You can choose from the following financial statement types: income_stmt, quarterly_income_stmt, balance_sheet, quarterly_balance_sheet, cashflow, quarterly_cashflow.
+
+Args:
+    ticker: str
+        The ticker symbol of the stock to get financial statement for, e.g. "AAPL"
+    financial_type: str
+        The type of financial statement to get. You can choose from the following financial statement types: income_stmt, quarterly_income_stmt, balance_sheet, quarterly_balance_sheet, cashflow, quarterly_cashflow.
+""",
+)
+async def get_financial_statement(
+    ticker: str,
+    financial_type: str,
+    export_path: Optional[str] = None,
+) -> str:
+    """Get financial statement with caching and export"""
+    cache = get_cache()
+    cache_key = f"financial_{ticker}_{financial_type}"
+    
+    def fetch_statement():
+        company = yf.Ticker(ticker)
+        if financial_type == FinancialType.income_stmt:
+            return company.income_stmt
+        elif financial_type == FinancialType.quarterly_income_stmt:
+            return company.quarterly_income_stmt
+        elif financial_type == FinancialType.balance_sheet:
+            return company.balance_sheet
+        elif financial_type == FinancialType.quarterly_balance_sheet:
+            return company.quarterly_balance_sheet
+        elif financial_type == FinancialType.cashflow:
+            return company.cashflow
+        elif financial_type == FinancialType.quarterly_cashflow:
+            return company.quarterly_cashflow
+        else:
+            return None
+    
+    financial_statement, cache_age = cache.get_or_set(
+        cache_key,
+        fetch_statement,
+        ttl_seconds=3600  # 1 hour
+    )
+    
+    if financial_statement is None or financial_statement.empty:
+        return f"No financial statement data available for {ticker} ({financial_type})"
+    
+    # Convert to list of dicts for export
+    result = []
+    for column in financial_statement.columns:
+        if isinstance(column, pd.Timestamp):
+            date_str = column.strftime("%Y-%m-%d")
+        else:
+            date_str = str(column)
+        
+        date_obj = {"date": date_str}
+        for index, value in financial_statement[column].items():
+            date_obj[index] = None if pd.isna(value) else value
+        result.append(date_obj)
+    
+    if export_path:
+        return export_to_json(result, export_path)
+    
+    # Format as plain text table
+    df = pd.DataFrame(result)
+    result_text = paginate_by_tokens(
+        data=df,
+        page=1,  # Financial statements are small, no pagination needed
+        max_tokens=6000,
+        data_type="table",
+        title=f"FINANCIAL STATEMENT - {ticker} ({financial_type})",
+        cache_age=cache_age,
+    )
+    
+    return result_text.formatted_text
+
+
+@yfinance_server.tool(
+    name="get_holder_info",
+    description="""Get holder information for a given ticker symbol from yahoo finance. You can choose from the following holder types: major_holders, institutional_holders, mutualfund_holders, insider_transactions, insider_purchases, insider_roster_holders.
+
+Args:
+    ticker: str
+        The ticker symbol of the stock to get holder information for, e.g. "AAPL"
+    holder_type: str
+        The type of holder information to get. You can choose from the following holder types: major_holders, institutional_holders, mutualfund_holders, insider_transactions, insider_purchases, insider_roster_holders.
+""",
+)
+async def get_holder_info(
+    ticker: str,
+    holder_type: str,
+    page: int = 1,
+    export_path: Optional[str] = None,
+) -> str:
+    """Get holder information with pagination"""
+    cache = get_cache()
+    cache_key = f"holder_{ticker}_{holder_type}"
+    
+    def fetch_holder_data():
+        company = yf.Ticker(ticker)
+        if holder_type == HolderType.major_holders:
+            return company.major_holders.reset_index(names="metric")
+        elif holder_type == HolderType.institutional_holders:
+            return company.institutional_holders
+        elif holder_type == HolderType.mutualfund_holders:
+            return company.mutualfund_holders
+        elif holder_type == HolderType.insider_transactions:
+            return company.insider_transactions
+        elif holder_type == HolderType.insider_purchases:
+            return company.insider_purchases
+        elif holder_type == HolderType.insider_roster_holders:
+            return company.insider_roster_holders
+        else:
+            return None
+    
+    holder_data, cache_age = cache.get_or_set(
+        cache_key,
+        fetch_holder_data,
+        ttl_seconds=3600  # 1 hour
+    )
+    
+    if holder_data is None or holder_data.empty:
+        return f"No holder information available for {ticker} ({holder_type})"
+    
+    if export_path:
+        return export_to_json(holder_data, export_path)
+    
+    result = paginate_by_tokens(
+        data=holder_data,
+        page=page,
+        max_tokens=6000,
+        data_type="table",
+        title=f"HOLDER INFO - {ticker} ({holder_type})",
+        cache_age=cache_age,
+    )
+    
+    return result.formatted_text
+
+
+@yfinance_server.tool(
+    name="get_option_expiration_dates",
+    description="""Fetch the available options expiration dates for a given ticker symbol.
+
+Args:
+    ticker: str
+        The ticker symbol of the stock to get option expiration dates for, e.g. "AAPL"
+""",
+)
+async def get_option_expiration_dates(ticker: str) -> str:
+    """Fetch the available options expiration dates for a given ticker symbol."""
+
+    company = yf.Ticker(ticker)
+    try:
+        if company.isin is None:
+            print(f"Company ticker {ticker} not found.")
+            return f"Company ticker {ticker} not found."
+    except Exception as e:
+        print(f"Error: getting option expiration dates for {ticker}: {e}")
+        return f"Error: getting option expiration dates for {ticker}: {e}"
+    return json.dumps(company.options)
+
+
+@yfinance_server.tool(
+    name="get_option_chain",
+    description="""Fetch the option chain for a given ticker symbol, expiration date, and option type.
+
+Args:
+    ticker: str
+        The ticker symbol of the stock to get option chain for, e.g. "AAPL"
+    expiration_date: str
+        The expiration date for the options chain (format: 'YYYY-MM-DD')
+    option_type: str
+        The type of option to fetch ('calls' or 'puts')
+""",
+)
+async def get_option_chain(
+    ticker: str,
+    expiration_date: str,
+    option_type: str,
+    page: int = 1,
+    export_path: Optional[str] = None,
+) -> str:
+    """Fetch option chain with pagination"""
+    cache = get_cache()
+    cache_key = f"options_{ticker}_{expiration_date}_{option_type}"
+    
+    def fetch_options():
+        company = yf.Ticker(ticker)
+        if expiration_date not in company.options:
+            raise ValueError(f"No options for date {expiration_date}")
+        if option_type not in ["calls", "puts"]:
+            raise ValueError("Invalid option type")
+        
+        option_chain = company.option_chain(expiration_date)
+        return option_chain.calls if option_type == "calls" else option_chain.puts
+    
+    try:
+        option_data, cache_age = cache.get_or_set(
+            cache_key,
+            fetch_options,
+            ttl_seconds=300  # 5 minutes - volatile
+        )
+    except ValueError as e:
+        return f"Error: {str(e)}"
+    
+    if option_data is None or option_data.empty:
+        return f"No option chain data available for {ticker}"
+    
+    if export_path:
+        return export_to_json(option_data, export_path)
+    
+    result = paginate_by_tokens(
+        data=option_data,
+        page=page,
+        max_tokens=6000,
+        data_type="table",
+        title=f"OPTION CHAIN - {ticker} ({option_type.upper()}, {expiration_date})",
+        cache_age=cache_age,
+    )
+    
+    return result.formatted_text
+
+
+@yfinance_server.tool(
+    name="get_recommendations",
+    description="""Get recommendations or upgrades/downgrades for a given ticker symbol from yahoo finance. You can also specify the number of months back to get upgrades/downgrades for, default is 12.
+
+Args:
+    ticker: str
+        The ticker symbol of the stock to get recommendations for, e.g. "AAPL"
+    recommendation_type: str
+        The type of recommendation to get. You can choose from the following recommendation types: recommendations, upgrades_downgrades.
+    months_back: int
+        The number of months back to get upgrades/downgrades for, default is 12.
+""",
+)
+async def get_recommendations(
+    ticker: str,
+    recommendation_type: str,
+    months_back: int = 12,
+    page: int = 1,
+    export_path: Optional[str] = None,
+) -> str:
+    """Get recommendations with pagination"""
+    cache = get_cache()
+    cache_key = f"recommendations_{ticker}_{recommendation_type}_{months_back}"
+    
+    def fetch_recommendations():
+        company = yf.Ticker(ticker)
+        if recommendation_type == RecommendationType.recommendations:
+            return company.recommendations
+        elif recommendation_type == RecommendationType.upgrades_downgrades:
+            upgrades_downgrades = company.upgrades_downgrades.reset_index()
+            cutoff_date = pd.Timestamp.now() - pd.DateOffset(months=months_back)
+            upgrades_downgrades = upgrades_downgrades[
+                upgrades_downgrades["GradeDate"] >= cutoff_date
+            ]
+            upgrades_downgrades = upgrades_downgrades.sort_values("GradeDate", ascending=False)
+            return upgrades_downgrades.drop_duplicates(subset=["Firm"])
+        else:
+            return None
+    
+    try:
+        rec_data, cache_age = cache.get_or_set(
+            cache_key,
+            fetch_recommendations,
+            ttl_seconds=3600  # 1 hour
+        )
+    except Exception as e:
+        return f"Error: getting recommendations for {ticker}: {e}"
+    
+    if rec_data is None or rec_data.empty:
+        return f"No recommendations available for {ticker}"
+    
+    if export_path:
+        return export_to_json(rec_data, export_path)
+    
+    result = paginate_by_tokens(
+        data=rec_data,
+        page=page,
+        max_tokens=6000,
+        data_type="table",
+        title=f"RECOMMENDATIONS - {ticker} ({recommendation_type})",
+        cache_age=cache_age,
+    )
+    
+    return result.formatted_text
+
+
+def main() -> None:
+    """Main entry point for the server"""
+    print("Starting Yahoo Finance MCP server...")
+    yfinance_server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

{yfin_mcp-0.2.4.dist-info → yfin_mcp-0.2.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yfin-mcp
-Version: 0.2.4
+Version: 0.2.5
 Summary: Enhanced Yahoo Finance MCP Server with intelligent pagination, caching, and LLM-optimized responses
 Author: AlexYoung (Original Author)
 Author-email: fritzprix <innocentevil0914@gmail.com>
@@ -280,7 +280,7 @@ For testing with MCP Inspector:
 
 ```bash
 # From source
-uv run server.py
+uv run yfin-mcp
 
 # Or if installed via pip
 python -m yfin_mcp
@@ -315,7 +315,7 @@ chmod +x publish_package.sh
 ```
 
 > [!NOTE]
-> The scripts will build the package into the `dist/` directory and then use `uv publish` to upload it. Ensure you have your PyPI credentials configured in `~/.pypirc` (or `%HOME%\.pypirc` on Windows) or set the `UV_PUBLISH_TOKEN` environment variable.
+> The scripts will build the package into the `dist/` directory and then use `twine` to upload it. Ensure you have your PyPI credentials configured in `~/.pypirc` (or `%HOME%\.pypirc` on Windows) or set the `TWINE_PASSWORD` environment variable.
 
 ## License
 

yfin_mcp-0.2.5.dist-info/RECORD

@@ -0,0 +1,11 @@
+yfin_mcp/__init__.py,sha256=o50r3pMClywOYSZNh-saX7Gop-XcJR9ZYoutb49sy18,20
+yfin_mcp/__main__.py,sha256=tsUTknY-RMVcmeThCU7_f58cuicrPOSGRGmGD7zLjCU,68
+yfin_mcp/cache_manager.py,sha256=QXqYpZ6q1rYqpsJspyCgXr7CD3g_d6Tlde-f4_32Td0,4439
+yfin_mcp/pagination_utils.py,sha256=Q1IRJsY76n6ohfTZhQcfZTKAefRuSaDE6UNM9coQ8-M,8737
+yfin_mcp/server.py,sha256=Jwg8L78WCWFkMTY-D02O5R9zBtClB-YC1Q-fAHq9Fj0,20460
+yfin_mcp-0.2.5.dist-info/licenses/LICENSE,sha256=-X17dvA84FUO-t9DRgqDt7JO2d0tSz6UpuZ-ZMtFfyo,1189
+yfin_mcp-0.2.5.dist-info/METADATA,sha256=5WdcLw2-YCcDQpfjQU-dy4JAiPzIgMwYWztLb8O5_QQ,10770
+yfin_mcp-0.2.5.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+yfin_mcp-0.2.5.dist-info/entry_points.txt,sha256=UHi0TxeiN87R8aY4YIVFjEZBwS12NFOdtJRAlpgJvnU,50
+yfin_mcp-0.2.5.dist-info/top_level.txt,sha256=--tJwK65rhM2E1QIObaxg4gTRFb_r1lKInXDSUXPlbE,9
+yfin_mcp-0.2.5.dist-info/RECORD,,

yfin_mcp-0.2.5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+yfin-mcp = yfin_mcp.server:main

yfin_mcp-0.2.5.dist-info/top_level.txt

@@ -0,0 +1 @@
+yfin_mcp

yfin_mcp-0.2.4.dist-info/RECORD

@@ -1,6 +0,0 @@
-yfin_mcp-0.2.4.dist-info/licenses/LICENSE,sha256=-X17dvA84FUO-t9DRgqDt7JO2d0tSz6UpuZ-ZMtFfyo,1189
-yfin_mcp-0.2.4.dist-info/METADATA,sha256=Y_1DaBQxoCpacFq7fFk1oszgDPzPaZBzxsKgQjm_54I,10778
-yfin_mcp-0.2.4.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-yfin_mcp-0.2.4.dist-info/entry_points.txt,sha256=kpA80BnCqljODfRYZKgWGPco5SvNVQ1zJgQgpm5zz7k,41
-yfin_mcp-0.2.4.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-yfin_mcp-0.2.4.dist-info/RECORD,,

yfin_mcp-0.2.4.dist-info/entry_points.txt

@@ -1,2 +0,0 @@
-[console_scripts]
-yfin-mcp = server:main

yfin_mcp-0.2.4.dist-info/top_level.txt

@@ -1 +0,0 @@
-