tradingview-mcp 1.0.0__py3-none-any.whl → 1.0__py3-none-any.whl

tradingview_mcp/docs_data.py

@@ -0,0 +1,297 @@
+"""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.
+"""
+
+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."
+)
+
+
+def _data_path(*parts: str):
+    """Get path to packaged data file."""
+    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)
+
+
+def get_markets_data() -> dict[str, list[str]]:
+    """Get markets metadata."""
+    return load_json("markets.json")
+
+
+def get_column_display_names() -> dict[str, str]:
+    """Get field name to display name mapping."""
+    data = load_json("column_display_names.json")
+    return data.get("fields", data)
+
+
+def get_screener_presets() -> list[dict[str, Any]]:
+    """Get predefined screener presets."""
+    return load_json("screeners", "main_screeners.json")
+
+
+def get_screener_markets() -> list[str]:
+    """Get list of screener market identifiers."""
+    return load_json("screeners", "markets.json")
+
+
+def get_metainfo(market: str) -> dict[str, Any]:
+    """Get field metainfo for a specific market."""
+    return load_json("metainfo", f"{market}.json")
+
+
+def get_screeners_data(name: str) -> Any:
+    """Get screeners data by filename."""
+    return load_json("screeners", name)
+
+
+# ============================================================================
+# AI-Friendly Data Access with Output Limits
+# ============================================================================
+
+
+def get_ai_quick_reference() -> dict[str, Any]:
+    """Get AI quick reference guide with common patterns and examples."""
+    return load_json("extracted", "ai_quick_reference.json")
+
+
+def get_screener_code_examples() -> dict[str, str]:
+    """Get screener code examples by name."""
+    return load_json("extracted", "screener_code_examples.json")
+
+
+def get_common_fields() -> dict[str, dict[str, Any]]:
+    """Get common field definitions (from stocks, most comprehensive)."""
+    return load_json("extracted", "common_fields.json")
+
+
+def get_fields_by_market(market: str | None = None) -> dict[str, Any]:
+    """Get field definitions by market type."""
+    data = load_json("extracted", "fields_by_market.json")
+    if market:
+        return data.get(market, {})
+    return data
+
+
+def paginate_data(
+    data: list | dict,
+    offset: int = 0,
+    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'
+    """
+    if isinstance(data, list):
+        total = len(data)
+        items = 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}
+    
+    result: dict[str, Any] = {
+        "data": items,
+        "total": total,
+        "offset": offset,
+        "limit": limit,
+        "has_more": (offset + limit) < total,
+    }
+    
+    # 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
+
+
+def search_fields(
+    query: str,
+    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
+    """
+    query_lower = query.lower()
+    
+    if market:
+        fields_data = get_fields_by_market(market)
+        if isinstance(fields_data, list):
+            fields = fields_data
+        else:
+            return []
+    else:
+        fields = list(get_common_fields().items())
+        fields = [
+            {"name": k, **v} if isinstance(v, dict) else {"name": k, "display_name": str(v)}
+            for k, v in fields[:500]  # Limit iteration
+        ]
+    
+    matches = []
+    for field in fields:
+        if isinstance(field, dict):
+            name = field.get("name", "")
+            display = field.get("display_name", "")
+            if query_lower in name.lower() or query_lower in display.lower():
+                matches.append(field)
+                if len(matches) >= limit:
+                    break
+    
+    return matches
+
+
+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
+    """
+    # Check common fields first
+    common = get_common_fields()
+    if field_name in common:
+        info = common[field_name]
+        return {
+            "name": field_name,
+            "display_name": info.get("display_name"),
+            "type": info.get("type"),
+            "variants": info.get("variants"),
+        }
+    
+    # Check display names mapping
+    display_names = get_column_display_names()
+    if field_name in display_names:
+        return {
+            "name": field_name,
+            "display_name": display_names[field_name],
+        }
+    
+    return None
+
+
+def estimate_tokens(data: Any) -> int:
+    """Estimate token count for data (rough: 4 chars = 1 token)."""
+    json_str = json.dumps(data, ensure_ascii=False, default=str)
+    return len(json_str) // 4
+
+
+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)
+    """
+    estimated = estimate_tokens(data)
+    if estimated <= max_tokens:
+        return data, False
+    
+    # Try to truncate intelligently
+    if isinstance(data, list):
+        # Binary search for right size
+        low, high = 0, len(data)
+        while low < high:
+            mid = (low + high + 1) // 2
+            if estimate_tokens(data[:mid]) <= max_tokens:
+                low = mid
+            else:
+                high = mid - 1
+        return data[:low], True
+    
+    elif isinstance(data, dict):
+        keys = list(data.keys())
+        low, high = 0, len(keys)
+        while low < high:
+            mid = (low + high + 1) // 2
+            subset = {k: data[k] for k in keys[:mid]}
+            if estimate_tokens(subset) <= max_tokens:
+                low = mid
+            else:
+                high = mid - 1
+        return {k: data[k] for k in keys[:low]}, True
+    
+    # Fallback: stringify and truncate
+    json_str = json.dumps(data, ensure_ascii=False, default=str)
+    max_chars = max_tokens * 4
+    if len(json_str) > max_chars:
+        return json_str[:max_chars] + "... (truncated)", True
+    return data, False

tradingview_mcp/scanner.py

@@ -10,7 +10,8 @@ from tradingview_mcp.column import Column
 from tradingview_mcp.query import Query
 
 
-DEFAULT_COLUMNS = ["name", "close", "volume", "market_cap_basic"]
+# Always include 'description' for full name (e.g., "Apple Inc." instead of just "AAPL")
+DEFAULT_COLUMNS = ["name", "description", "close", "change", "volume", "market_cap_basic"]
 
 
 class Scanner: