tradingview-mcp 26.0.0__py3-none-any.whl → 26.2.0__py3-none-any.whl

tradingview_mcp/docs_data.py

@@ -1,47 +1,52 @@
-"""Load packaged docs and reference datasets for MCP resources.
-
-This module provides access to:
-- Market metadata (markets.json)
-- Column/field display names (column_display_names.json)  
-- Screener presets (screeners/*.json)
-- Market metainfo with field definitions (metainfo/*.json)
-- AI-friendly quick reference (extracted/ai_quick_reference.json)
-- Screener code examples (extracted/screener_code_examples.json)
-- Field definitions by market (extracted/fields_by_market.json)
-
-Data is loaded from packaged files first, with fallback to the reference path.
-Set TRADINGVIEW_SCREENER_DOCS_DATA env var to override the reference path.
-"""
+"""Load packaged docs datasets for MCP resources - AI-friendly fast lookup."""
 
 from __future__ import annotations
 
 import json
-import os
 from functools import lru_cache
 from importlib.resources import files
-from pathlib import Path
 from typing import Any
 
 
-DEFAULT_REFERENCE_ROOT = Path(
-    os.getenv(
-        "TRADINGVIEW_SCREENER_DOCS_DATA",
-        "/home/henrik/tradingview-mcp/referance/TradingView-Screener-docs/data",
-    )
-)
-
-# Token/size limits for AI-friendly responses
-MAX_ITEMS_DEFAULT = 100
-MAX_ITEMS_LARGE = 500
-MAX_CHARS_DEFAULT = 50000  # ~12.5k tokens
-MAX_CHARS_LARGE = 200000  # ~50k tokens
-
-# Large data warnings
-LARGE_DATA_WARNING = (
-    "⚠️ This data is large ({size} items). "
-    "Use `limit` parameter to reduce output. "
-    "Set `confirm_large=True` to retrieve full data."
-)
+# Token/size limits
+MAX_ITEMS_DEFAULT = 50
+MAX_ITEMS_LARGE = 200
+
+# Valid markets for quick reference
+STOCK_MARKETS = [
+    "america", "argentina", "australia", "austria", "bahrain", "bangladesh",
+    "belgium", "brazil", "canada", "chile", "china", "colombia", "cyprus",
+    "czech", "denmark", "egypt", "estonia", "finland", "france", "germany",
+    "greece", "hongkong", "hungary", "iceland", "india", "indonesia", "ireland",
+    "israel", "italy", "japan", "kenya", "korea", "ksa", "kuwait", "latvia",
+    "lithuania", "luxembourg", "malaysia", "mexico", "morocco", "netherlands",
+    "newzealand", "nigeria", "norway", "pakistan", "peru", "philippines",
+    "poland", "portugal", "qatar", "romania", "rsa", "russia", "serbia",
+    "singapore", "slovakia", "spain", "srilanka", "sweden", "switzerland",
+    "taiwan", "thailand", "tunisia", "turkey", "uae", "uk", "venezuela", "vietnam",
+]
+OTHER_MARKETS = ["bond", "bonds", "cfd", "coin", "crypto", "economics2", "forex", "futures", "options"]
+ALL_MARKETS = STOCK_MARKETS + OTHER_MARKETS
+
+# Common field categories for quick lookup
+FIELD_CATEGORIES = {
+    "price": ["close", "open", "high", "low", "change", "change_abs", "gap"],
+    "volume": ["volume", "Value.Traded", "relative_volume_10d_calc", "average_volume_10d_calc"],
+    "market_cap": ["market_cap_basic", "market_cap_calc"],
+    "fundamental": ["price_earnings_ttm", "earnings_per_share_basic_ttm", "dividends_yield_current"],
+    "technical": ["RSI", "MACD.macd", "BB.upper", "BB.lower", "SMA50", "SMA200", "EMA50", "Recommend.All"],
+    "performance": ["Perf.W", "Perf.1M", "Perf.3M", "Perf.6M", "Perf.Y", "Perf.YTD"],
+    "metadata": ["name", "description", "sector", "exchange", "type", "currency"],
+}
+
+# Filter operations reference
+FILTER_OPS = {
+    "comparison": ["greater", "less", "equal", "not_equal", "greater_or_equal", "less_or_equal"],
+    "range": ["in_range", "not_in_range"],
+    "list": ["in_list", "not_in_list"],
+    "text": ["match", "not_match", "has", "has_none_of"],
+    "null": ["empty", "not_empty"],
+}
 
 
 def _data_path(*parts: str):
