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

tradingview_mcp/server.py

@@ -7,8 +7,12 @@ Provides comprehensive MCP tools and resources for TradingView market screening.
 from __future__ import annotations
 
 import argparse
+import inspect
 import json
 import os
+import traceback
+from datetime import datetime
+from functools import wraps
 from typing import Any, Optional
 
 from mcp.server.fastmcp import FastMCP
@@ -38,6 +42,23 @@ from tradingview_mcp.utils import (
     sanitize_timeframe,
     timeframe_to_resolution,
 )
+from tradingview_mcp.docs_data import (
+    get_ai_quick_reference,
+    get_column_display_names,
+    get_common_fields,
+    get_fields_by_market,
+    get_markets_data,
+    get_metainfo as load_metainfo,
+    get_screener_code_examples,
+    get_screener_markets,
+    get_screener_presets,
+    paginate_data,
+    search_fields,
+    get_field_summary,
+    estimate_tokens,
+    truncate_for_tokens,
+    MAX_ITEMS_DEFAULT,
+)
 
 # Initialize MCP Server
 mcp = FastMCP(
@@ -45,10 +66,101 @@ mcp = FastMCP(
     instructions=(
         "A comprehensive MCP server for TradingView market screening. "
         "Provides tools for stock and cryptocurrency screening, technical analysis, "
-        "and market data retrieval. Supports 76+ markets and 250+ technical indicators."
+        "and market data retrieval. Supports 76+ markets and 250+ technical indicators. "
+        "Docs resources: docs://params, docs://screeners, docs://fields, docs://markets. "
+        "Set TRADINGVIEW_MCP_DEBUG=1 for detailed debug responses on errors."
     ),
 )
 
+DEBUG_MODE = os.getenv("TRADINGVIEW_MCP_DEBUG", "0").lower() in {"1", "true", "yes"}
+
+
+def _safe_json(value: Any) -> Any:
+    try:
+        return json.loads(json.dumps(value, default=str))
+    except Exception:
+        return str(value)
+
+
+def _debug_hint(exc: Exception) -> str | None:
+    message = str(exc).lower()
+    if "market" in message and "invalid" in message:
+        return "Check the market name using the markets://list or docs://screeners resources."
+    if "column" in message and "unknown" in message:
+        return "Check available columns via columns://list or docs://fields."
+    if "http" in message or "status" in message:
+        return "TradingView API may be rate-limiting or blocked. Retry with fewer requests."
+    return None
+
+
+def _build_error_response(tool_name: str, exc: Exception, context: dict[str, Any]) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "ok": False,
+        "tool": tool_name,
+        "error": {"type": exc.__class__.__name__, "message": str(exc)},
+        "context": _safe_json(context),
+        "timestamp": datetime.utcnow().isoformat() + "Z",
+    }
+    hint = _debug_hint(exc)
+    if hint:
+        payload["hint"] = hint
+    if DEBUG_MODE:
+        payload["trace"] = traceback.format_exc()
+    return payload
+
+
+def _error_response(exc: Exception, context: dict[str, Any] | None = None) -> dict[str, Any]:
+    frame = inspect.currentframe()
+    caller = frame.f_back.f_code.co_name if frame and frame.f_back else "unknown"
+    return _build_error_response(caller, exc, context or {})
+
+
+def debug_tool(fn):
+    """Decorator to return structured debug responses on failure."""
+
+    @wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            result = fn(*args, **kwargs)
+            if isinstance(result, dict) and "error" in result:
+                return _build_error_response(
+                    fn.__name__,
+                    Exception(str(result.get("error"))),
+                    {"args": args, "kwargs": kwargs, "note": "error returned by tool"},
+                )
+            if (
+                isinstance(result, list)
+                and len(result) == 1
+                and isinstance(result[0], dict)
+                and "error" in result[0]
+            ):
+                return _build_error_response(
+                    fn.__name__,
+                    Exception(str(result[0].get("error"))),
+                    {"args": args, "kwargs": kwargs, "note": "error returned by tool"},
+                )
+            return result
+        except Exception as exc:  # pragma: no cover - defensive guard
+            context = {"args": args, "kwargs": kwargs}
+            return _build_error_response(fn.__name__, exc, context)
+
+    return wrapper
+
+
+_original_mcp_tool = mcp.tool
+
+
+def _debug_mcp_tool(*args, **kwargs):
+    """Wrap FastMCP tool registration with debug handling."""
+
+    def decorator(fn):
+        return _original_mcp_tool(*args, **kwargs)(debug_tool(fn))
+
+    return decorator
+
+
+mcp.tool = _debug_mcp_tool
+
 
 # =============================================================================
 # MCP Resources
