Chrono MCP

# TIME CALCULATOR Tool Concept ## Overview A comprehensive time calculation tool that performs arithmetic operations on dates, times, and durations. Complements the GET TIME tool by focusing on mathematical operations rather than formatting/conversion. ## Tool Definition ### Name: `TIME CALCULATOR` ### Description Perform time arithmetic operations including duration calculations, date math, and interval operations. Supports business days, custom schedules, and complex time calculations. ## Parameters ### Core Parameters - `operation` (required): Type of calculation to perform - `add` - Add duration to a date/time - `subtract` - Subtract duration from a date/time - `diff` - Calculate difference between two dates/times - `duration_between` - Get detailed duration breakdown - `business_days` - Calculate business days between dates - `next_occurrence` - Find next occurrence of day/date pattern ### Date/Time Inputs - `base_time` (string, optional): Base ISO datetime. Defaults to current time - `target_time` (string, optional): Target datetime for comparisons/calculations - `timezone` (string, optional): Timezone for calculations (e.g., 'America/New_York') ### Duration Parameters - `years` (number, optional): Years to add/subtract - `months` (number, optional): Months to add/subtract - `days` (number, optional): Days to add/subtract - `hours` (number, optional): Hours to add/subtract - `minutes` (number, optional): Minutes to add/subtract - `seconds` (number, optional): Seconds to add/subtract ### Business Time Parameters - `exclude_weekends` (boolean, optional): Exclude Saturday/Sunday. Default: true - `holidays` (array, optional): List of holiday dates to exclude - `business_hours` (object, optional): Custom business hours - `start`: Start time (e.g., '09:00') - `end`: End time (e.g., '17:00') - `timezone`: Business hours timezone ### Pattern Parameters (for next_occurrence) - `day_of_week` (number, optional): 0=Sunday, 1=Monday, etc. - `day_of_month` (number, optional): Day of month (1-31) - `month` (number, optional): Month (1-12) ## Usage Examples ### Basic Date Math ```json { "operation": "add", "base_time": "2024-12-25T10:00:00Z", "days": 5, "hours": 3 } // Result: 2024-12-30T13:00:00Z ``` ### Duration Between Dates ```json { "operation": "diff", "base_time": "2024-01-01T00:00:00Z", "target_time": "2024-12-25T15:30:00Z" } // Result: { days: 358, hours: 15, minutes: 30, total_seconds: 30999000 } ``` ### Business Days Calculation ```json { "operation": "business_days", "base_time": "2024-12-20T00:00:00Z", "target_time": "2024-12-27T00:00:00Z", "exclude_weekends": true, "holidays": ["2024-12-25", "2024-12-26"] } // Result: 3 business days (excludes weekend + 2 holidays) ``` ### Next Occurrence Pattern ```json { "operation": "next_occurrence", "base_time": "2024-12-20T10:00:00Z", "day_of_week": 1, "timezone": "America/New_York" } // Result: Next Monday after 2024-12-20 in NY timezone ``` ## Output Format ### Standard Calculation Result ```json { "operation": "add", "input": { "base_time": "2024-12-25T10:00:00Z", "duration": { "days": 5, "hours": 3 } }, "result": "2024-12-30T13:00:00Z", "result_timezone": "UTC", "metadata": { "calculation_time": "2024-12-20T...", "timezone_offset": "+00:00" } } ``` ### Duration Breakdown Result ```json { "operation": "diff", "input": { "base_time": "2024-01-01T00:00:00Z", "target_time": "2024-12-25T15:30:00Z" }, "result": { "years": 0, "months": 11, "days": 24, "hours": 15, "minutes": 30, "seconds": 0, "total_milliseconds": 30999000000, "human_readable": "11 months, 24 days, 15 hours, 30 minutes" } } ``` ## Implementation Strategy ### Phase 1: Core Operations 1. **Basic arithmetic**: `add`, `subtract` operations with duration objects 2. **Duration calculations**: `diff`, `duration_between` with detailed breakdowns 3. **Timezone support**: All operations respect timezone context ### Phase 2: Business Time 1. **Business days**: `business_days` operation with weekend/holiday exclusion 2. **Custom schedules**: Support for business hours and custom working calendars 3. **Holiday support**: Configurable holiday lists by region ### Phase 3: Advanced Patterns 1. **Pattern matching**: `next_occurrence` for recurring events 2. **Complex intervals**: Support for business quarters, fiscal years 3. **Recurring calculations**: Monthly/yearly patterns ## Value Proposition ### Complements GET TIME - **GET TIME**: Focuses on display, formatting, timezone conversion - **TIME CALCULATOR**: Focuses on computation, arithmetic, duration analysis ### Use Cases - **Project management**: Calculate project timelines, milestones - **Business planning**: Working days, business hours calculations - **Scheduling**: Find next available slots, recurring meetings - **Analytics**: Time-based metrics, duration analysis - **SLA monitoring**: Calculate response times, uptime periods ### Technical Benefits - **Precision**: Handles complex timezone math correctly - **Business logic**: Built-in understanding of working time concepts - **Flexibility**: Supports both simple arithmetic and complex business rules - **Consistency**: Pairs perfectly with GET TIME for complete time operations ## Next Steps 1. Implement core `add`/`subtract`/`diff` operations using Luxon 2. Create business days logic with holiday/weekend handling 3. Add pattern matching for recurring date calculations 4. Integrate with existing GET TIME tool for comprehensive time toolkit