Metadata-Version: 2.5
Name: ical-mcp
Version: 0.2.2
Summary: macOS Calendar.app CLI and MCP server — list calendars, schedule events, invite attendees
Project-URL: Homepage, https://github.com/ml-lubich/ical
Project-URL: Repository, https://github.com/ml-lubich/ical
Project-URL: Issues, https://github.com/ml-lubich/ical/issues
License-Expression: MIT
License-File: LICENSE
Keywords: applescript,calendar,cli,macos,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# ical CLI

macOS Calendar.app CLI tool — schedule, invite, list, and verify calendar events.

## Install
```bash
uv tool install --python 3.14 ical-mcp
# or, with Python 3.10 or newer
pip install ical-mcp
# or
brew install ml-lubich/tap/ical
```

From a checkout:

```bash
uv tool install --editable .
```

The PyPI distribution is named `ical-mcp`. It installs the `ical` Typer CLI
and the standalone `ical-mcp` stdio server; `ical mcp` remains a compatibility
alias for the server command.

## Usage
```bash
ical -h
ical agent -h
ical calendars
ical add --title "Team Sync" --start "Monday, August 10, 2026 at 1:00:00 PM" --end "Monday, August 10, 2026 at 2:00:00 PM" -a guest@example.com -c you@example.com
ical add --title "Team Sync" --start "Monday, August 10, 2026 at 1:00:00 PM" --end "Monday, August 10, 2026 at 2:00:00 PM" -a guest@example.com -c you@example.com --json
ical show --id EVENT_ID --calendar you@example.com --json
ical list -c you@example.com
ical list -c you@example.com -j
```

Every command and command group accepts both `-h` and `--help`; generated
shell-completion flags are disabled so help lists the supported command
surface. `ical list` prints a human-readable table; `-j`/`--json` prints JSON
to stdout. `ical add` verifies the created event by reading it back from
Calendar before reporting success. Human output summarizes the verified event
and attendee RSVP status. With `--json`, it returns a stable object with
`status: "verified"` and an `event` containing the event ID, title, ISO 8601
start and end, calendar, and attendees (`email` and `status`). A post-write verification
failure reports `status: "created_unverified"`, along with the event ID and
error. `unknown` RSVP status means
Calendar has no recorded response from that attendee yet; it does not mean
they accepted. CLI errors are printed to stderr and return a nonzero exit
status.

Every Calendar AppleScript call has a 20-second timeout. Calendar failures,
timeouts, and failed event lookups are reported as errors; `ical list` does not
turn an automation failure into an empty calendar. If creation times out
before Calendar returns an ID, JSON reports `status: "write_outcome_unknown"`
and an error. Search for the event with `ical list` before retrying. If the
conflict check times out before creation starts, JSON reports
`status: "not_created"`; it is safe to retry after Calendar responds. If an ID
is available but read-back failed, use `ical show --id EVENT_ID --calendar
CALENDAR --json` to verify it. **Do not retry the add until confirming the
event is absent**, or you may send a duplicate invitation. `ical show` is
read-only and returns the same verified event envelope as `ical add`. A JSON
lookup failure returns `status: "verification_failed"`, the requested event
ID, and the error; retry the read after checking Calendar, never the add.

## MCP (for AI agents)
`ical-mcp` is the standalone FastMCP server command for stdio clients. It exposes `list_calendars`, `list_events`, and `add_calendar_event`. The backward-compatible `ical mcp` command runs the same server. Point any MCP-compatible client (Claude Desktop, Claude Code, etc.) at the standalone executable:
```json
{
  "mcpServers": {
    "ical": {
      "command": "ical-mcp"
    }
  }
}
```
If `ical-mcp` isn't on `PATH`, use its absolute path from `uv tool dir --bin`. Existing MCP configs using `ical` with `args: ["mcp"]` continue to work.

macOS Calendar's AppleScript scripting bridge can be slow for calendars with
many recurring events. Calls now stop after the bounded timeout and return an
actionable error instead of appearing to hang indefinitely.

## Testing
```bash
uv run --extra dev pytest
```
The default test command reports coverage and enforces an 80% minimum. Tests mock only the OS boundary (`subprocess`/`osascript`); parsing, conflict detection, CLI dispatch, and MCP tool functions run for real.
