chronoguard

<!-- mcp-name: io.github.kelli930/chronoguard -->

# 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.

## Why ChronoGuard exists

AI agents are good at language, but they should not have to guess deterministic time logic.

Instead of asking a model:

What is 5 US business days after September 11, 2026?

have the agent call ChronoGuard:

{
  "operation": "business_day_offset",
  "timezone": "America/Chicago",
  "reference_timestamp": "2026-09-11T10:00:00",
  "value": 5,
  "country_code": "US"
}

ChronoGuard returns the deterministic result:

{
  "resolved_datetime_iso": "2026-09-18T10:00:00-05:00",
  "day_of_week": "Friday",
  "is_business_day": true,
  "is_holiday": false
}

This removes date arithmetic, holiday logic, timezone conversion, and DST edge cases from the LLM's reasoning path.

## Free vs Paid Use

ChronoGuard is free for evaluation and non-production use.

You may use ChronoGuard for free for personal projects, education, research, demos, prototypes, proof-of-concept work, internal evaluation, and non-production development and testing.

A paid commercial license is required for production business use.

This includes using ChronoGuard:

in a live business workflow
in a production application or service
to support paying customers
inside software you sell
inside a SaaS product
as a hosted or managed service
for ongoing commercial operations

Production use means use in a live system, workflow, product, service, or operational process that supports a business, organization, customer, or revenue-generating activity.

Redistribution, resale, commercial bundling, or offering ChronoGuard as a paid hosted service is not permitted without a separate commercial agreement.

Commercial licensing options will be announced separately.

## 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:

```text
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+.

```bash
python -m pip install -r requirements.txt
```

## Run the tests

From the project root:

```bash
python -m pytest -v
```

Expected result for this release:

```text
28 passed
```

## Inspect the MCP server

```bash
fastmcp inspect server.py
```

A successful inspection should show one registered tool.

## Run locally over stdio

```bash
python server.py
```

ChronoGuard currently uses MCP stdio transport for local clients.

## Example MCP client call

```python
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:

```text
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:

```json
{
  "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:

```json
{
  "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