chronoguard 0.1.1__tar.gz

chronoguard-0.1.1/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: chronoguard
+Version: 0.1.1
+Summary: Deterministic date, time, timezone, holiday, and business-day arithmetic for AI agents via MCP.
+Project-URL: Homepage, https://github.com/kelli930/chronoguard
+Project-URL: Repository, https://github.com/kelli930/chronoguard
+Project-URL: Issues, https://github.com/kelli930/chronoguard/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=4.0.3
+Requires-Dist: holidays>=0.80
+Requires-Dist: python-dateutil>=2.9
+Requires-Dist: pydantic>=2
+
+<!-- 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.
+
+## 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

chronoguard-0.1.1/README.md

@@ -0,0 +1,231 @@
+<!-- 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.
+
+## 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

chronoguard-0.1.1/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chronoguard"
+version = "0.1.1"
+description = "Deterministic date, time, timezone, holiday, and business-day arithmetic for AI agents via MCP."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastmcp>=4.0.3",
+    "holidays>=0.80",
+    "python-dateutil>=2.9",
+    "pydantic>=2"
+]
+
+[project.urls]
+Homepage = "https://github.com/kelli930/chronoguard"
+Repository = "https://github.com/kelli930/chronoguard"
+Issues = "https://github.com/kelli930/chronoguard/issues"
+
+[project.scripts]
+chronoguard = "chronoguard.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

chronoguard-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chronoguard-0.1.1/src/chronoguard/server.py