@@ -242,6 +354,364 @@ def list_scanner_presets() -> str:
     return result
 
 
+@mcp.resource("docs://params")
+def docs_params() -> str:
+    """TradingView screener parameter format and schema."""
+    schema = {
+        "markets": ["america"],
+        "columns": ["close", "volume", "market_cap_basic"],
+        "filter": [
+            {"left": "change", "operation": "gt", "right": 2},
+            {"left": "volume", "operation": "greater", "right": 1000000},
+        ],
+        "filter2": {
+            "operator": "and",
+            "operands": [
+                {
+                    "expression": {"left": "type", "operation": "equal", "right": "stock"}
+                },
+                {
+                    "expression": {"left": "is_primary", "operation": "equal", "right": True}
+                },
+            ],
+        },
+        "symbols": {"query": {"types": []}, "tickers": []},
+        "sort": {"sortBy": "market_cap_basic", "sortOrder": "desc"},
+        "range": [0, 50],
+        "options": {"lang": "en"},
+        "ignore_unknown_fields": False,
+        "price_conversion": {"to_symbol": False},
+    }
+
+    format_notes = (
+        "# Screener Params Format\n\n"
+        "## Core fields\n"
+        "- markets: list of market identifiers (e.g., america, crypto, forex)\n"
+        "- columns: list of fields to return\n"
+        "- filter: flat list of expressions\n"
+        "- filter2: nested boolean logic tree (and/or)\n"
+        "- symbols: optional tickers/types filter\n"
+        "- sort: {sortBy, sortOrder}\n"
+        "- range: [offset, limit]\n"
+        "- options: {lang}\n"
+        "- ignore_unknown_fields: boolean\n"
+        "- price_conversion: {to_symbol}\n\n"
+        "## Expression format\n"
+        "{left: <field>, operation: <op>, right: <value>}\n\n"
+        "Common operations: equal, ne, gt, gte, lt, lte, in_range, has, has_none_of\n\n"
+        "## Example schema\n"
+    )
+    return format_notes + json.dumps(schema, ensure_ascii=False, indent=2)
+
+
+@mcp.resource("docs://screeners")
+def docs_screeners() -> str:
+    """Predefined screener presets from docs data (compact overview)."""
+    presets = get_screener_presets()
+    overview = [
+        {"name": p.get("name"), "url": p.get("url"), "has_query": bool(p.get("query"))}
+        for p in presets
+    ]
+    return json.dumps(overview, ensure_ascii=False, indent=2)
+
+
+@mcp.resource("docs://fields")
+def docs_fields() -> str:
+    """Field display names (first 100). Use search_available_fields tool for more."""
+    mapping = get_column_display_names()
+    # Limit output to save tokens
+    limited = dict(list(mapping.items())[:100])
+    result = {
+        "fields": limited,
+        "total": len(mapping),
+        "note": "Showing first 100 fields. Use search_available_fields() tool to search for specific fields.",
+    }
+    return json.dumps(result, ensure_ascii=False, indent=2)
+
+
+@mcp.resource("docs://markets")
+def docs_markets() -> str:
+    """Markets metadata (compact). Use ai_get_reference tool for categorized list."""
+    markets = get_markets_data()
+    screener_markets = get_screener_markets()
+    return json.dumps(
+        {
+            "markets_count": len(markets) if isinstance(markets, (list, dict)) else 0,
+            "screener_markets": screener_markets,
+            "hint": "Use ai_get_reference() tool for full categorized market list.",
+        },
+        ensure_ascii=False,
+        indent=2,
+    )
+
+
+@mcp.tool()
+def get_field_info(field: str) -> dict[str, Any]:
+    """Get display name, type, and related info for a field.
+    
+    Args:
+        field: Field/column name to look up
+        
+    Returns:
+        Field info including display name, type, and variants if available
+    """
+    # Try get_field_summary first (uses common_fields)
+    summary = get_field_summary(field)
+    if summary and summary.get("display_name"):
+        return summary
+    
+    # Fallback to display names mapping
+    mapping = get_column_display_names()
+    display = mapping.get(field)
+    if display:
+        return {"field": field, "display_name": display}
+
+    # Try case-insensitive or partial matches
+    normalized = field.lower()
+    suggestions = [
+        name for name in list(mapping.keys())[:500]
+        if normalized in name.lower() or normalized in str(mapping[name]).lower()
+    ][:10]
+    return {
+        "field": field,
+        "display_name": None,
+        "suggestions": suggestions,
+    }
+
+
+@mcp.tool()
+def get_screener_preset(name: str) -> dict[str, Any]:
+    """Return a full screener preset (query + code) by name."""
+    presets = get_screener_presets()
+    for preset in presets:
+        if preset.get("name", "").lower() == name.lower():
+            return preset
+    return {
+        "error": f"Preset '{name}' not found.",
+        "available": [p.get("name") for p in presets],
+    }
+
+
+@mcp.tool()
+def get_market_metainfo(
+    market: str,
+    limit: int = 50,
+    offset: int = 0,
+    confirm_large: bool = False,
+) -> dict[str, Any]:
+    """Return metainfo (field definitions and allowed values) for a market.
+    
+    Args:
+        market: Market type (stocks, crypto, forex, bond, etc.)
+        limit: Maximum fields to return (default 50, max 500)
+        offset: Starting offset for pagination
+        confirm_large: Set True to allow returning more than 100 items
+        
+    Returns:
+        Paginated metainfo with field definitions
+    """
+    limit = min(limit, 500)  # Hard cap
+    
+    try:
+        metainfo = load_metainfo(market)
+        
+        # Paginate if it's a list or large dict
+        if isinstance(metainfo, list):
+            return paginate_data(metainfo, offset, limit, confirm_large)
+        elif isinstance(metainfo, dict):
+            # Return summary if too large
+            total_fields = len(metainfo.get("fields", []))
+            if total_fields > MAX_ITEMS_DEFAULT and not confirm_large:
+                return {
+                    "market": market,
+                    "total_fields": total_fields,
+                    "warning": f"⚠️ Large data ({total_fields} fields). Use limit/offset to paginate or set confirm_large=True.",
+                    "sample_fields": list(metainfo.get("fields", {}).keys())[:20] if isinstance(metainfo.get("fields"), dict) else None,
+                }
+            return {"market": market, "metainfo": metainfo}
+        return {"market": market, "metainfo": metainfo}
+    except FileNotFoundError:
+        return {
+            "error": f"Metainfo for '{market}' not found.",
+            "available_markets": ["stocks", "crypto", "forex", "bond", "bonds", "cfd", "futures", "options", "coin", "economics2"],
+            "hint": "Use one of the available markets listed above.",
+        }
+
+
+# =============================================================================
+# AI-Friendly Tools - Quick Reference and Search
+# =============================================================================
+
+
+@mcp.resource("docs://ai-reference")
+def docs_ai_reference() -> str:
+    """AI quick reference guide with common patterns, markets, and filters."""
+    ref = get_ai_quick_reference()
+    return json.dumps(ref, ensure_ascii=False, indent=2)
+
+
+@mcp.resource("docs://code-examples")  
+def docs_code_examples() -> str:
+    """Python code examples for common screener queries."""
+    examples = get_screener_code_examples()
+    return json.dumps(examples, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+def ai_get_reference() -> dict[str, Any]:
+    """Get AI-friendly quick reference for this MCP.
+    
+    Returns a compact guide with:
+    - Available markets by category
+    - Common columns by type  
+    - Filter operations
+    - Common filter patterns
+    - Timeframes
+    
+    This is the recommended starting point for AI agents to understand how to use this MCP.
+    """
+    return get_ai_quick_reference()
+
+
+@mcp.tool()
+def search_available_fields(
+    query: str,
+    market: str = "stocks",
+    limit: int = 20,
+) -> dict[str, Any]:
+    """Search for fields/columns by name or description.
+    
+    Args:
+        query: Search term (e.g., "volume", "RSI", "market cap")
+        market: Market type to search in (stocks, crypto, forex, etc.)
+        limit: Maximum results (default 20, max 50)
+        
+    Returns:
+        Matching fields with their display names and types
+    """
+    limit = min(limit, 50)
+    results = search_fields(query, market, limit)
+    
+    return {
+        "query": query,
+        "market": market,
+        "count": len(results),
+        "fields": results,
+        "hint": "Use the 'name' field as the column name in queries." if results else "No matches found. Try a different search term.",
+    }
+
+
+@mcp.tool()
+def get_code_example(screener_name: str) -> dict[str, Any]:
+    """Get Python code example for a specific screener type.
+    
+    Args:
+        screener_name: Screener name (e.g., "Stocks (legacy)", "Crypto", "Forex", "ETFs", "Bonds")
+        
+    Returns:
+        Python code example for building that screener query
+    """
+    examples = get_screener_code_examples()
+    
+    # Try exact match first
+    if screener_name in examples:
+        return {
+            "name": screener_name,
+            "code": examples[screener_name],
+        }
+    
+    # Try case-insensitive match
+    for name, code in examples.items():
+        if name.lower() == screener_name.lower():
+            return {"name": name, "code": code}
+    
+    # Return available options
+    return {
+        "error": f"Example '{screener_name}' not found.",
+        "available": list(examples.keys()),
+        "hint": "Use one of the available screener names listed above.",
+    }
+
+
+@mcp.tool()
+def list_fields_for_market(
+    market: str = "stocks",
+    category: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+    confirm_large: bool = False,
+) -> dict[str, Any]:
+    """List available fields for a specific market with pagination.
+    
+    Args:
+        market: Market type (stocks, crypto, forex, coin, bond, cfd, futures, options)
+        category: Optional filter by field type (price, volume, fundamental, technical)
+        limit: Maximum results (default 50, max 200)
+        offset: Starting offset for pagination
+        confirm_large: Set True to allow more than 100 results
+        
+    Returns:
+        Paginated list of field definitions
+    """
+    limit = min(limit, 200)
+    
+    fields = get_fields_by_market(market)
+    
+    if not fields:
+        return {
+            "error": f"No fields found for market '{market}'.",
+            "available_markets": ["stocks", "crypto", "forex", "coin", "bond", "bonds", "cfd", "futures", "options", "economics2", "ireland"],
+        }
+    
+    # Filter by category if specified
+    if category and isinstance(fields, list):
+        category_lower = category.lower()
+        fields = [f for f in fields if category_lower in f.get("type", "").lower()]
+    
+    return paginate_data(fields, offset, limit, confirm_large)
+
+
+@mcp.tool()
+def get_common_fields_summary(
+    category: str | None = None,
+    limit: int = 30,
+) -> dict[str, Any]:
+    """Get summary of commonly used fields across all markets.
+    
+    Args:
+        category: Optional filter (price, volume, fundamental, technical, rating)
+        limit: Maximum fields to return (default 30)
+        
+    Returns:
+        Dict with field names, display names, and types
+    """
+    ref = get_ai_quick_reference()
+    common_cols = ref.get("common_columns", {})
+    
+    if category:
+        category_lower = category.lower()
+        if category_lower in common_cols:
+            return {
+                "category": category,
+                "fields": common_cols[category_lower],
+            }
+        return {
+            "error": f"Category '{category}' not found.",
+            "available_categories": list(common_cols.keys()),
+        }
+    
+    # Return all categories with limited fields
+    result = {}
+    for cat, fields in common_cols.items():
+        result[cat] = fields[:limit] if len(fields) > limit else fields
+    
+    return {
+        "categories": result,
+        "total_categories": len(common_cols),
+        "hint": "Use category parameter to filter by type.",
+    }
+
+
 # =============================================================================
 # MCP Tools - Basic Screening
 # =============================================================================