ical-mcp 0.2.2__py3-none-any.whl

ical/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.2"

ical/agent.py

@@ -0,0 +1,108 @@
+import json
+
+def build_schema() -> dict:
+    return {
+        "name": "ical",
+        "description": "macOS Calendar.app CLI and MCP tool with bounded operations and verified invite creation",
+        "apple_script_timeout_seconds": 20,
+        "commands": {
+            "calendars": {
+                "description": "List available calendars",
+                "args": []
+            },
+            "list": {
+                "description": "List events in a calendar; Calendar automation errors are reported, never returned as an empty calendar",
+                "flags": {
+                    "--calendar": "Calendar name (default: Calendar)",
+                    "--json": "Output JSON"
+                }
+            },
+            "show": {
+                "description": "Read one event by Calendar ID, including invitee RSVP status; use to verify an uncertain write",
+                "flags": {
+                    "--id": "Calendar event ID (required)",
+                    "--calendar": "Calendar name containing the event (default: Calendar)",
+                    "--json": "Return a machine-readable verified result"
+                }
+            },
+            "add": {
+                "description": "Create an event, check for conflicts, invite attendees, then read the event back by ID before reporting success",
+                "flags": {
+                    "--title": "Event title (required)",
+                    "--start": "Start time string (required)",
+                    "--end": "End time string (required)",
+                    "--calendar": "Calendar name",
+                    "--attendee": "Email address of attendee (repeatable)",
+                    "--description": "Event description",
+                    "--location": "Event location",
+                    "--no-check-conflict": "Disable conflict detection",
+                    "--json": "Return a machine-readable verified result"
+                }
+            },
+            "mcp": {
+                "description": "Run FastMCP stdio server"
+            }
+        },
+        "add_result": {
+            "status": ["verified", "created_unverified", "write_outcome_unknown", "not_created"],
+            "event": {
+                "fields": ["id", "title", "start", "end", "calendar", "attendees"],
+                "start": "ISO 8601 string",
+                "end": "ISO 8601 string",
+                "attendees": {"fields": ["email", "status"], "status_values": ["accepted", "declined", "tentative", "unknown"]}
+            },
+            "unverified_fields": ["status", "id", "error"],
+            "write_outcome_unknown_fields": ["status", "error"],
+            "not_created_fields": ["status", "stage", "error"],
+            "show_result": {
+                "success": {"status": "verified", "event": "same event object as add"},
+                "failure": {"status": "verification_failed", "id": "requested event ID", "error": "reason"}
+            },
+            "note": "Calendar attendee status describes RSVP state. An unknown status means no response is recorded; it does not mean accepted. created_unverified means the write may have succeeded but read-back failed; preserve its ID and check with `ical show`. write_outcome_unknown means event creation timed out before its ID was returned; search the calendar with `ical list` before retrying."
+        },
+        "errors": {
+            "timeout": "Calendar automation exceeded its bounded timeout. The outcome of a write may be uncertain.",
+            "created_unverified": "The event may have been created, but read-back did not confirm it. Preserve the event ID and inspect Calendar before retrying.",
+            "write_outcome_unknown": "Event creation timed out before an ID was returned. The write may have succeeded. Search with `ical list`; do not retry until you confirm the event is absent.",
+            "not_created": "The conflict check timed out before the event write began. No event was created; retry after Calendar responds.",
+            "verification_failed": "Read-only event lookup failed. The CLI returns the event ID and error; check Calendar and retry the read, not the create.",
+            "conflict": "An overlapping event was found; no event was created.",
+            "calendar_error": "Calendar automation failed. The CLI returns a nonzero exit status and writes the error to stderr."
+        },
+        "retry_policy": "After write_outcome_unknown, use `ical list` to search for the event. After created_unverified, use `ical show --id ID --calendar CALENDAR`. Do not retry either write until confirming the event is absent. A not_created conflict-check timeout is safe to retry after Calendar responds."
+    }
+
+def build_guide() -> str:
+    return """# ical Agent Guide
+
+`ical` is an LLM-native CLI tool for macOS Calendar.app.
+
+## Common Operations:
+- List calendars: `ical calendars`
+- List events in calendar: `ical list -c you@example.com --json`
+- Read one event by its Calendar ID: `ical show --id EVENT_ID --calendar you@example.com --json`
+- Add and verify an event with conflict check & invites:
+  `ical add -t "Meeting" -s "Monday, August 10, 2026 at 1:00 PM" -e "Monday, August 10, 2026 at 2:00 PM" -c "you@example.com" -a "user@example.com"`
+- Get a machine-readable verified result:
+  `ical add -t "Meeting" -s "Monday, August 10, 2026 at 1:00 PM" -e "Monday, August 10, 2026 at 2:00 PM" -c "you@example.com" -a "user@example.com" --json`
+- Launch FastMCP stdio server for tool calling: `ical-mcp`
+- Compatibility alias: `ical mcp`
+
+`ical add` only reports verified success after reading the created event back
+by its Calendar ID. The JSON success object has `status: "verified"` and an
+`event` with `id`, `title`, ISO 8601 `start` and `end`, `calendar`, and
+`attendees`; each attendee has an `email` and RSVP `status`. An `unknown` RSVP means no response
+has been recorded, not that the invite was accepted.
+
+Calendar automation calls have a 20-second timeout. If the conflict check times
+out, `ical add` returns `not_created`; no event write was attempted, so retry
+after Calendar responds. If the create write times out before
+Calendar returns an event ID, JSON reports `status: "write_outcome_unknown"`
+with an error. Search with `ical list` before retrying. If creation returns an
+ID but read-back fails, the result is `created_unverified`; inspect it with
+`ical show --id EVENT_ID --calendar CALENDAR`. **Do not retry either write
+until confirming the event is absent**, to avoid a duplicate invite. `ical
+show` is read-only and returns the same verified event envelope as `ical add`.
+Calendar read failures are errors rather than empty event lists. See `ical
+agent schema` for the machine-readable result and error contract.
+"""

