agents-calendar 0.0.3

CalDAV feeler for agents (CLI + MCP).
Stdlib HTTP. The server expands recurrence. Passwords stay on the host.

Quickstart

pip install agents-calendar && agents-calendar sync --init

Merges MCP into host configs. Prints where credentials go. Does not write secrets into mcp.json. init is the same command.

Source checkouts can also be installed and managed with vand.

What it does

List calendars, list events in a time range, add, update, delete. Recurrence rules stay on the CalDAV server (time-range report). Writes send If-None-Match: * on create and If-Match on update and delete, so a stale etag does not clobber.

The password is never printed, logged, or returned by a tool.

Credentials

Highest priority first:

1. Process env: CALDAV_URL, CALDAV_USERNAME, CALDAV_PASSWORD
2. ~/.agents/calendar.json (mode 0600)
3. ~/.agents/.env keys CALDAV_*

{
  "url": "https://example.com/dav/calendars/user/calendar/",
  "username": "user",
  "password": "app-password"
}

CLI and MCP both read this file, so a desktop host does not need the password in its MCP config. A URL that is only a host or principal is resolved through calendar-home-set. add writes into a VEVENT collection, not a reminder collection.

Where it runs

Floor: any MCP client or a terminal. python -m agents_calendar serve is enough. No skills are installed.

MCP without autowire: point the host at python -m agents_calendar serve.

MCP tools

Primary surface. They mirror the CLI. Password never appears in the JSON.

Five tools.

CLI

Machine-readable catalog: python -m agents_calendar --help-json (do not scrape --help).

No subcommand prints help.

ABI

Contract in abi/:

• WHY.md — server-side recurrence and etags
• LAYOUT.md — credential file
• MCP.md — five tools
• CLI.md — the same verbs, plus init

Tests

python -m unittest discover tests

License

MIT. See LICENSE.