ChronoGuard

Deterministic date, time, timezone, holiday, and business-day arithmetic for AI agents via MCP.

LLMs are good at language. They should not have to guess whether a deadline lands on a holiday, whether five business days crosses a weekend, or what a timestamp means across a daylight-saving transition. ChronoGuard moves that work into a small deterministic tool with a stable contract.

Status

v0.1.1 — public validation prototype

Validated in Replit on September 11, 2026 with:

• 28 automated tests passing
• FastMCP 4.0.3
• MCP 2.2.0
• Real holidays package integration
• Successful real stdio MCP client discovery of chronoguard_resolve_time
• Successful end-to-end MCP tool invocation through the stdio server
• Successful FastMCP inspector discovery

ChronoGuard is ready for developer testing, but it is not yet positioned as production-grade global business-calendar infrastructure.

What ChronoGuard solves

ChronoGuard gives an agent a deterministic answer for temporal questions that are easy for an LLM to get subtly wrong.

Example workflows:

1. SLA deadlines — “What is 4 US business days after this support ticket opened?”
2. Billing and finance cutoffs — “What is the previous business day before month-end?”
3. Rolling data windows — “Give me the exact timestamps for the last 30 days.”
4. Timezone-safe scheduling — “Convert this timestamp to America/Chicago and preserve the correct date.”
5. Holiday-aware automation — “What date is 5 business days after Friday, September 11, 2026?”

Supported operations

The MCP tool is named:

chronoguard_resolve_time

Supported operations:

• current_time
• add_duration
• subtract_duration
• business_day_offset
• calculate_span

Supported units:

• minutes
• hours
• days
• weeks
• business_days

Other inputs:

• IANA timezone such as America/Chicago or UTC
• ISO-8601 reference timestamp
• Country code such as US
• Optional holiday-calendar subdivision such as a state or region when supported by the holidays package

Temporal semantics

ChronoGuard deliberately distinguishes different meanings of “add time”:

• Minutes / hours: elapsed-time arithmetic. Calculation happens through UTC and converts back to the requested timezone.
• Days / weeks: local calendar arithmetic, preserving wall-clock time across DST changes.
• Business days: local calendar arithmetic that skips weekends and supported official holidays.
• Naive local timestamps: accepted only when they map to one unambiguous real instant. Nonexistent spring-forward times and ambiguous fall-back times are rejected unless an explicit UTC offset is supplied.

Important v0.1 limitation

ChronoGuard currently assumes Saturday and Sunday are weekends for business-day calculations.

The holidays dependency supports many countries and subdivisions, but that does not mean v0.1 correctly models every country's weekend convention, banking calendar, exchange calendar, or company-specific business calendar.

Do not describe v0.1 as universally correct for global business calendars.

Install

Requires Python 3.11+.

python -m pip install -r requirements.txt

Run the tests

From the project root:

python -m pytest -v

Expected result for this release:

28 passed

Inspect the MCP server

fastmcp inspect server.py

A successful inspection should show one registered tool.

Run locally over stdio

python server.py

ChronoGuard currently uses MCP stdio transport for local clients.

Example MCP client call

import asyncio
from fastmcp import Client
from server import mcp


async def main():
    async with Client(mcp) as client:
        result = await client.call_tool(
            "chronoguard_resolve_time",
            {
                "operation": "business_day_offset",
                "timezone": "America/Chicago",
                "reference_timestamp": "2026-09-11T10:00:00",
                "value": 5,
                "country_code": "US",
            },
        )
        print(result.data)


asyncio.run(main())

Expected resolved date:

2026-09-18

Example MCP configuration

For an MCP client that launches local stdio servers, use a configuration shaped like this and replace the path with the absolute location of server.py on your machine:

{
  "mcpServers": {
    "chronoguard": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Depending on the client and Python environment, you may need to use the absolute path to the Python executable for the environment where ChronoGuard's dependencies are installed.

Example response

A successful business-day call returns structured data such as:

{
  "resolved_datetime_iso": "2026-09-18T10:00:00-05:00",
  "timezone": "America/Chicago",
  "day_of_week": "Friday",
  "is_business_day": true,
  "is_holiday": false,
  "holiday_name": null,
  "date_range": null
}

Error behavior

ChronoGuard fails explicitly rather than silently guessing when it encounters inputs such as:

• Invalid IANA timezone names
• Invalid ISO timestamps
• Unsupported holiday calendars
• Nonexistent DST-local times
• Ambiguous DST-local times without an explicit offset

That behavior is intentional: a deterministic agent tool should prefer a clear error to a plausible but wrong date.

What is not in v0.1

Not yet supported:

• Non-Saturday/Sunday weekend conventions
• NYSE or other exchange calendars
• Federal Reserve settlement calendars
• Custom company holiday calendars
• Remote HTTP transport
• Authentication or rate limiting
• Hosted commercial API
• Billing or usage metering

Those should be added only after developer demand justifies them.

Why this exists

The experiment behind ChronoGuard is simple:

When an AI workflow has a narrow deterministic failure mode, move that task out of LLM reasoning and into a small tool with a strict contract.

ChronoGuard is the first test of that idea.

Feedback wanted

This release is intentionally small. Useful feedback includes:

• Where your agent currently gets date/time logic wrong
• Which calendar rules you actually need
• Whether local stdio is enough or remote HTTP matters
• Which operations you expected but did not find
• Whether you would adopt a shared temporal utility instead of maintaining date logic inside each agent