my-ffcal_get_calendar_events
Retrieve ForexFactory economic calendar events for specific time periods or custom date ranges to support trading analysis and workflow integration.
Instructions
Retrieve ForexFactory calendar events for a given time period or custom date range.Valid time_period values include: today, tomorrow, yesterday, this_week, next_week, last_week, this_month, next_month, last_month, custom.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| time_period | No | ||
| start_date | No | ||
| end_date | No |
Implementation Reference
- The core handler function that implements the tool logic: parses input time_period or custom dates, scrapes events from ForexFactory using FFScraperService, normalizes them using extract_and_normalize_events, and returns a list of event dictionaries.async def get_calendar_events( time_period: Optional[str] = None, start_date: Optional[str] = None, end_date: Optional[str] = None, ) -> list[dict]: # 👈 return JSON, not Pydantic """ Parameters ---------- time_period : str, optional Named period such as today, tomorrow, yesterday, this_week, next_week, last_week, this_month, next_month, last_month, custom. start_date : str, optional Start date in YYYY-MM-DD (required if time_period='custom'). end_date : str, optional End date in YYYY-MM-DD (required if time_period='custom'). Returns ------- List[Event] List of structured calendar events. """ # CASE 1: Named time period if time_period and time_period.lower() != "custom": try: # normalize before parsing normalized = time_period.strip().lower().replace(" ", "_") tp = TimePeriod.from_text(normalized) except ValueError: raise ValueError( f"Invalid time_period '{time_period}'. " f"Valid options: {', '.join([t.value for t in TimePeriod])}" ) scraper = FFScraperService(time_period=tp) raw_events = await scraper.get_events() # CASE 2: Custom date range else: TimePeriod.validate_date_format(start_date) TimePeriod.validate_date_format(end_date) scraper = FFScraperService( time_period=TimePeriod.CUSTOM, custom_start_date=start_date, custom_end_date=end_date, ) raw_events = await scraper.get_events() normalized = extract_and_normalize_events(raw_events) return normalized
- src/forexfactory_mcp/tools/get_calendar_tool.py:18-23 (registration)The @app.tool decorator that registers the tool with the exact name f'{namespace}_get_calendar_events' (namespace='ffcal'), along with description. Note: tool name becomes 'ffcal_get_calendar_events' by default.@app.tool( name=f"{namespace}_get_calendar_events", description="Retrieve ForexFactory calendar events for a given time period or custom date range." "Valid `time_period` values include: today, tomorrow, yesterday, " "this_week, next_week, last_week, this_month, next_month, last_month, custom.", )
- src/forexfactory_mcp/tools/tools_manager.py:17-17 (registration)Invocation of register_get_calendar_tool within the central tools_manager.register_tools function.register_get_calendar_tool(app, namespace)
- src/forexfactory_mcp/server.py:94-94 (registration)High-level registration call in server setup_app function, passing the namespace from settings.register_tools(_app, settings.NAMESPACE)
- Defines the NAMESPACE='ffcal' used to prefix tool names, resulting in 'ffcal_get_calendar_events'. This could be overridden to 'my-ffcal' via environment variable.NAMESPACE: str = "ffcal"