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

tradingview_mcp/tools/reference.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+from typing import Any, Optional
+
+from tradingview_mcp.docs_data import (
+    get_ai_quick_reference,
+    search_fields,
+    get_screener_code_examples,
+    get_valid_fields_for_market,
+    get_common_fields,
+    lookup_field,
+    get_field_summary,
+    get_filter_format,
+    validate_market,
+    get_quick_reference,
+    get_screener_presets,
+    get_metainfo
+)
+
+def ai_get_reference() -> dict[str, Any]:
+    """Get AI quick reference for using this MCP."""
+    return get_ai_quick_reference()
+
+def search_available_fields(query: str, market: str = None) -> list[dict[str, Any]]:
+    """Search for available fields/columns."""
+    return search_fields(query, market)
+
+def get_code_example(name: str) -> str:
+    """Get code example by name."""
+    examples = get_screener_code_examples()
+    return examples.get(name, "Example not found.")
+
+def list_fields_for_market(market: str) -> list[str]:
+    """List valid fields for a specific market."""
+    return get_valid_fields_for_market(market)
+
+def get_common_fields_summary() -> dict[str, Any]:
+    """Get summary of common fields."""
+    return get_common_fields()
+
+def lookup_single_field(name: str) -> dict[str, Any]:
+    """Lookup details for a single field."""
+    return lookup_field(name)
+
+def get_field_info(name: str) -> dict[str, Any]:
+    """Get info for a field."""
+    return get_field_summary(name) or {"error": "Field not found"}
+
+def get_filter_example(type: str = "number") -> dict[str, Any]:
+    """Get example filter format."""
+    return get_filter_format(type)
+
+def check_market(market: str) -> dict[str, Any]:
+    """Validate a market name."""
+    return validate_market(market)
+
+def get_help() -> dict[str, Any]:
+    """Get help and usage info."""
+    return get_quick_reference()
+
+def get_screener_preset(name: str) -> dict[str, Any]:
+    """Get a screener preset."""
+    presets = get_screener_presets()
+    for p in presets:
+        if p.get("name") == name:
+            return p
+    return {"error": "Preset not found"}
+
+def get_market_metainfo(market: str) -> dict[str, Any]:
+    """Get metainfo for a market."""
+    return get_metainfo(market)

tradingview_mcp/tools/screener.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+from typing import Any, Optional
+
+from tradingview_mcp.column import Column
+from tradingview_mcp.constants import DEFAULT_COLUMNS, get_column_name
+from tradingview_mcp.query import Query
+from tradingview_mcp.utils import sanitize_market
+
+def screen_market(
+    market: str = "america",
+    columns: Optional[list[str]] = None,
+    sort_by: str = "volume",
+    ascending: bool = False,
+    limit: int = 25,
+    filters: Optional[list[dict[str, Any]]] = None,
+) -> dict[str, Any]:
+    """Run a custom market screening query."""
+    market = sanitize_market(market)
+    limit = max(1, min(limit, 500))
+    
+    # Ensure description is always included
+    cols = columns or DEFAULT_COLUMNS
+    if "description" not in cols:
+        cols = ["description"] + list(cols)
+
+    query = Query().set_markets(market).select(*cols).order_by(sort_by, ascending=ascending).limit(limit)
+
+    # Apply filters if provided
+    if filters:
+        filter_expressions = []
+        for f in filters:
+            # Automatic translation of human-readable column names
+            col_name = get_column_name(f.get("column", "close"))
+            col = Column(col_name)
+            op = f.get("operation", "gt")
+            val = f.get("value")
+
+            if op == "gt":
+                filter_expressions.append(col > val)
+            elif op == "gte":
+                filter_expressions.append(col >= val)
+            elif op == "lt":
+                filter_expressions.append(col < val)
+            elif op == "lte":
+                filter_expressions.append(col <= val)
+            elif op == "eq":
+                filter_expressions.append(col == val)
+            elif op == "neq":
+                filter_expressions.append(col != val)
+            elif op == "between" and isinstance(val, (list, tuple)) and len(val) == 2:
+                filter_expressions.append(col.between(val[0], val[1]))
+            elif op == "isin" and isinstance(val, (list, tuple)):
+                filter_expressions.append(col.isin(val))
+
+        if filter_expressions:
+            query = query.where(*filter_expressions)
+
+    try:
+        total_count, df = query.get_scanner_data()
+        results = df.to_dict("records")
+
+        return {
+            "total_count": total_count,
+            "returned": len(results),
+            "market": market,
+            "data": results,
+        }
+    except Exception as e:
+        return {"error": str(e), "market": market}
+
+
+def get_top_gainers(market: str = "america", limit: int = 25) -> dict[str, Any]:
+    """Get top gainers for a market."""
+    market = sanitize_market(market)
+    return screen_market(market, sort_by="change", ascending=False, limit=limit)
+
+
+def get_top_losers(market: str = "america", limit: int = 25) -> dict[str, Any]:
+    """Get top losers for a market."""
+    market = sanitize_market(market)
+    return screen_market(market, sort_by="change", ascending=True, limit=limit)
+
+
+def get_most_active(market: str = "america", limit: int = 25) -> dict[str, Any]:
+    """Get most active symbols by volume."""
+    market = sanitize_market(market)
+    return screen_market(market, sort_by="volume", ascending=False, limit=limit)

