# Date Utils Engine MCP for AI Agents MCP > Date Utils Engine provides deterministic calendar math for AI agents. It stops LLMs from hallucinating dates, missing leap years, or failing timezone conversions. Your agent offloads all complex time calculations to this engine, guaranteeing 100% accurate date arithmetic and reliable global timezone shifts. ## Overview - **Category:** loved-by-devs - **Price:** Free - **Tags:** date-math, timezone-conversion, leap-year, calendar-logic, javascript-library, deterministic-calculation ## Description LLMs struggle with consistent timekeeping; they treat calendar math as text tokens, not actual clock data. This MCP brings the industry-standard `date-fns` logic directly into your agentic workflows. You can trust it to handle complex dates, reliably adding or subtracting days, months, and years while maintaining perfect calendar accuracy. Need to shift a date? Simply provide an ISO timestamp and an IANA timezone identifier. The engine automatically accounts for Daylight Saving Time changes, turning messy UTC times into precise local clock readings. When you connect Date Utils Engine through the Vinkius catalog, your AI client gains reliable mathematical certainty for time-sensitive tasks, letting you write code that just works. ## Tools ### add_days Adds or subtracts a specific number of calendar days from a date, guaranteeing 100% accuracy. ### diff_dates Calculates the exact time difference between two dates and returns the delta in days, hours, minutes, and seconds. ### parse_date Takes a raw date string and safely parses it, confirming that it is a valid calendar date object. ### to_timezone Converts an ISO date string to any specific IANA timezone, correctly handling Daylight Saving Time shifts automatically. ## Prompt Examples **Prompt:** ``` What is the exact date 90 calendar days from today's date? ``` **Response:** ``` **Calculation:** * Start Date: October 12, 2024 * Days Added: 90 **Resulting Date:** December 10, 2024 (This calculation correctly accounts for the varying length of months and year boundaries.) ``` **Prompt:** ``` Convert this UTC time to New York time. ``` **Response:** ``` **Input Timestamp:** `2026-07-15T18:00:00Z` **Target Timezone:** America/New_York ✅ **Local Time Shift:** 2026-07-15 14:00:00-04:00 (The shift correctly applies the Daylight Saving Time offset for July.) ``` **Prompt:** ``` How many days are between January 1, 2023 and March 1, 2025? ``` **Response:** ``` **Date Difference Calculation:** * Start Date: 2023-01-01 * End Date: 2025-03-01 **Difference:** There are exactly **791** days between the two dates. (This calculation correctly includes leap years.) ``` ## Capabilities ### Add or Subtract Calendar Days Calculate a precise future or past date by adding or subtracting a specific number of calendar days from any given starting date. ### Determine Time Differences Between Dates Get the exact time delta between two dates, providing counts in days, hours, minutes, and seconds. ### Validate Raw Date Strings Take a raw date string and safely parse it to confirm it represents an actual, valid calendar date object. ### Convert Timezones Reliably Shift any UTC or ISO date to a specific IANA timezone (like America/Los_Angeles), automatically adjusting for Daylight Saving Time rules. ## Use Cases ### Calculating a Project Milestone Date A PM needs to know when a task starting on March 1st will finish after exactly 60 working days. The agent uses `add_days` to calculate the correct end date, avoiding calendar errors that would push the deadline incorrectly. ### Comparing Event Timelines Globally A data analyst must compare two event timestamps recorded in UTC and one local time zone (e.g., Europe/Berlin). The agent uses `to_timezone` to normalize both dates, providing a single, accurate comparison delta using `diff_dates`. ### Validating User Input Forms A developer needs to check if user-submitted date strings are actually valid before processing them. The agent runs the input through `parse_date`, instantly catching any malformed or non-existent dates, preventing system crashes. ### Analyzing Time Spans in Historical Data A researcher collects two records with timestamps from different time zones. The agent uses `to_timezone` to align both records to a single standard (e.g., UTC) before using `diff_dates` to get the precise span. ## Benefits - Avoids LLM calendar hallucinations entirely. Instead of guessing dates, your agent uses `add_days` to move a date forward or backward with guaranteed accuracy. - Manages complex time zones effortlessly. The `to_timezone` tool converts any UTC timestamp into the correct local time for an IANA zone, even across DST changes. - Ensures data integrity upfront. Use `parse_date` to validate messy inputs before running critical calculations like those from `diff_dates`. - Saves debugging time. By offloading math, your team stops spending hours fixing date-related bugs that are notoriously difficult to track down. - Maintains determinism. The engine executes as native V8 JavaScript, meaning the output is predictable and consistent every single time you call `add_days` or `to_timezone`. ## How It Works The bottom line is your agent doesn't guess about dates; it runs them through reliable, industry-standard calendar logic. 1. Start by giving your AI client the initial data: an ISO formatted date string and the mathematical operation required, like 'add 45 days' or 'convert to America/Sao_Paulo'. 2. The MCP sends this request to the deterministic engine, which performs the complex calendar math locally, bypassing typical LLM time errors. 3. You get back a confirmed, accurate date object or delta that accounts for every leap year and timezone rule in play. ## Frequently Asked Questions **Does Date Utils Engine help my AI agents with time zone changes?** Yes, it reliably converts any global timestamp to a specific local timezone using the IANA format. It automatically adjusts for Daylight Saving Time shifts, so you never have to worry about incorrect offsets again. **Can Date Utils Engine calculate dates that span multiple years or months?** Absolutely. The engine handles complex date arithmetic, letting you add or subtract days across year boundaries and through varying month lengths with guaranteed accuracy. **Why should I use this MCP instead of just telling my agent the math?** Because LLMs are bad at calendar math. This MCP offloads date logic to a deterministic engine, meaning the results are mathematically certain and reliable in production code. **Is Date Utils Engine useful for calculating time differences between two dates?** It's perfect for that. You can use it to determine the exact number of days, hours, or minutes separating any two given timestamps, including leap year considerations. **What if I have a messy date string? Can Date Utils Engine fix it?** The engine includes a tool that safely parses raw date strings. It validates the input first, ensuring you are working with an actual calendar date before any calculations begin.