1#!/usr/bin/env python3
2"""
3CoinGecko Coin OHLC Chart within Time Range Tool - MCP Compliant
4 
5API Reference: https://docs.coingecko.com/reference/coins-id-ohlc-range
6Returns: Array of [timestamp_ms, open, high, low, close] in USD
7"""
8 
9import os
10from dotenv import load_dotenv
11import time
12import argparse
13import json
14import sys
15try:
16    from .utils import parse_flexible_time, split_time_range, merge_ohlc_data, get_days_difference, search_coin_by_name
17except ImportError:
18    from utils import parse_flexible_time, split_time_range, merge_ohlc_data, get_days_difference, search_coin_by_name
19 
20from core.http_client import proxied_get
21 
22# Load environment variables from project root directory
23project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..', '..', '..'))
24load_dotenv(os.path.join(project_root, '.env'))
25 
26# MCP Tool Schema
27MCP_TOOL_SCHEMA = {
28    "name": "get_coin_ohlc_range_by_id",
29    "title": "CoinGecko OHLC Range",
30    "description": "Retrieve OHLC candlestick data within a custom time range for technical analysis. Supports unlimited time ranges (365+ days) with automatic data splitting for large ranges. Will return a lot of data, use with caution.",
31    "inputSchema": {
32        "$schema": "https://json-schema.org/draft/2020-12/schema",
33        "type": "object",
34        "properties": {
35            "coin_id": {
36                "type": "string",
37                "minLength": 1,
38                "description": "The coin ID (e.g., 'bitcoin', 'ethereum') or symbol (e.g., 'BTC', 'ETH')"
39            },
40            "from_timestamp": {
41                "type": ["string", "integer", "number"],
42                "description": "Start time - supports Unix timestamp, ISO date ('2023-01-01'), or natural language ('2 weeks ago', 'last month')"
43            },
44            "to_timestamp": {
45                "type": ["string", "integer", "number"],
46                "description": "End time - same formats as from_timestamp"
47            },
48            "interval": {
49                "type": ["string", "null"],
50                "enum": ["daily", "hourly", None],
51                "description": "Data interval - 'daily' (max 180 days per request), 'hourly' (max 31 days per request), or null for auto-selection based on time range"
52            }
53        },
54        "required": ["coin_id", "from_timestamp", "to_timestamp"],
55        "additionalProperties": False
56    },
57    "outputSchema": {
58        "$schema": "https://json-schema.org/draft/2020-12/schema",
59        "type": "array",
60        "items": {
61            "type": "array",
62            "items": [
63                {"type": "number", "description": "Unix timestamp in milliseconds"},
64                {"type": "number", "description": "Opening price in USD"},
65                {"type": "number", "description": "Highest price in USD"},
66                {"type": "number", "description": "Lowest price in USD"},
67                {"type": "number", "description": "Closing price in USD"}
68            ],
69            "minItems": 5,
70            "maxItems": 5
71        },
72        "description": "Array of OHLC candlestick data where each item is [timestamp_ms, open, high, low, close] in USD"
73    },
74    "annotations": {
75        "path": "tools/coingecko/coin_ohlc_range_by_id.py",
76        "function": "get_coin_ohlc_range_by_id",
77        "examples": [
78            {
79                "name": "basic_daily",
80                "arguments": {
81                    "coin_id": "bitcoin",
82                    "from_timestamp": "2024-01-01",
83                    "to_timestamp": "2024-01-07",
84                    "interval": "daily"
85                }
86            },
87            {
88                "name": "natural_language",
89                "arguments": {
90                    "coin_id": "ETH",
91                    "from_timestamp": "30 days ago",
92                    "to_timestamp": "today",
93                    "interval": "hourly"
94                }
95            }
96        ]
97    }
98}
99 
100def get_coin_ohlc_range_by_id(coin_id, from_timestamp=None, to_timestamp=None, interval=None):
101    """
102    Fetch OHLC chart data for a specific coin within a time range from CoinGecko Pro API.
103    Handles automatic data splitting for large time ranges. Currency fixed to USD.
104    """
105    if not coin_id:
106        raise ValueError("coin_id parameter is required")
107    
108    if not from_timestamp or not to_timestamp:
109        raise ValueError("Both from_timestamp and to_timestamp are required")
110    
111    # Convert symbol to ID if needed
112    coin_result = search_coin_by_name(coin_id)
113    if not coin_result:
114        raise ValueError(f"Could not find coin with symbol or name: {coin_id}")
115    actual_coin_id = coin_result['id']
116    
117    # Currency is fixed to USD
118    vs_currency = 'usd'
119    
120    # Parse flexible time inputs
121    from_ts = parse_flexible_time(from_timestamp)
122    to_ts = parse_flexible_time(to_timestamp)
123    
124    if from_ts >= to_ts:
125        raise ValueError("from_timestamp must be earlier than to_timestamp")
126    
127    # Validate interval parameter
128    if interval is not None:
129        valid_intervals = ['daily', 'hourly']
130        if interval not in valid_intervals:
131            raise ValueError(f"interval must be one of {valid_intervals} or None, got: {interval}")
132    
133    # Determine optimal interval and splitting strategy
134    days_diff = get_days_difference(from_ts, to_ts)
135    
136    # Auto-select interval if not specified
137    if interval is None:
138        if days_diff <= 31:
139            interval = 'hourly'
140        else:
141            interval = 'daily'
142    
143    # Validate time range against interval limits
144    if interval == 'hourly' and days_diff > 31:
145        if days_diff <= 180:
146            # Switch to daily for better compatibility
147            interval = 'daily'
148        else:
149            # Split into hourly chunks (31 days each) then merge
150            return _fetch_ohlc_with_splitting(actual_coin_id, vs_currency, from_ts, to_ts, 'hourly', 31)
151    elif interval == 'daily' and days_diff > 180:
152        # Split into daily chunks (180 days each) then merge
153        return _fetch_ohlc_with_splitting(actual_coin_id, vs_currency, from_ts, to_ts, 'daily', 180)
154    
155    # Single request
156    return _fetch_single_ohlc_range(actual_coin_id, vs_currency, from_ts, to_ts, interval)
157 
158 
159def _fetch_ohlc_with_splitting(coin_id, vs_currency, from_ts, to_ts, interval, max_days):
160    """Fetch OHLC data with automatic splitting for large ranges."""
161    time_chunks = split_time_range(from_ts, to_ts, max_days=max_days)
162    data_chunks = []
163    
164    for chunk_start, chunk_end in time_chunks:
165        chunk_data = _fetch_single_ohlc_range(coin_id, vs_currency, chunk_start, chunk_end, interval)
166        data_chunks.append(chunk_data)
167        # Small delay between requests to be respectful to the API
168        time.sleep(0.5)
169    
170    # Merge all chunks
171    return merge_ohlc_data(data_chunks)
172 
173 
174def _fetch_single_ohlc_range(coin_id, vs_currency, from_timestamp, to_timestamp, interval):
175    """Fetch OHLC data for a single time range."""
176    url = f"https://pro-api.coingecko.com/api/v3/coins/{coin_id}/ohlc/range"
177    params = {
178        'vs_currency': vs_currency,
179        'from': from_timestamp,
180        'to': to_timestamp
181    }
182    if interval:
183        params['interval'] = interval
184    
185    headers = {"x-cg-pro-api-key": os.getenv("COINGECKO_API_KEY")}
186    
187    if not headers["x-cg-pro-api-key"]:
188        raise ValueError("COINGECKO_API_KEY environment variable is required")
189    
190    # Retry logic
191    for attempt in range(3):
192        try:
193            resp = proxied_get(url, params=params, headers=headers, timeout=15)
194            resp.raise_for_status()
195            return resp.json()
196        except Exception as e:
197            if attempt == 2:  # Last attempt
198                raise ConnectionError(f"API request failed after retries: {e}")
199            time.sleep(1)
200 
201 
202# Backward compatibility
203def get_coin_ohlc_range(coin_id, vs_currency='usd', from_timestamp=None, to_timestamp=None, interval=None):
204    """Backward compatibility wrapper for get_coin_ohlc_range_by_id. vs_currency is ignored (always USD)."""
205    return get_coin_ohlc_range_by_id(coin_id, from_timestamp, to_timestamp, interval)
206 
207 
208def main():
209    """Command-line interface for the coin OHLC range tool."""
210    
211    # Handle MCP schema queries first (single argument only)
212    if len(sys.argv) == 2:
213        arg = sys.argv[1]
214        
215        if arg == "--schema":
216            print(json.dumps(MCP_TOOL_SCHEMA, indent=2, sort_keys=True, ensure_ascii=False))
217            return 0
218        elif arg.startswith("--") and len(arg) > 2:
219            field_name = arg[2:]  # Remove "--" prefix
220            if field_name in MCP_TOOL_SCHEMA:
221                field_value = MCP_TOOL_SCHEMA[field_name]
222                print(json.dumps(field_value, indent=2, sort_keys=True, ensure_ascii=False))
223                return 0
224 
225    parser = argparse.ArgumentParser(
226        description="Fetch OHLC chart data within a time range for a specific coin from CoinGecko API.",
227        epilog="""INPUT:
228  --coin_id: Coin ID/symbol (bitcoin, BTC, ethereum, ETH)
229  --from_timestamp: Start time ("30 days ago", "2023-01-01", timestamp)
230  --to_timestamp: End time ("today", "2023-12-31", timestamp)  
231  --interval: Data interval (daily, hourly, or auto-select)
232 
233OUTPUT:
234  JSON array of OHLC data points:
235  [{"timestamp": 1640995200, "open": 46300.45, "high": 47100.23, 
236    "low": 45800.12, "close": 46950.78}]
237 
238EXAMPLE:
239  python coin_ohlc_range_by_id.py --coin_id BTC --from_timestamp "30 days ago" --to_timestamp "today"
240  python coin_ohlc_range_by_id.py --coin_id ethereum --from_timestamp "2023-01-01" --to_timestamp "2023-12-31" --interval daily
241        """,
242        formatter_class=argparse.RawDescriptionHelpFormatter
243    )
244    
245    # MCP schema arguments
246    parser.add_argument('--schema', action='store_true', help='Output complete MCP Tool Schema (JSON)')
247    parser.add_argument('--name', action='store_true', help='Output tool name')
248    parser.add_argument('--title', action='store_true', help='Output tool title')
249    parser.add_argument('--description', action='store_true', help='Output tool description')
250    parser.add_argument('--inputSchema', action='store_true', help='Output input schema')
251    parser.add_argument('--outputSchema', action='store_true', help='Output output schema')
252    parser.add_argument('--annotations', action='store_true', help='Output annotations')
253    
254    # Original functionality arguments
255    parser.add_argument('--coin_id', help='Coin id (e.g., bitcoin) or symbol (e.g., BTC)')
256    parser.add_argument('--from_timestamp', type=str,
257                       help='Start time - supports: Unix timestamp, ISO date (2023-01-01), natural language ("2 weeks ago", "last month")')
258    parser.add_argument('--to_timestamp', type=str,
259                       help='End time - same formats as from_timestamp')
260    parser.add_argument('--interval', type=str, choices=['daily', 'hourly'], 
261                       help='Data interval - "daily" (max 180 days) or "hourly" (max 31 days). Auto-selected if not specified')
262 
263    args = parser.parse_args()
264    
265    # Handle MCP schema queries
266    if args.schema:
267        print(json.dumps(MCP_TOOL_SCHEMA, indent=2, sort_keys=True, ensure_ascii=False))
268        return 0
269    elif args.name:
270        print(json.dumps(MCP_TOOL_SCHEMA["name"], ensure_ascii=False))
271        return 0
272    elif args.title:
273        print(json.dumps(MCP_TOOL_SCHEMA["title"], ensure_ascii=False))
274        return 0
275    elif args.description:
276        print(json.dumps(MCP_TOOL_SCHEMA["description"], ensure_ascii=False))
277        return 0
278    elif args.inputSchema:
279        print(json.dumps(MCP_TOOL_SCHEMA["inputSchema"], indent=2, sort_keys=True, ensure_ascii=False))
280        return 0
281    elif args.outputSchema:
282        print(json.dumps(MCP_TOOL_SCHEMA["outputSchema"], indent=2, sort_keys=True, ensure_ascii=False))
283        return 0
284    elif args.annotations:
285        print(json.dumps(MCP_TOOL_SCHEMA["annotations"], indent=2, sort_keys=True, ensure_ascii=False))
286        return 0
287    
288    # Validate required arguments for normal operation
289    if not args.coin_id:
290        parser.error("--coin_id is required")
291    if not args.from_timestamp:
292        parser.error("--from_timestamp is required")
293    if not args.to_timestamp:
294        parser.error("--to_timestamp is required")
295 
296    try:
297        data = get_coin_ohlc_range_by_id(
298            coin_id=args.coin_id,
299            from_timestamp=args.from_timestamp,
300            to_timestamp=args.to_timestamp,
301            interval=args.interval
302        )
303        print(json.dumps(data, ensure_ascii=False, indent=2))
304    except Exception as e:
305        print(f"Failed to fetch OHLC range data: {e}")
306        return 1
307        
308    return 0
309 
310 
311if __name__ == "__main__":
312    exit(main())