ical/calendar.py

@@ -0,0 +1,200 @@
+import subprocess
+import datetime
+from dateutil import parser
+from typing import List, Dict, Any, Optional
+
+
+APPLE_SCRIPT_TIMEOUT_SECONDS = 20
+
+
+class CalendarAutomationError(RuntimeError):
+    """Calendar.app automation returned an error."""
+
+
+class CalendarTimeoutError(CalendarAutomationError):
+    """Calendar.app did not respond within the bounded operation time."""
+
+    def __init__(self, message: str, *, write_may_have_succeeded: bool = False):
+        super().__init__(message)
+        self.write_may_have_succeeded = write_may_have_succeeded
+
+
+class EventNotFoundError(CalendarAutomationError):
+    """No event with the requested ID exists in the selected calendar."""
+
+def _escape_applescript(s: str) -> str:
+    """Escape backslashes and double quotes so a value can be safely embedded
+    inside a double-quoted AppleScript string literal."""
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+def run_applescript(
+    script: str,
+    operation: str = "Calendar operation",
+    *,
+    write_may_have_succeeded: bool = False,
+) -> str:
+    try:
+        res = subprocess.run(
+            ["osascript", "-e", script],
+            capture_output=True,
+            text=True,
+            timeout=APPLE_SCRIPT_TIMEOUT_SECONDS,
+        )
+    except subprocess.TimeoutExpired as err:
+        raise CalendarTimeoutError(
+            f"{operation} timed out after {APPLE_SCRIPT_TIMEOUT_SECONDS}s. "
+            "Calendar may still be processing; check the calendar before retrying.",
+            write_may_have_succeeded=write_may_have_succeeded,
+        ) from err
+    if res.returncode != 0:
+        detail = res.stderr.strip() or "Calendar.app returned an unspecified AppleScript error"
+        raise CalendarAutomationError(f"{operation} failed: {detail}")
+    return res.stdout.strip()
+
+def parse_date(date_str: str) -> datetime.datetime:
+    return parser.parse(date_str)
+
+def get_events(calendar: str = "Calendar") -> List[Dict[str, Any]]:
+    # Bulk-fetch each property across all events in one Apple Event call each
+    # (summary of every event / start date of every event / ...) instead of
+    # looping "repeat with e in evts" and querying properties per-event.
+    # The per-event loop round-trips to Calendar.app 2-3x per event and is
+    # catastrophically slow (multi-second-per-event, effectively hangs) on
+    # any calendar with more than a handful of events - a well-known macOS
+    # Calendar AppleScript scripting-bridge performance bug.
+    script = f'''
+    tell application "Calendar"
+        tell calendar "{_escape_applescript(calendar)}"
+            set summaries to summary of every event
+            set starts to start date of every event
+            set ends to end date of every event
+        end tell
+    end tell
+    set res to ""
+    repeat with i from 1 to (count of summaries)
+        set res to res & (item i of summaries) & " | " & ((item i of starts) as string) & " | " & ((item i of ends) as string) & "\n"
+    end repeat
+    return res
+    '''
+    output = run_applescript(script, operation=f"Reading events from calendar {calendar!r}")
+    events = []
+    for line in output.splitlines():
+        if line.strip():
+            parts = line.split(" | ")
+            if len(parts) == 3:
+                try:
+                    start_dt = parse_date(parts[1])
+                    end_dt = parse_date(parts[2])
+                    events.append({
+                        "title": parts[0],
+                        "start": start_dt,
+                        "end": end_dt,
+                        "start_str": parts[1],
+                        "end_str": parts[2]
+                    })
+                except (ValueError, OverflowError):
+                    continue
+    return events
+
+
+def get_event_details(calendar: str, event_id: str) -> Dict[str, Any]:
+    """Read one event by ID, including invitee participation when available."""
+    separator = "ASCII character 31"
+    script = f'''
+    tell application "Calendar"
+        tell calendar "{_escape_applescript(calendar)}"
+            set matchingEvents to every event whose id is "{_escape_applescript(event_id)}"
+            if (count of matchingEvents) is 0 then return ""
+            set targetEvent to item 1 of matchingEvents
+            set fields to {{id of targetEvent as text, summary of targetEvent as text, ¬
+                start date of targetEvent as text, end date of targetEvent as text}}
+            set resultText to ""
+            repeat with fieldValue in fields
+                if resultText is not "" then set resultText to resultText & linefeed
+                set resultText to resultText & (contents of fieldValue)
+            end repeat
+            repeat with guest in attendees of targetEvent
+                set resultText to resultText & linefeed & (email of guest as text) & {separator} & ¬
+                    (participation status of guest as text)
+            end repeat
+            return resultText
+        end tell
+    end tell
+    '''
+    output = run_applescript(script, operation=f"Verifying event {event_id!r}")
+    lines = output.splitlines()
+    if len(lines) < 4:
+        raise EventNotFoundError(
+            f"Event {event_id!r} was not found in calendar {calendar!r}."
+        )
+    try:
+        start_dt = parse_date(lines[2])
+        end_dt = parse_date(lines[3])
+    except (ValueError, OverflowError) as err:
+        raise CalendarAutomationError(
+            f"Calendar returned invalid dates while verifying event {event_id!r}."
+        ) from err
+    attendees = []
+    for line in lines[4:]:
+        if chr(31) not in line:
+            continue
+        email, status = line.split(chr(31), 1)
+        attendees.append({"email": email, "status": status})
+    return {
+        "id": lines[0],
+        "title": lines[1],
+        "start": start_dt,
+        "end": end_dt,
+        "start_str": lines[2],
+        "end_str": lines[3],
+        "calendar": calendar,
+        "attendees": attendees,
+    }
+
+def check_conflicts(calendar: str, start_dt: datetime.datetime, end_dt: datetime.datetime) -> List[Dict[str, Any]]:
+    existing = get_events(calendar)
+    conflicts = []
+    for evt in existing:
+        # Check overlap: start1 < end2 and start2 < end1
+        if evt["start"] < end_dt and start_dt < evt["end"]:
+            conflicts.append(evt)
+    return conflicts
+
+def add_event(
+    title: str,
+    start: str,
+    end: str,
+    calendar: str = "Calendar",
+    attendee: Optional[List[str]] = None,
+    description: str = "",
+    location: str = "",
+    check_conflict: bool = True
+) -> Dict[str, Any]:
+    start_dt = parse_date(start)
+    end_dt = parse_date(end)
+    
+    if check_conflict:
+        conflicts = check_conflicts(calendar, start_dt, end_dt)
+        if conflicts:
+            conflict_titles = ", ".join([c["title"] for c in conflicts])
+            raise ValueError(f"Conflict detected with existing event(s): {conflict_titles}")
+            
+    attendee_script = ""
+    if attendee:
+        for email in attendee:
+            attendee_script += f'\n\t\t\tmake new attendee at end of attendees of newEvt with properties {{email:"{_escape_applescript(email)}"}}'
+
+    script = f'''
+    tell application "Calendar"
+        tell calendar "{_escape_applescript(calendar)}"
+            set newEvt to make new event with properties {{summary:"{_escape_applescript(title)}", start date:date "{start}", end date:date "{end}", description:"{_escape_applescript(description)}", location:"{_escape_applescript(location)}"}}{attendee_script}
+            return id of newEvt
+        end tell
+    end tell
+    '''
+    event_id = run_applescript(
+        script,
+        operation=f"Creating event {title!r}",
+        write_may_have_succeeded=True,
+    )
+    return {"id": event_id, "title": title, "start": start, "end": end, "calendar": calendar}