@@ -0,0 +1,260 @@
+from datetime import datetime, date, timedelta, timezone as dt_timezone
+import zoneinfo
+from typing import Optional, Literal
+
+from pydantic import BaseModel
+import holidays
+from dateutil import parser
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="ChronoGuard")
+
+
+class DateRange(BaseModel):
+    start_iso: str
+    end_iso: str
+
+
+class ChronoGuardResponse(BaseModel):
+    resolved_datetime_iso: str
+    timezone: str
+    day_of_week: str
+    is_business_day: bool
+    is_holiday: bool
+    holiday_name: Optional[str] = None
+    date_range: Optional[DateRange] = None
+
+
+def _get_holiday_calendar(country_code: str, subdiv: Optional[str] = None):
+    """Return a supported holiday calendar or fail explicitly."""
+    try:
+        return holidays.country_holidays(country_code.upper(), subdiv=subdiv)
+    except (NotImplementedError, KeyError, ValueError) as exc:
+        detail = f" country '{country_code}'"
+        if subdiv:
+            detail += f" subdivision '{subdiv}'"
+        raise ValueError(f"Unsupported holiday calendar for{detail}.") from exc
+
+
+def is_workday(
+    target_date: date, country_code: str, subdiv: Optional[str] = None
+) -> tuple[bool, bool, Optional[str]]:
+    """Check business-day status using a Sat/Sun weekend plus official holidays.
+
+    v0.1 intentionally supports only calendars whose weekend is Saturday/Sunday.
+    Holiday status is evaluated even when the holiday falls on a weekend.
+    """
+    country_holidays = _get_holiday_calendar(country_code, subdiv)
+    is_holiday = target_date in country_holidays
+    holiday_name = country_holidays.get(target_date) if is_holiday else None
+    is_weekend = target_date.weekday() >= 5
+    return (not is_weekend and not is_holiday), is_holiday, holiday_name
+
+
+def shift_business_days(
+    start_dt: datetime,
+    offset: int,
+    country_code: str,
+    subdiv: Optional[str] = None,
+) -> datetime:
+    """Offset by N business days while preserving local wall-clock time."""
+    if offset == 0:
+        return start_dt
+
+    step = 1 if offset > 0 else -1
+    remaining = abs(offset)
+    current_dt = start_dt
+
+    while remaining:
+        current_dt += timedelta(days=step)
+        workday, _, _ = is_workday(current_dt.date(), country_code, subdiv)
+        if workday:
+            remaining -= 1
+
+    return current_dt
+
+
+def _validate_naive_local_datetime(parsed_dt: datetime, tz: zoneinfo.ZoneInfo) -> datetime:
+    """Attach tzinfo only when a naive local time maps to exactly one real instant.
+
+    Rejects nonexistent spring-forward times and ambiguous fall-back times rather
+    than silently choosing an interpretation.
+    """
+    candidates: list[datetime] = []
+    for fold in (0, 1):
+        candidate = parsed_dt.replace(tzinfo=tz, fold=fold)
+        roundtrip = candidate.astimezone(dt_timezone.utc).astimezone(tz)
+        if roundtrip.replace(tzinfo=None) == parsed_dt:
+            candidates.append(candidate)
+
+    unique_offsets = {candidate.utcoffset() for candidate in candidates}
+    if not candidates:
+        raise ValueError(
+            f"Local time '{parsed_dt.isoformat()}' does not exist in timezone '{tz.key}' due to a DST transition."
+        )
+    if len(unique_offsets) > 1:
+        raise ValueError(
+            f"Local time '{parsed_dt.isoformat()}' is ambiguous in timezone '{tz.key}' due to a DST transition; provide an explicit UTC offset."
+        )
+    return candidates[0]
+
+
+def _parse_reference(reference_timestamp: Optional[str], tz: zoneinfo.ZoneInfo) -> datetime:
+    if reference_timestamp is None:
+        return datetime.now(tz)
+
+    try:
+        parsed_dt = parser.isoparse(reference_timestamp)
+    except Exception as exc:
+        raise ValueError(f"Could not parse reference_timestamp ISO string: {exc}") from exc
+
+    if parsed_dt.tzinfo is None:
+        return _validate_naive_local_datetime(parsed_dt, tz)
+    return parsed_dt.astimezone(tz)
+
+
+def _apply_amount(
+    base_dt: datetime,
+    value: int,
+    unit: Literal["minutes", "hours", "days", "weeks", "business_days"],
+    country_code: str,
+    subdivision: Optional[str],
+) -> datetime:
+    """Apply a signed amount with explicit temporal semantics.
+
+    minutes/hours = elapsed time (UTC arithmetic)
+    days/weeks = local calendar arithmetic, preserving local wall-clock time
+    business_days = local business-calendar arithmetic
+    """
+    if unit == "minutes":
+        utc_result = base_dt.astimezone(dt_timezone.utc) + timedelta(minutes=value)
+        return utc_result.astimezone(base_dt.tzinfo)
+    if unit == "hours":
+        utc_result = base_dt.astimezone(dt_timezone.utc) + timedelta(hours=value)
+        return utc_result.astimezone(base_dt.tzinfo)
+    if unit == "days":
+        return base_dt + timedelta(days=value)
+    if unit == "weeks":
+        return base_dt + timedelta(weeks=value)
+    if unit == "business_days":
+        return shift_business_days(base_dt, value, country_code, subdivision)
+    raise ValueError(f"Unsupported unit: {unit}")
+
+
+def execute_chronoguard(
+    operation: Literal[
+        "current_time",
+        "add_duration",
+        "subtract_duration",
+        "business_day_offset",
+        "calculate_span",
+    ],
+    timezone: str = "UTC",
+    reference_timestamp: Optional[str] = None,
+    unit: Optional[Literal["minutes", "hours", "days", "weeks", "business_days"]] = None,
+    value: int = 0,
+    country_code: str = "US",
+    subdivision: Optional[str] = None,
+) -> ChronoGuardResponse:
+    try:
+        tz = zoneinfo.ZoneInfo(timezone)
+    except (zoneinfo.ZoneInfoNotFoundError, ValueError) as exc:
+        raise ValueError(
+            f"Invalid IANA timezone string: '{timezone}'. Example: 'America/Chicago' or 'UTC'"
+        ) from exc
+
+    base_dt = _parse_reference(reference_timestamp, tz)
+    resolved_dt = base_dt
+    date_range = None
+
+    if operation == "current_time":
+        pass
+
+    elif operation in ("add_duration", "subtract_duration"):
+        if unit is None:
+            raise ValueError(f"'{operation}' requires 'unit'.")
+        if value <= 0:
+            raise ValueError(f"'{operation}' requires a positive non-zero 'value'.")
+        signed_value = value if operation == "add_duration" else -value
+        resolved_dt = _apply_amount(
+            base_dt, signed_value, unit, country_code, subdivision
+        )
+
+    elif operation == "business_day_offset":
+        resolved_dt = shift_business_days(
+            base_dt, value, country_code, subdivision
+        )
+
+    elif operation == "calculate_span":
+        if unit is None:
+            raise ValueError("'calculate_span' requires 'unit'.")
+        other_end = _apply_amount(
+            base_dt, value, unit, country_code, subdivision
+        )
+        if value < 0:
+            start, end = other_end, base_dt
+        else:
+            start, end = base_dt, other_end
+        date_range = DateRange(start_iso=start.isoformat(), end_iso=end.isoformat())
+        resolved_dt = other_end
+
+    else:
+        raise ValueError(f"Unsupported operation: {operation}")
+
+    workday, is_holiday, holiday_name = is_workday(
+        resolved_dt.date(), country_code, subdivision
+    )
+
+    return ChronoGuardResponse(
+        resolved_datetime_iso=resolved_dt.isoformat(),
+        timezone=timezone,
+        day_of_week=resolved_dt.strftime("%A"),
+        is_business_day=workday,
+        is_holiday=is_holiday,
+        holiday_name=holiday_name,
+        date_range=date_range,
+    )
+
+
+@mcp.tool(
+    name="chronoguard_resolve_time",
+    description=(
+        "Deterministic temporal resolution and business-date arithmetic. "
+        "Use for current time, elapsed or calendar offsets, rolling spans, "
+        "business-day offsets, SLAs, and financial cutoffs. v0.1 business-day "
+        "calendars assume a Saturday/Sunday weekend."
+    ),
+)
+def chronoguard_tool(
+    operation: Literal[
+        "current_time",
+        "add_duration",
+        "subtract_duration",
+        "business_day_offset",
+        "calculate_span",
+    ],
+    timezone: str = "UTC",
+    reference_timestamp: Optional[str] = None,
+    unit: Optional[Literal["minutes", "hours", "days", "weeks", "business_days"]] = None,
+    value: int = 0,
+    country_code: str = "US",
+    subdivision: Optional[str] = None,
+) -> dict:
+    """Resolve and calculate dates deterministically."""
+    return execute_chronoguard(
+        operation=operation,
+        timezone=timezone,
+        reference_timestamp=reference_timestamp,
+        unit=unit,
+        value=value,
+        country_code=country_code,
+        subdivision=subdivision,
+    ).model_dump()
+
+
+def main():
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

