@mentu/calendar

Deterministic calendar scheduling for agents. Structured JSON in → structured JSON out. Ships an MCP server and a CLI in one self-contained binary.

• Deterministic — the same input JSON produces byte-identical output JSON.
• Offline & host-independent — no network, no ambient clock (pass now as input), no host time zone. Time zones come from a vendored, pinned IANA release.
• Half-open [start, end) intervals — back-to-back events do not conflict.
• Plans, not writes — mutating operations return plans/diffs; a provider adapter performs any live writes.

Install

npm i -g @mentu/calendar          # global CLI: `calendar`
# …or run without installing:
npx -y @mentu/calendar --mcp

A single prebuilt binary is delivered for your platform (macOS arm64/x64, Linux x64, Windows x64) as an optional dependency — no build step and no runtime dependencies.

MCP server

claude mcp add calendar -- npx -y @mentu/calendar --mcp

Exposes nine tools named calendar_<op> (e.g. calendar_find_slots). Each tool's input schema is the operation's published JSON Schema, and results are the same response envelope as the CLI. Local, offline, deterministic — no network, no state, no ambient clock.

CLI

calendar call find_slots --input request.json     # run an operation (or pipe JSON on stdin)
calendar call check_availability --input req.json
calendar --schema [op]                            # emit JSON request schemas
calendar --self-test                              # deterministic self-check
calendar --version
calendar --mcp                                    # run as a stdio MCP server

Operations: resolve_timezone, check_availability, detect_conflicts, find_slots, create_event_plan, reschedule_event_plan, cancel_event_plan, expand_recurrence, next_occurrence.

Calendar semantics follow RFC 5545; time zones use a vendored, pinned IANA tzdata release.

License

Free to use, including commercially. Redistribution and reverse engineering are not permitted. See LICENSE.