tradingview_mcp/tools/search.py

@@ -0,0 +1,350 @@
+from __future__ import annotations
+from typing import Any
+import concurrent.futures
+
+from mcp.server.fastmcp import Context
+
+from tradingview_mcp.column import Column
+from tradingview_mcp.constants import EXCHANGE_SCREENER
+from tradingview_mcp.docs_data import get_default_columns_for_market, STOCK_MARKETS
+from tradingview_mcp.query import Query
+from tradingview_mcp.utils import sanitize_market
+
+# Common aliases for commodities/forex that don't match TV names
+SYMBOL_ALIASES = {
+    # Precious Metals
+    "XAG": ["SILVER", "XAGUSD"],
+    "XAU": ["GOLD", "XAUUSD"],
+    "XPT": ["PLATINUM", "XPTUSD"],
+    "XPD": ["PALLADIUM", "XPDUSD"],
+    
+    # Energy
+    "OIL": ["USOIL", "UKOIL", "WTI", "BRENT"],
+    "WTI": ["USOIL"],
+    "BRENT": ["UKOIL"],
+    "NATGAS": ["NG1!", "NATURALGAS"],
+    
+    # Others
+    "COPPER": ["HG1!", "XCUUSD"],
+}
+
+def search_symbols(
+    query: str,
+    market: str = "america",
+    limit: int = 25,
+) -> dict[str, Any]:
+    """
+    Search symbols by name or ticker. Returns strict locator format for downstream tools.
+    
+    Output format includes 'locator': 'EXCHANGE:SYMBOL, market_name'.
+    Use this locator to call get_technical_analysis() or other tools precisely.
+    """
+    market = sanitize_market(market)
+    limit = max(1, min(limit, 100))
+    
+    # Use dynamic default columns for this market
+    cols = get_default_columns_for_market(market)
+    
+    # Determine sort column
+    sort_col = "market_cap_basic" if "market_cap_basic" in cols else "name"
+    
+    # Expand query with aliases if available
+    queries = [query]
+    if query.upper() in SYMBOL_ALIASES:
+        queries.extend(SYMBOL_ALIASES[query.upper()])
+
+    try:
+        # Standard search in requested market
+        results = _execute_search(queries, market, limit, cols, sort_col)
+        
+        # Smart Fallback: If default market ('america') yielded no results, try others
+        if not results["results"] and market == "america":
+            
+            # 1. Asian Numeric Heuristic
+            if query.isdigit() and len(query) in [4, 5, 6]:
+                asian_markets = ["taiwan", "hongkong", "japan", "china", "korea"]
+                for asian_market in asian_markets:
+                    asian_cols = get_default_columns_for_market(asian_market)
+                    asian_sort = "volume"
+                    asian_res = _execute_search(queries, asian_market, 5, asian_cols, asian_sort)
+                    if asian_res["results"]:
+                         return {**asian_res, "note": f"No results in 'america', using numeric heuristic for '{asian_market}'."}
+
+            # 2. True Global Search
+            try:
+                global_cols = ["name", "description", "close", "change", "volume", "market_cap_basic", "exchange", "type"]
+                q = (
+                    Query()
+                    .set_markets(*STOCK_MARKETS)
+                    .select(*global_cols)
+                    .where(Column("description").like(query))
+                    .order_by("volume", ascending=False)
+                    .limit(5)
+                )
+                _, df = q.get_scanner_data()
+                
+                if df.empty:
+                     q = (
+                        Query()
+                        .set_markets(*STOCK_MARKETS)
+                        .select(*global_cols)
+                        .where(Column("name").like(query))
+                        .order_by("volume", ascending=False)
+                        .limit(5)
+                     )
+                     _, df = q.get_scanner_data()
+                
+                if not df.empty:
+                     # Add locators for global results
+                     records = df.to_dict("records")
+                     for r in records:
+                          _enrich_locator(r, "stock", query) # We can't know exact market easily from batch query, assume global context usage
+                     
+                     return {
+                        "query": query,
+                        "market": "global",
+                        "total_found": len(df),
+                        "returned": len(df),
+                        "results": records,
+                        "note": "Found matches in global stock markets."
+                    }
+            except Exception:
+                pass
+
+            # 3. Check Crypto/Forex/CFD
+            for other in ["crypto", "forex", "cfd"]:
+                 if other == market: continue
+                 
+                 cols = get_default_columns_for_market(other)
+                 sort = "market_cap_basic" if "market_cap_basic" in cols else "name"
+                 if other == "forex" or other == "cfd": sort = "name"
+                 
+                 res = _execute_search(queries, other, 5, cols, sort)
+                 if res["results"]:
+                     return {**res, "note": f"Found matches in '{other}'."}
+
+        return results
+        
+    except Exception as e:
+        return _search_symbols_fallback(query, market, limit, cols, str(e))
+
+
+def _enrich_locator(record: dict, market: str, category: str = "stock"):
+    """Add standard locator string to a record."""
+    ex = record.get("exchange", "UNKNOWN")
+    name = record.get("name", "UNKNOWN")
+    
+    # Try to deduce market if 'stock' is generic
+    # (This is hard without a map of Exchange->Country, but we do our best)
+    
+    # Construct Locator
+    # Format: EXCHANGE:SYMBOL, Market
+    record["locator"] = f"{ex}:{name}, {market}"
+    record["market"] = market
+
+
+def _execute_search(queries: list[str] | str, market: str, limit: int, cols: list[str], sort_col: str) -> dict[str, Any]:
+    """Execute search, supporting multiple query terms (aliases)."""
+    if isinstance(queries, str):
+        queries = [queries]
+        
+    all_results = []
+    
+    # Try each query term until we get enough results
+    for q_term in queries:
+        if len(all_results) >= limit: break
+        
+        try:
+            # 1. Search description
+            q = (
+                Query()
+                .set_markets(market)
+                .select(*cols)
+                .where(Column("description").like(q_term))
+                .order_by(sort_col, ascending=False)
+                .limit(limit)
+            )
+            _, df = q.get_scanner_data()
+            if not df.empty:
+                 all_results.extend(df.to_dict("records"))
+            
+            # 2. Search name
+            if len(all_results) < limit:
+                q2 = (
+                    Query()
+                    .set_markets(market)
+                    .select(*cols)
+                    .where(Column("name").like(q_term))
+                    .order_by(sort_col, ascending=False)
+                    .limit(limit)
+                )
+                _, df2 = q2.get_scanner_data()
+                if not df2.empty:
+                     all_results.extend(df2.to_dict("records"))
+        except:
+            pass
+            
+    # Dedup
+    unique = {r.get("name")+r.get("exchange"): r for r in all_results}
+    results = list(unique.values())[:limit]
+    
+    # Enhance with locator
+    for r in results:
+        _enrich_locator(r, market)
+    
+    return {
+        "query": queries[0], 
+        "market": market,
+        "total_found": len(results),
+        "returned": len(results),
+        "results": results,
+    }
+
+
+def _search_symbols_fallback(query: str, market: str, limit: int, cols: list[str], error: str) -> dict[str, Any]:
+    return {"error": f"Search failed: {str(e)}", "original_error": error}
+
+
+def get_symbol_info(symbol: str, include_technical: bool = False) -> dict[str, Any]:
+    """
+    Get detailed information for a symbol.
+    Returns matches with strict locators: 'EXCHANGE:SYMBOL, Market'.
+    """
+    technical_cols = [
+        "RSI", "RSI7", "MACD.macd", "MACD.signal", "SMA20", "SMA50", "SMA200", 
+        "EMA20", "EMA50", "EMA200", "BB.upper", "BB.lower", "ATR", "ADX", 
+        "Recommend.All", "Recommend.MA", "Recommend.Other"
+    ]
+
+    try:
+        # --- Strict Mode (Exchange Specified) ---
+        if ":" in symbol:
+            exchange, ticker = symbol.split(":", 1)
+            market = EXCHANGE_SCREENER.get(exchange.lower()) or "america"
+            
+            # Allow override via sanitized lookup? No, specific exchange implies specific market logic usually.
+            # But let's be safe.
+            
+            cols = get_default_columns_for_market(market)
+            if include_technical: cols.extend(technical_cols)
+            cols = list(dict.fromkeys(cols))
+
+            q = (
+                Query()
+                .set_markets(market)
+                .select(*cols)
+                .where(Column("name").isin([symbol, ticker, symbol.upper(), ticker.upper()]))
+                .limit(5)
+            )
+            _, df = q.get_scanner_data()
+            results = df.to_dict("records")
+            
+            if results:
+                # Add strict locators
+                for r in results:
+                    _enrich_locator(r, market)
+                    
+                if len(results) == 1:
+                    return {"symbol": symbol, "found": True, "market": market, "data": results[0]}
+                return {"symbol": symbol, "found": True, "market": market, "matches": results}
+            else:
+                return {"symbol": symbol, "found": False, "hint": f"Symbol not found in {market} ({exchange}). Check format."}
+
+        # --- Universal Mode (Implicit Market) ---
+        all_matches = []
+        
+        # Targets
+        targets = [symbol, symbol.upper(), f"{symbol}USDT", f"{symbol}USD"]
+        if symbol.upper() in SYMBOL_ALIASES:
+            targets.extend(SYMBOL_ALIASES[symbol.upper()])
+        
+        # Helper
+        def run_search(market, col_getter):
+             try:
+                cols = col_getter(market)
+                if include_technical: cols.extend(technical_cols)
+                cols = list(dict.fromkeys(cols))
+                
+                # We need to set markets properly
+                q = Query()
+                if market == "global_stocks":
+                    q.set_markets(*STOCK_MARKETS)
+                else:
+                    q.set_markets(market)
+                
+                q.select(*cols).where(Column("name").isin(targets))
+                
+                if market == "global_stocks":
+                    q.order_by("market_cap_basic", ascending=False).limit(10)
+                else:
+                    q.limit(5)
+                    
+                _, df = q.get_scanner_data()
+                if not df.empty:
+                    matches = df.to_dict("records")
+                    cat = "stock" if market == "global_stocks" else market
+                    
+                    # Fixup locator logic 
+                    for m in matches: 
+                        m["_category"] = cat
+                        # If global stock, we don't know exact country easily without map.
+                        # But for now we pass 'global_stocks' or try to guess?
+                        # It's better to tell AI "taiwan" if possible.
+                        # But we queried ALL markets. 
+                        # HACK: We should query 'taiwan' explicitly if heuristics match?
+                        # No, just return EXCHANGE:SYMBOL and let AI use 'search_symbols' if it needs precise market.
+                        # Actually user wants "TWSE:0050, taiwan".
+                        # If we used set_markets(*ALL), we lose the origin market info in the response unless we select 'market' column?
+                        # TradingView API doesn't usually return 'market' column. It returns 'exchange'.
+                        # We can map Exchange -> Market via EXCHANGE_SCREENER?
+                        rec_market = EXCHANGE_SCREENER.get(m.get("exchange", "").lower(), cat)
+                        _enrich_locator(m, rec_market)
+                        
+                    return matches
+             except:
+                 pass
+             return []
+
+        # Execute in parallel
+        with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
+            futures = [
+                executor.submit(run_search, "global_stocks", lambda m: ["name", "description", "close", "change", "volume", "market_cap_basic", "exchange", "type"]),
+                executor.submit(run_search, "crypto", get_default_columns_for_market),
+                executor.submit(run_search, "forex", get_default_columns_for_market),
+                executor.submit(run_search, "cfd", get_default_columns_for_market)
+            ]
+            for future in concurrent.futures.as_completed(futures):
+                all_matches.extend(future.result())
+
+        # --- Aggregate Results ---
+        if not all_matches:
+             return search_symbols(symbol, "america", 5)
+
+        # Remove duplicates
+        unique_matches = {}
+        for m in all_matches:
+            key = m.get("ticker", m.get("name"))
+            if key not in unique_matches:
+                unique_matches[key] = m
+        
+        final_matches = list(unique_matches.values())
+
+        if len(final_matches) == 1:
+            first = final_matches[0]
+            cat = first.pop("_category", "global")
+            return {"symbol": symbol, "found": True, "market": cat, "data": first}
+        
+        return {
+            "symbol": symbol,
+            "found": True, 
+            "market": "global", 
+            "count": len(final_matches),
+            "matches": final_matches,
+            "note": "Multiple matches found across global markets."
+        }
+
+    except Exception as e:
+        return {
+            "error": f"Failed to get symbol info: {str(e)}",
+            "hint": "Try using search_symbols to find the correct symbol format",
+        }