ical/cli.py

@@ -0,0 +1,257 @@
+"""Command line interface for macOS Calendar.app."""
+
+import json
+import sys
+import datetime
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ical import __version__
+
+EPILOG = """\
+Examples:
+
+  ical calendars
+  ical list --calendar "you@example.com" --json
+  ical add --title "Mock Interview" --start "Monday, Aug 10, 2026 at 1:00 PM" --end "Monday, Aug 10, 2026 at 2:00 PM" -a user@example.com
+  ical-mcp
+
+`ical mcp` remains a compatibility alias for `ical-mcp`.
+Agents: run `ical agent guide` for a playbook, `ical agent schema` for JSON contract.
+"""
+
+app = typer.Typer(
+    name="ical",
+    help="macOS Calendar.app CLI and MCP server.",
+    epilog=EPILOG,
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+agent_app = typer.Typer(
+    name="agent",
+    help="Show the machine-readable schema and playbook.",
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+app.add_typer(agent_app, name="agent")
+
+console = Console()
+
+
+def _event_json(event: dict) -> dict:
+    """Return the stable, machine-readable fields shared by add and show."""
+    return {
+        key: value.isoformat() if isinstance(value, datetime.datetime) else value
+        for key, value in event.items()
+        if key in {"id", "title", "start", "end", "calendar", "attendees"}
+    }
+
+
+def _print_event(event: dict, label: str) -> None:
+    start_text = event.get("start_str", str(event["start"]))
+    end_text = event.get("end_str", str(event["end"]))
+    console.print(
+        f"[bold green]{label}.[/bold green] "
+        f"{event['title']} — {start_text} to {end_text} ([cyan]{event['calendar']}[/cyan])"
+    )
+    attendees = event.get("attendees", [])
+    if attendees:
+        for guest in attendees:
+            status = guest.get("status") or "status unavailable"
+            console.print(f"  Invitee: {guest['email']} ({status})")
+    else:
+        console.print("  Invitees: none")
+    console.print(f"  ID: {event['id']}")
+
+
+@app.command("calendars")
+def list_calendars() -> None:
+    """List available calendars in Calendar.app."""
+    from ical.calendar import run_applescript
+
+    try:
+        calendars = run_applescript(
+            'tell application "Calendar" to get name of calendars'
+        ).split(", ")
+    except Exception as err:
+        typer.echo(f"Error listing calendars: {err}", err=True)
+        raise typer.Exit(code=1) from err
+
+    table = Table(title="Calendars")
+    table.add_column("Name", style="cyan")
+    for calendar in calendars:
+        table.add_row(calendar)
+    console.print(table)
+
+
+@app.command("add")
+def add_event(
+    title: Annotated[str, typer.Option("--title", "-t", help="Event title")],
+    start: Annotated[str, typer.Option("--start", "-s", help="Start date and time")],
+    end: Annotated[str, typer.Option("--end", "-e", help="End date and time")],
+    calendar: Annotated[str, typer.Option("--calendar", "-c", help="Calendar name")] = "Calendar",
+    attendee: Annotated[list[str] | None, typer.Option("--attendee", "-a", help="Attendee email; repeat for multiple attendees")] = None,
+    description: Annotated[str, typer.Option("--description", "-d", help="Event description")] = "",
+    location: Annotated[str, typer.Option("--location", "-l", help="Event location")] = "",
+    check_conflict: Annotated[bool, typer.Option("--check-conflict/--no-check-conflict", help="Check for overlapping events")] = True,
+    as_json: Annotated[bool, typer.Option("--json", "-j", help="Emit verified event as JSON")] = False,
+) -> None:
+    """Create an event, invite attendees, and verify it was saved."""
+    from ical.calendar import CalendarTimeoutError, add_event as core_add_event, get_event_details
+
+    try:
+        result = core_add_event(
+            title=title,
+            start=start,
+            end=end,
+            calendar=calendar,
+            attendee=attendee,
+            description=description,
+            location=location,
+            check_conflict=check_conflict,
+        )
+    except CalendarTimeoutError as err:
+        if err.write_may_have_succeeded:
+            status = "write_outcome_unknown"
+            details = {"status": status, "error": str(err)}
+            message = (
+                "Create request timed out; the write outcome is unknown. "
+                "Do not retry yet. Check Calendar.app for the event first. "
+                f"Details: {err}"
+            )
+        else:
+            status = "not_created"
+            details = {"status": status, "stage": "conflict_check", "error": str(err)}
+            message = (
+                "Calendar conflict check timed out. No event was created. "
+                "You can retry after Calendar responds. "
+                f"Details: {err}"
+            )
+        if as_json:
+            typer.echo(json.dumps(details))
+        else:
+            typer.echo(message, err=True)
+        raise typer.Exit(code=1) from err
+    except (ValueError, RuntimeError) as err:
+        typer.echo(f"Could not create event: {err}", err=True)
+        raise typer.Exit(code=1) from err
+    except Exception as err:
+        typer.echo(f"Unexpected error creating event: {err}", err=True)
+        raise typer.Exit(code=1) from err
+
+    # The create call may have succeeded even if Calendar.app stops responding
+    # during read-back. Never repeat the write automatically in that case.
+    try:
+        event = get_event_details(calendar, result["id"])
+    except Exception as err:
+        message = (
+            f"Event was created, but verification failed (ID: {result['id']}). "
+            f"Do not retry add; verify it with `ical show --id {result['id']} "
+            f"--calendar {calendar}`. Details: {err}"
+        )
+        if as_json:
+            typer.echo(json.dumps({"status": "created_unverified", "id": result["id"], "error": str(err)}))
+        else:
+            typer.echo(message, err=True)
+        raise typer.Exit(code=1) from err
+
+    if as_json:
+        typer.echo(json.dumps({"status": "verified", "event": _event_json(event)}, ensure_ascii=False))
+        return
+
+    _print_event(event, "Event created and verified")
+
+
+@app.command("show")
+def show_event(
+    event_id: Annotated[str, typer.Option("--id", help="Event ID returned by `ical add`")],
+    calendar: Annotated[str, typer.Option("--calendar", "-c", help="Calendar name")] = "Calendar",
+    as_json: Annotated[bool, typer.Option("--json", "-j", help="Emit verified event as JSON")] = False,
+) -> None:
+    """Read and verify one existing event by ID."""
+    from ical.calendar import get_event_details
+
+    try:
+        event = get_event_details(calendar, event_id)
+    except Exception as err:
+        if as_json:
+            typer.echo(json.dumps({"status": "verification_failed", "id": event_id, "error": str(err)}))
+        else:
+            typer.echo(f"Could not verify event {event_id!r}: {err}", err=True)
+        raise typer.Exit(code=1) from err
+
+    if as_json:
+        typer.echo(json.dumps({"status": "verified", "event": _event_json(event)}, ensure_ascii=False))
+        return
+    _print_event(event, "Event verified")
+
+
+@app.command("list")
+def list_events(
+    calendar: Annotated[str, typer.Option("--calendar", "-c", help="Calendar name")] = "Calendar",
+    as_json: Annotated[bool, typer.Option("--json", "-j", help="Emit JSON output")] = False,
+) -> None:
+    """List events in a calendar."""
+    from ical.calendar import get_events
+
+    try:
+        events = get_events(calendar)
+        json_events = [
+            {"title": event["title"], "start": event["start_str"], "end": event["end_str"]}
+            for event in events
+        ]
+        if as_json:
+            typer.echo(json.dumps({"calendar": calendar, "events": json_events}, ensure_ascii=False))
+            return
+
+        table = Table(title=f"Events in {calendar}")
+        table.add_column("Title", style="bold white")
+        table.add_column("Start", style="green")
+        table.add_column("End", style="yellow")
+        for event in events:
+            table.add_row(event["title"], event["start_str"], event["end_str"])
+        console.print(table)
+    except Exception as err:
+        typer.echo(f"Error listing events: {err}", err=True)
+        raise typer.Exit(code=1) from err
+
+
+@app.command("mcp")
+def serve_mcp() -> None:
+    """Run the FastMCP server over stdio."""
+    from ical.mcp import run_server
+
+    run_server()
+
+
+@agent_app.command("schema")
+def agent_schema_cmd() -> None:
+    """Print the JSON command contract for agents."""
+    from ical.agent import build_schema
+
+    console.print_json(data=build_schema())
+
+
+@agent_app.command("guide")
+def agent_guide_cmd() -> None:
+    """Print the Markdown agent playbook."""
+    from ical.agent import build_guide
+
+    sys.stdout.write(build_guide())
+
+
+@app.command("version")
+def version() -> None:
+    """Print the installed version."""
+    typer.echo(f"ical {__version__}")
+
+
+if __name__ == "__main__":
+    app()

ical/mcp.py

@@ -0,0 +1,63 @@
+import sys
+import json
+import asyncio
+from typing import List, Optional
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError:
+    from mcp.server.mcpserver import MCPServer as FastMCP
+from ical.calendar import add_event as core_add_event, get_events as core_get_events, run_applescript
+
+mcp = FastMCP("ical")
+
+@mcp.tool()
+def list_calendars() -> List[str]:
+    """List available calendars in macOS Calendar.app."""
+    script = 'tell application "Calendar" to get name of calendars'
+    return run_applescript(script).split(", ")
+
+@mcp.tool()
+def list_events(calendar: str = "Calendar") -> List[dict]:
+    """List events in a calendar."""
+    events = core_get_events(calendar)
+    return [
+        {
+            "title": e["title"],
+            "start": e["start_str"],
+            "end": e["end_str"]
+        } for e in events
+    ]
+
+@mcp.tool()
+def add_calendar_event(
+    title: str,
+    start: str,
+    end: str,
+    calendar: str = "Calendar",
+    attendees: Optional[List[str]] = None,
+    description: str = "",
+    location: str = "",
+    check_conflict: bool = True
+) -> dict:
+    """Add a calendar event with automatic conflict detection and attendee invites."""
+    try:
+        return core_add_event(
+            title=title,
+            start=start,
+            end=end,
+            calendar=calendar,
+            attendee=attendees,
+            description=description,
+            location=location,
+            check_conflict=check_conflict
+        )
+    except ValueError as err:
+        return {"error": str(err), "status": "conflict_detected"}
+    except Exception as err:
+        return {"error": str(err), "status": "failed"}
+
+def run_server():
+    mcp.run(transport="stdio")
+
+if __name__ == "__main__":
+    run_server()

ical_mcp-0.2.2.dist-info/METADATA

@@ -0,0 +1,113 @@
+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.

ical_mcp-0.2.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+ical/__init__.py,sha256=m6kyaNpwBcP1XYcqrelX2oS3PJuOnElOcRdBa9pEb8c,22
+ical/agent.py,sha256=MIvtCxzp7YmUMa1JRvGOHUkkMvDXzHCRT8suLgB2wQY,6730
+ical/calendar.py,sha256=54iudpsusZFYyPvfEjeq_ZuU0U7ekZ1eOxdR55KnYQQ,7817
+ical/cli.py,sha256=V8B80MA8HWPG1HG_apy2KqFKwCgP_yxY50q1t-hLrSM,9122
+ical/mcp.py,sha256=JUFpjQVV6aUu1fjrrmRa3O7nzt3SyptED2MirlM8sZY,1757
+ical_mcp-0.2.2.dist-info/METADATA,sha256=s9-DaeRpq8VC8fnocjxxTQKOScgn-Up1gObdHGsCHiw,4970
+ical_mcp-0.2.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+ical_mcp-0.2.2.dist-info/entry_points.txt,sha256=uwfz833NXq1wACEv8C_2JN0RBnwE5OaJl_B90tN3-dg,69
+ical_mcp-0.2.2.dist-info/licenses/LICENSE,sha256=f2Jg7siIJugKjulMOIw4zz439sRWntgKzpceB40HKUs,1069
+ical_mcp-0.2.2.dist-info/RECORD,,

ical_mcp-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

ical_mcp-0.2.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ical = ical.cli:app
+ical-mcp = ical.mcp:run_server

ical_mcp-0.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Misha Lubich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.