chronoguard-0.1.1/src/chronoguard.egg-info/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: chronoguard
+Version: 0.1.1
+Summary: Deterministic date, time, timezone, holiday, and business-day arithmetic for AI agents via MCP.
+Project-URL: Homepage, https://github.com/kelli930/chronoguard
+Project-URL: Repository, https://github.com/kelli930/chronoguard
+Project-URL: Issues, https://github.com/kelli930/chronoguard/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=4.0.3
+Requires-Dist: holidays>=0.80
+Requires-Dist: python-dateutil>=2.9
+Requires-Dist: pydantic>=2
+
+<!-- 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.
+
+## 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

chronoguard-0.1.1/src/chronoguard.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/chronoguard/__init__.py
+src/chronoguard/server.py
+src/chronoguard.egg-info/PKG-INFO
+src/chronoguard.egg-info/SOURCES.txt
+src/chronoguard.egg-info/dependency_links.txt
+src/chronoguard.egg-info/entry_points.txt
+src/chronoguard.egg-info/requires.txt
+src/chronoguard.egg-info/top_level.txt
+tests/test_chronoguard.py

chronoguard-0.1.1/src/chronoguard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

chronoguard-0.1.1/src/chronoguard.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chronoguard = chronoguard.server:main

chronoguard-0.1.1/src/chronoguard.egg-info/requires.txt