@@ -49,22 +54,12 @@ def _data_path(*parts: str):
     return files("tradingview_mcp.data").joinpath(*parts)
 
 
-def _reference_path(*parts: str) -> Path:
-    """Get path to reference data file."""
-    return DEFAULT_REFERENCE_ROOT.joinpath(*parts)
-
-
 @lru_cache(maxsize=128)
 def load_json(*parts: str) -> Any:
-    """Load JSON file from package data or reference fallback."""
-    try:
-        path = _data_path(*parts)
-        with path.open("r", encoding="utf-8") as handle:
-            return json.load(handle)
-    except (FileNotFoundError, TypeError):
-        fallback = _reference_path(*parts)
-        with fallback.open("r", encoding="utf-8") as handle:
-            return json.load(handle)
+    """Load JSON file from packaged data."""
+    path = _data_path(*parts)
+    with path.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
 
 
 def get_markets_data() -> dict[str, list[str]]:
@@ -98,6 +93,50 @@ def get_screeners_data(name: str) -> Any:
     return load_json("screeners", name)
 
 
+def get_stock_screeners() -> list[dict[str, Any]]:
+    """Get stock screeners metadata."""
+    return load_json("screeners", "stocks.json")
+
+
+def get_stock_screeners_failed() -> list[dict[str, Any]]:
+    """Get failed stock screeners metadata."""
+    return load_json("screeners", "stocks_failed.json")
+
+
+def get_stock_screener_presets(market: str | None = None) -> dict[str, Any]:
+    """Get stock screener presets by market."""
+    data = load_json("extracted", "stock_screener_presets.json")
+    if market:
+        return data.get(market, {})
+    return data
+
+
+def get_valid_fields_for_market(market: str) -> list[str]:
+    """Get list of valid field names for a market."""
+    fields_data = get_fields_by_market(market)
+    if isinstance(fields_data, list):
+        return [f.get("name", "") for f in fields_data if f.get("name")]
+    return []
+
+
+def suggest_fields_for_error(error_message: str, market: str = "stocks") -> dict[str, Any]:
+    """Suggest valid fields when an error occurs."""
+    valid_fields = get_valid_fields_for_market(market)
+    common = get_common_fields()
+    
+    # Extract commonly used fields
+    common_names = list(common.keys())[:50]
+    
+    return {
+        "error": error_message,
+        "market": market,
+        "suggestion": "Use fields from the valid_fields list",
+        "common_fields": common_names,
+        "total_valid_fields": len(valid_fields),
+        "hint": "Call list_fields_for_market(market) for full field list"
+    }
+
+
 # ============================================================================
 # AI-Friendly Data Access with Output Limits
 # ============================================================================
@@ -132,39 +171,27 @@ def paginate_data(
     limit: int = MAX_ITEMS_DEFAULT,
     confirm_large: bool = False,
 ) -> dict[str, Any]:
-    """Paginate large data with size warnings.
-    
-    Args:
-        data: List or dict to paginate
-        offset: Starting index (for lists) or skip count (for dicts)
-        limit: Maximum items to return
-        confirm_large: If True, allow large outputs without warning
-        
-    Returns:
-        Dict with 'data', 'total', 'offset', 'limit', and optional 'warning'
-    """
+    """Paginate data with offset and limit."""
     if isinstance(data, list):
         total = len(data)
-        items = data[offset:offset + limit]
+        items = data if confirm_large else data[offset:offset + limit]
     else:
         keys = list(data.keys())
         total = len(keys)
-        selected_keys = keys[offset:offset + limit]
-        items = {k: data[k] for k in selected_keys}
+        if confirm_large:
+            items = data
+        else:
+            selected_keys = keys[offset:offset + limit]
+            items = {k: data[k] for k in selected_keys}
     
     result: dict[str, Any] = {
         "data": items,
         "total": total,
         "offset": offset,
-        "limit": limit,
-        "has_more": (offset + limit) < total,
+        "limit": total if confirm_large else limit,
+        "has_more": False if confirm_large else (offset + limit) < total,
+        "next_offset": None if confirm_large else ((offset + limit) if (offset + limit) < total else None),
     }
-    
-    # Add warning for large data if not confirmed
-    if total > MAX_ITEMS_DEFAULT and not confirm_large and limit >= total:
-        result["warning"] = LARGE_DATA_WARNING.format(size=total)
-        result["hint"] = f"Use limit={MAX_ITEMS_DEFAULT} or set confirm_large=True"
-    
     return result
 
 