tradingview_mcp/tools/technical.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+from typing import Any
+
+from tradingview_mcp.column import Column
+from tradingview_mcp.constants import TECHNICAL_COLUMNS
+from tradingview_mcp.query import Query
+from tradingview_mcp.utils import sanitize_market
+
+def get_technical_analysis(symbol: str, market: str) -> dict[str, Any]:
+    """
+    Get technical indicators for a symbol.
+    
+    IMPORTANT: You must use a strictly formatted symbol and market.
+    1. Call `get_symbol_info(symbol)` first.
+    2. Use the `locator` field from the response (e.g. "EXCHANGE:SYMBOL") and the exact `market`.
+    3. Do NOT guess the market.
+    """
+    # Strict validation
+    if ":" not in symbol:
+        return {
+            "error": "Ambiguous symbol format. Missing exchange prefix.",
+            "hint": f"Please run get_symbol_info('{symbol}') first to find the correct 'EXCHANGE:{symbol}' locator and 'market'."
+        }
+    
+    # Parse strictly formatted symbol
+    exchange, ticker = symbol.split(":", 1)
+    
+    market = sanitize_market(market)
+    
+    # Use standard technical columns
+    cols = list(TECHNICAL_COLUMNS)
+    
+    try:
+        q = (
+            Query()
+            .set_markets(market)
+            .select(*cols)
+            .where(Column("name").isin([ticker, ticker.upper()])) # Use ticker part for name lookup
+            .limit(1)
+        )
+
+        _, df = q.get_scanner_data()
+        
+        if df.empty:
+            # Check if user maybe used wrong market?
+            # But we want to be strict.
+            return {
+                "error": f"Symbol '{symbol}' not found in market '{market}'.",
+                "hint": "Ensure you are using the correct market from get_symbol_info()."
+            }
+            
+        data = df.iloc[0].to_dict()
+        return {
+            "symbol": symbol,
+            "market": market,
+            "indicators": data
+        }
+    except Exception as e:
+        return {"error": str(e)}
+
+def scan_rsi_extremes(market: str = "america", limit: int = 25) -> dict[str, Any]:
+    """Find symbols with extreme RSI values (<30 or >70)."""
+    market = sanitize_market(market)
+    
+    q = (
+        Query()
+        .set_markets(market)
+        .select("name", "close", "RSI", "volume")
+        # RSI > 70 OR RSI < 30. Note: Current Query builder supports AND by default.
+        # For OR logic, we might need multiple queries or where2 if supported.
+        # Let's simple check oversold first (<30)
+        .where(Column("RSI") < 30)
+        .order_by("RSI", ascending=True)
+        .limit(limit)
+    )
+    
+    try:
+        _, df_oversold = q.get_scanner_data()
+        oversold = df_oversold.to_dict("records")
+        
+        # Overbought
+        q2 = (
+            Query()
+            .set_markets(market)
+            .select("name", "close", "RSI", "volume")
+            .where(Column("RSI") > 70)
+            .order_by("RSI", ascending=False)
+            .limit(limit)
+        )
+        _, df_overbought = q2.get_scanner_data()
+        overbought = df_overbought.to_dict("records")
+        
+        return {
+            "market": market,
+            "oversold": oversold,
+            "overbought": overbought
+        }
+    except Exception as e:
+        return {"error": str(e)}
+
+def scan_bollinger_bands(market: str = "america", limit: int = 25) -> dict[str, Any]:
+    """Find symbols trading outside Bollinger Bands."""
+    market = sanitize_market(market)
+    # This is complex to do with simple filters.
+    # We'll just return basic BB values for top volume stocks.
+    
+    q = (
+        Query()
+        .set_markets(market)
+        .select("name", "close", "BB.upper", "BB.lower")
+        .order_by("volume", ascending=False)
+        .limit(limit)
+    )
+    
+    try:
+        _, df = q.get_scanner_data()
+        return {"data": df.to_dict("records")}
+    except Exception as e:
+        return {"error": str(e)}
+
+def scan_macd_crossover(market: str = "america", limit: int = 25) -> dict[str, Any]:
+    """scan for MACD crossovers."""
+    market = sanitize_market(market)
+    q = (
+        Query()
+        .set_markets(market)
+        .select("name", "close", "MACD.macd", "MACD.signal")
+        .where(Column("MACD.macd") > Column("MACD.signal")) # Bullish crossoverish (simple comparison)
+        .order_by("volume", ascending=False)
+        .limit(limit)
+    )
+    try:
+        _, df = q.get_scanner_data()
+        return {"bullish_macd_momentum": df.to_dict("records")}
+    except Exception as e:
+        return {"error": str(e)}