@@ -0,0 +1,4 @@
+fastmcp>=4.0.3
+holidays>=0.80
+python-dateutil>=2.9
+pydantic>=2

chronoguard-0.1.1/src/chronoguard.egg-info/top_level.txt

@@ -0,0 +1 @@
+chronoguard

chronoguard-0.1.1/tests/test_chronoguard.py

@@ -0,0 +1,325 @@
+import pytest
+from datetime import datetime
+
+from chronoguard.server import execute_chronoguard
+import asyncio
+import os
+from pathlib import Path
+import sys
+import fastmcp
+from fastmcp import Client
+from fastmcp.client.transports import StdioTransport
+from chronoguard.server import execute_chronoguard, mcp
+
+
+def iso(res):
+    return datetime.fromisoformat(res.resolved_datetime_iso)
+
+
+def test_weekend_skipping_forward():
+    res = execute_chronoguard(
+        operation="business_day_offset",
+        reference_timestamp="2026-09-11T09:00:00Z",
+        value=1,
+        timezone="UTC",
+    )
+    assert res.day_of_week == "Monday"
+    assert res.is_business_day is True
+    assert iso(res).date().isoformat() == "2026-09-14"
+
+
+def test_weekend_skipping_backward():
+    res = execute_chronoguard(
+        operation="business_day_offset",
+        reference_timestamp="2026-09-14T09:00:00Z",
+        value=-1,
+        timezone="UTC",
+    )
+    assert iso(res).date().isoformat() == "2026-09-11"
+
+
+def test_us_labor_day_skipped():
+    res = execute_chronoguard(
+        operation="business_day_offset",
+        reference_timestamp="2026-09-04T12:00:00",
+        value=1,
+        country_code="US",
+        timezone="America/New_York",
+    )
+    assert res.day_of_week == "Tuesday"
+    assert iso(res).date().isoformat() == "2026-09-08"
+
+
+def test_holiday_metadata_on_weekday():
+    res = execute_chronoguard(
+        operation="current_time",
+        reference_timestamp="2026-07-03T12:00:00",
+        country_code="US",
+        timezone="America/New_York",
+    )
+    assert res.is_holiday is True
+    assert res.is_business_day is False
+    assert res.holiday_name
+
+
+def test_holiday_metadata_even_when_on_weekend():
+    res = execute_chronoguard(
+        operation="current_time",
+        reference_timestamp="2027-12-25T12:00:00",
+        country_code="US",
+        timezone="America/New_York",
+    )
+    assert res.is_holiday is True
+    assert res.is_business_day is False
+    assert "Christmas" in res.holiday_name
+
+@pytest.mark.parametrize(
+    ("country_code", "reference_timestamp", "holiday_fragment"),
+    [
+        ("US", "2026-07-04T12:00:00", "Independence"),
+        ("CA", "2026-07-01T12:00:00", "Canada Day"),
+        ("GB", "2026-12-25T12:00:00", "Christmas"),
+    ],
+)
+def test_supported_country_holiday_calendars(country_code, reference_timestamp, holiday_fragment):
+    res = execute_chronoguard(
+        operation="current_time",
+        reference_timestamp=reference_timestamp,
+        timezone="UTC",
+        country_code=country_code,
+    )
+    assert res.is_holiday is True
+    assert res.is_business_day is False
+    assert res.holiday_name and holiday_fragment in res.holiday_name
+def test_rolling_span_days_past():
+    res = execute_chronoguard(
+        operation="calculate_span",
+        reference_timestamp="2026-09-11T12:00:00Z",
+        value=-30,
+        unit="days",
+        timezone="UTC",
+    )
+    assert res.date_range is not None
+    assert res.date_range.start_iso.startswith("2026-08-12")
+    assert res.date_range.end_iso.startswith("2026-09-11")
+
+
+def test_rolling_span_minutes_is_minutes_not_days():
+    res = execute_chronoguard(
+        operation="calculate_span",
+        reference_timestamp="2026-09-11T12:00:00Z",
+        value=-30,
+        unit="minutes",
+        timezone="UTC",
+    )
+    assert res.date_range.start_iso.startswith("2026-09-11T11:30:00")
+
+
+def test_rolling_span_business_days():
+    res = execute_chronoguard(
+        operation="calculate_span",
+        reference_timestamp="2026-09-11T12:00:00-04:00",
+        value=-4,
+        unit="business_days",
+        timezone="America/New_York",
+        country_code="US",
+    )
+    # Fri Sep 11 back four business days crosses Labor Day Sep 7.
+    assert res.date_range.start_iso.startswith("2026-09-04T12:00:00")
+
+
+def test_add_elapsed_hours_across_spring_dst():
+    res = execute_chronoguard(
+        operation="add_duration",
+        reference_timestamp="2026-03-08T01:30:00-06:00",
+        value=2,
+        unit="hours",
+        timezone="America/Chicago",
+    )
+    # Two elapsed hours after 01:30 CST is 04:30 CDT.
+    assert res.resolved_datetime_iso.startswith("2026-03-08T04:30:00-05:00")
+
+
+def test_add_calendar_day_preserves_wall_clock_across_spring_dst():
+    res = execute_chronoguard(
+        operation="add_duration",
+        reference_timestamp="2026-03-07T12:00:00-06:00",
+        value=1,
+        unit="days",
+        timezone="America/Chicago",
+    )
+    assert res.resolved_datetime_iso.startswith("2026-03-08T12:00:00-05:00")
+
+
+def test_reject_nonexistent_naive_dst_time():
+    with pytest.raises(ValueError, match="does not exist"):
+        execute_chronoguard(
+            operation="current_time",
+            reference_timestamp="2026-03-08T02:30:00",
+            timezone="America/Chicago",
+        )
+
+
+def test_reject_ambiguous_naive_dst_time():
+    with pytest.raises(ValueError, match="ambiguous"):
+        execute_chronoguard(
+            operation="current_time",
+            reference_timestamp="2026-11-01T01:30:00",
+            timezone="America/Chicago",
+        )
+
+
+def test_explicit_offset_disambiguates_fall_dst_time():
+    res = execute_chronoguard(
+        operation="current_time",
+        reference_timestamp="2026-11-01T01:30:00-05:00",
+        timezone="America/Chicago",
+    )
+    assert res.resolved_datetime_iso.startswith("2026-11-01T01:30:00-05:00")
+
+
+def test_timezone_conversion_can_change_date():
+    res = execute_chronoguard(
+        operation="current_time",
+        reference_timestamp="2026-09-11T01:00:00Z",
+        timezone="America/Los_Angeles",
+    )
+    assert res.resolved_datetime_iso.startswith("2026-09-10T18:00:00-07:00")
+    assert res.day_of_week == "Thursday"
+
+
+def test_invalid_timezone_rejected():
+    with pytest.raises(ValueError, match="Invalid IANA timezone"):
+        execute_chronoguard(operation="current_time", timezone="Mars/Olympus_Mons")
+
+
+def test_invalid_timestamp_rejected():
+    with pytest.raises(ValueError, match="Could not parse"):
+        execute_chronoguard(
+            operation="current_time",
+            reference_timestamp="definitely-not-a-date",
+            timezone="UTC",
+        )
+
+
+def test_unsupported_country_rejected():
+    with pytest.raises(ValueError, match="Unsupported holiday calendar"):
+        execute_chronoguard(
+            operation="current_time",
+            reference_timestamp="2026-09-11T12:00:00Z",
+            country_code="ZZ",
+            timezone="UTC",
+        )
+
+
+def test_subdivision_holiday_new_york():
+    # Election Day is recognized by the US-NY holidays calendar in applicable years.
+    res = execute_chronoguard(
+        operation="current_time",
+        reference_timestamp="2026-11-03T12:00:00",
+        timezone="America/New_York",
+        country_code="US",
+        subdivision="NY",
+    )
+    # This assertion intentionally only validates that a subdivision calendar executes.
+    assert res.timezone == "America/New_York"
+
+
+def test_zero_business_day_offset_returns_reference():
+    res = execute_chronoguard(
+        operation="business_day_offset",
+        reference_timestamp="2026-09-12T12:00:00Z",
+        value=0,
+        timezone="UTC",
+    )
+    assert res.resolved_datetime_iso.startswith("2026-09-12T12:00:00+00:00")
+    assert res.is_business_day is False
+
+
+@pytest.mark.parametrize(
+    "operation",
+    ["add_duration", "subtract_duration"],
+)
+def test_duration_requires_positive_value(operation):
+    with pytest.raises(ValueError, match="positive non-zero"):
+        execute_chronoguard(
+            operation=operation,
+            reference_timestamp="2026-09-11T12:00:00Z",
+            unit="hours",
+            value=0,
+            timezone="UTC",
+        )
+
+
+def test_subtract_duration():
+    res = execute_chronoguard(
+        operation="subtract_duration",
+        reference_timestamp="2026-09-11T12:00:00Z",
+        unit="hours",
+        value=3,
+        timezone="UTC",
+    )
+    assert res.resolved_datetime_iso.startswith("2026-09-11T09:00:00+00:00")
+
+
+def test_business_day_offset_preserves_time():
+    res = execute_chronoguard(
+        operation="business_day_offset",
+        reference_timestamp="2026-09-11T15:45:12-04:00",
+        value=1,
+        timezone="America/New_York",
+        country_code="US",
+    )
+    dt = iso(res)
+    assert (dt.hour, dt.minute, dt.second) == (15, 45, 12)
+
+
+def test_round_trip_business_days_from_business_date():
+    start = "2026-09-09T10:00:00-04:00"
+    forward = execute_chronoguard(
+        operation="business_day_offset",
+        reference_timestamp=start,
+        value=8,
+        timezone="America/New_York",
+        country_code="US",
+    )
+    backward = execute_chronoguard(
+        operation="business_day_offset",
+        reference_timestamp=forward.resolved_datetime_iso,
+        value=-8,
+        timezone="America/New_York",
+        country_code="US",
+    )
+    assert backward.resolved_datetime_iso.startswith("2026-09-09T10:00:00")
+
+def test_fastmcp_client_discovers_and_invokes_tool():
+    async def exercise_mcp():
+        site_packages = str(Path(fastmcp.__file__).resolve().parent.parent)
+        python_path = os.pathsep.join(
+            path for path in (site_packages, os.environ.get("PYTHONPATH")) if path
+        )
+        transport = StdioTransport(
+            command=sys.executable,
+            args=[str(Path(__file__).resolve().parents[1] / "src" / "chronoguard" / "server.py")],
+            env={**os.environ, "PYTHONPATH": python_path},
+        )
+        async with Client(transport) as client:
+            tools = await client.list_tools()
+            result = await client.call_tool(
+                "chronoguard_resolve_time",
+                {
+                    "operation": "current_time",
+                    "reference_timestamp": "2026-07-01T12:00:00",
+                    "timezone": "UTC",
+                    "country_code": "CA",
+                },
+            )
+            return tools, result
+
+    tools, result = asyncio.run(exercise_mcp())
+    assert any(tool.name == "chronoguard_resolve_time" for tool in tools)
+    assert result.is_error is False
+    payload = result.structured_content
+    assert payload is not None
+    assert payload["is_holiday"] is True
+    assert payload["holiday_name"] == "Canada Day"