@@ -173,16 +200,7 @@ def search_fields(
     market: str | None = None,
     limit: int = 20,
 ) -> list[dict[str, Any]]:
-    """Search fields by name or display name.
-    
-    Args:
-        query: Search term (case-insensitive)
-        market: Optional market to search in (stocks, crypto, forex, etc.)
-        limit: Maximum results to return
-        
-    Returns:
-        List of matching field definitions
-    """
+    """Search fields by name or display name."""
     query_lower = query.lower()
     
     if market:
@@ -212,14 +230,7 @@ def search_fields(
 
 
 def get_field_summary(field_name: str) -> dict[str, Any] | None:
-    """Get summary info for a specific field.
-    
-    Args:
-        field_name: Field name to look up
-        
-    Returns:
-        Field info dict or None if not found
-    """
+    """Get summary info for a field."""
     # Check common fields first
     common = get_common_fields()
     if field_name in common:
@@ -252,15 +263,7 @@ def truncate_for_tokens(
     data: Any,
     max_tokens: int = 10000,
 ) -> tuple[Any, bool]:
-    """Truncate data to fit within token limit.
-    
-    Args:
-        data: Data to potentially truncate
-        max_tokens: Maximum tokens allowed
-        
-    Returns:
-        Tuple of (truncated_data, was_truncated)
-    """
+    """Truncate data to fit within a token limit."""
     estimated = estimate_tokens(data)
     if estimated <= max_tokens:
         return data, False
@@ -295,3 +298,214 @@ def truncate_for_tokens(
     if len(json_str) > max_chars:
         return json_str[:max_chars] + "... (truncated)", True
     return data, False
+
+
+# ============================================================================
+# Fast Lookup Functions - Returns compact data, not full dumps
+# ============================================================================
+
+
+def get_quick_reference() -> dict[str, Any]:
+    """Get compact quick reference - markets, field categories, filter ops."""
+    return {
+        "stock_markets": STOCK_MARKETS,
+        "other_markets": OTHER_MARKETS,
+        "field_categories": FIELD_CATEGORIES,
+        "filter_operations": FILTER_OPS,
+        "usage": {
+            "lookup_field": "lookup_field('RSI') - get field info",
+            "search_fields": "search_fields('volume') - search by keyword",
+            "get_filter_format": "get_filter_format('price') - get filter example",
+        },
+    }
+
+
+def lookup_field(field_name: str) -> dict[str, Any]:
+    """Lookup a single field by exact name."""
+    # Check common fields
+    common = get_common_fields()
+    if field_name in common:
+        info = common[field_name]
+        return {
+            "found": True,
+            "name": field_name,
+            "display_name": info.get("display_name"),
+            "type": info.get("type"),
+            "variants": info.get("variants"),
+        }
+    
+    # Check display names
+    display_names = get_column_display_names()
+    if field_name in display_names:
+        return {
+            "found": True,
+            "name": field_name,
+            "display_name": display_names[field_name],
+        }
+    
+    # Not found - suggest similar
+    query_lower = field_name.lower()
+    suggestions = [
+        name for name in list(common.keys())[:200]
+        if query_lower in name.lower()
+    ][:5]
+    
+    return {
+        "found": False,
+        "name": field_name,
+        "suggestions": suggestions,
+        "hint": f"Field '{field_name}' not found. Try one of: {suggestions}" if suggestions else f"Field '{field_name}' not found. Use search_fields() to find available fields.",
+    }
+
+
+def get_filter_format(field_type: str = "number") -> dict[str, Any]:
+    """Get correct filter format for a field type."""
+    formats = {
+        "number": {
+            "example": {"column": "RSI", "operation": "lt", "value": 30},
+            "operations": ["gt", "gte", "lt", "lte", "eq", "neq", "between"],
+            "between_example": {"column": "RSI", "operation": "between", "value": [20, 80]},
+        },
+        "price": {
+            "example": {"column": "close", "operation": "gt", "value": 100},
+            "operations": ["gt", "gte", "lt", "lte", "eq", "between"],
+        },
+        "percent": {
+            "example": {"column": "change", "operation": "gt", "value": 5},
+            "operations": ["gt", "gte", "lt", "lte", "between"],
+            "note": "Values are percentages, e.g., 5 = 5%",
+        },
+        "text": {
+            "example": {"column": "sector", "operation": "eq", "value": "Technology"},
+            "operations": ["eq", "neq", "isin"],
+            "isin_example": {"column": "exchange", "operation": "isin", "value": ["NASDAQ", "NYSE"]},
+        },
+        "bool": {
+            "example": {"column": "is_primary", "operation": "eq", "value": True},
+            "operations": ["eq"],
+        },
+    }
+    
+    if field_type in formats:
+        return {"type": field_type, **formats[field_type]}
+    
+    return {
+        "error": f"Unknown type '{field_type}'",
+        "available_types": list(formats.keys()),
+        "default": formats["number"],
+    }
+
+
+def get_market_fields_summary(market: str) -> dict[str, Any]:
+    """Get summary of available fields for a market (not full list)."""
+    if market not in ALL_MARKETS:
+        return {
+            "error": f"Invalid market '{market}'",
+            "valid_markets": ALL_MARKETS,
+        }
+    
+    # Try metainfo first
+    try:
+        metainfo = get_metainfo(market if market not in STOCK_MARKETS else "stocks")
+        if isinstance(metainfo, list):
+            field_count = len(metainfo)
+            # Get field types distribution
+            types = {}
+            for f in metainfo[:500]:
+                t = f.get("t", "unknown")
+                types[t] = types.get(t, 0) + 1
+            
+            return {
+                "market": market,
+                "total_fields": field_count,
+                "field_types": types,
+                "sample_fields": [f.get("n") for f in metainfo[:20]],
+                "hint": "Use search_fields(query, market) to find specific fields",
+            }
+    except FileNotFoundError:
+        pass
+    
+    # Fallback to fields_by_market
+    fields = get_fields_by_market(market)
+    if isinstance(fields, list):
+        return {
+            "market": market,
+            "total_fields": len(fields),
+            "sample_fields": [f.get("name") for f in fields[:20]],
+        }
+    
+    return {"market": market, "note": "Use get_common_fields() for this market"}
+
+
+def get_screener_preset_names() -> list[str]:
+    """Get list of available screener preset names only."""
+    presets = get_screener_presets()
+    return [p.get("name", "") for p in presets if p.get("name")]
+
+
+def get_code_example_names() -> list[str]:
+    """Get list of available code example names."""
+    examples = get_screener_code_examples()
+    return list(examples.keys())
+
+
+def validate_market(market: str) -> dict[str, Any]:
+    """Validate market name and return correct format if invalid."""
+    if market in ALL_MARKETS:
+        return {"valid": True, "market": market}
+    
+    # Try case-insensitive match
+    market_lower = market.lower()
+    for m in ALL_MARKETS:
+        if m.lower() == market_lower:
+            return {"valid": True, "market": m, "normalized": True}
+    
+    # Suggest similar
+    suggestions = [m for m in ALL_MARKETS if market_lower in m.lower()][:5]
+    
+    return {
+        "valid": False,
+        "input": market,
+        "suggestions": suggestions if suggestions else ALL_MARKETS[:10],
+        "hint": f"Invalid market '{market}'. Use one of the valid markets.",
+    }
+
+
+def build_error_with_format(
+    error_type: str,
+    context: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build helpful error response with correct format examples."""
+    error_formats = {
+        "invalid_market": {
+            "error": "Invalid market",
+            "valid_markets": ALL_MARKETS,
+            "example": "market='america'",
+        },
+        "invalid_field": {
+            "error": "Invalid field",
+            "common_fields": list(FIELD_CATEGORIES.get("price", [])) + list(FIELD_CATEGORIES.get("volume", [])),
+            "example": "columns=['close', 'volume', 'change']",
+            "hint": "Use search_fields(query) to find fields",
+        },
+        "invalid_filter": {
+            "error": "Invalid filter format",
+            "correct_format": {"column": "field_name", "operation": "op", "value": "value"},
+            "operations": ["gt", "gte", "lt", "lte", "eq", "neq", "between", "isin"],
+            "examples": [
+                {"column": "change", "operation": "gt", "value": 5},
+                {"column": "volume", "operation": "gt", "value": 1000000},
+                {"column": "RSI", "operation": "between", "value": [20, 30]},
+            ],
+        },
+        "invalid_sort": {
+            "error": "Invalid sort field",
+            "common_sort_fields": ["volume", "change", "market_cap_basic", "close", "RSI"],
+            "example": "sort_by='volume', ascending=False",
+        },
+    }
+    
+    result = error_formats.get(error_type, {"error": error_type})
+    if context:
+        result["context"] = context
+    return result