fantastical-mcp 0.1.0__tar.gz

fantastical_mcp-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment variables
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+
+# Project
+TODO.md
+*.mcpb

fantastical_mcp-0.1.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "fantastical": {
+      "command": "uv",
+      "args": ["run", "--directory", "/Users/kerrj/Documents/Development/fantastical-mcp", "fantastical-mcp"]
+    }
+  }
+}

fantastical_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,45 @@
+# CLAUDE.md
+
+## Project Overview
+
+**fantastical-mcp** is a Python MCP (Model Context Protocol) server that gives AI assistants read/write access to the Fantastical calendar on macOS. It reads events directly from Fantastical's local SQLite database and creates events via Fantastical's `x-fantastical3://` URL scheme. No TCC permissions or API keys are needed.
+
+## Architecture
+
+| Module | Responsibility |
+|--------|---------------|
+| `src/fantastical_mcp/server.py` | FastMCP server entry point, 12 tool definitions, transport config |
+| `src/fantastical_mcp/db.py` | Read-only SQLite access to Fantastical's YapDatabase store. Three-tier read strategy: secondary index, FTS5, blob decode with FTS fallback. |
+| `src/fantastical_mcp/formatters.py` | Plain-text output formatters. Australian English throughout. UTC to local time conversion on display. |
+| `src/fantastical_mcp/url_scheme.py` | URL scheme helpers for event creation and date navigation |
+
+## Documentation
+
+- `docs/tools.md` -- Detailed tool reference with parameters and example output
+- `docs/configuration.md` -- Environment variables, Claude Code/Desktop config, calendar exclusion
+- `docs/how-it-works.md` -- Technical architecture: YapDatabase, NSKeyedArchiver, NSDate epoch, URL scheme, TCC avoidance
+- `docs/development.md` -- Project structure, testing, blob decoding, adding tools, known quirks
+
+## Development
+
+- Python >=3.12, managed with `uv`
+- Install: `uv pip install -e ".[test]"`
+- Activate venv: `source .venv/bin/activate`
+- Unit tests (no Fantastical required): `pytest tests/ --ignore=tests/integration -v`
+- Integration tests (require Fantastical): `pytest tests/integration/ -v -m integration`
+- All tests: `pytest -v`
+
+## Conventions
+
+- **Australian English** in all display text and documentation (Licence, Organiser, serialisation, etc.)
+- All timestamps stored in UTC, converted to local time only on display
+- Database opened read-only (`?mode=ro`) to prevent corruption
+- Environment variables documented in `env.example`
+- Follow the FastMCP patterns for tool definitions
+
+## Key Design Decisions
+
+- Direct database read avoids TCC permission issues that plague EventKit and AppleScript approaches
+- FTS fallback path ensures graceful degradation if `NSKeyedArchiver` blob format changes
+- Writes use URL scheme to delegate parsing, validation, and persistence to Fantastical itself
+- Default calendar exclusions hide system calendars (Weather, Openings, etc.) from cluttering results

fantastical_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jayden Kerr
+
+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.

fantastical_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: fantastical-mcp
+Version: 0.1.0
+Summary: Fantastical calendar MCP server — read events from Fantastical's local database, create via URL scheme
+License-Expression: MIT
+License-File: LICENSE
+Keywords: calendar,fantastical,macos,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=2.0.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Fantastical MCP
+
+An MCP server that gives AI assistants read/write access to your Fantastical calendar on macOS.
+
+## What it does
+
+fantastical-mcp reads calendar events directly from Fantastical's local SQLite database and creates events via Fantastical's `x-fantastical3://` URL scheme. No TCC permissions, no API keys, no network access -- it works entirely offline using the data Fantastical already stores on your Mac.
+
+- **Read** -- Query events by date range, calendar, or full-text search
+- **Write** -- Create events using Fantastical's natural language parser
+- **Navigate** -- Open Fantastical to a specific date
+
+## Requirements
+
+- macOS
+- [Fantastical](https://flexibits.com/fantastical) installed with at least one calendar
+- Python 3.12+
+
+## Quick start
+
+### Claude Desktop (1-click install)
+
+1. Download `fantastical-mcp-0.1.0.mcpb` from the [latest release](https://github.com/jaydenk/fantastical-mcp/releases/latest)
+2. Double-click the file
+3. Done — Fantastical tools are now available in Claude Desktop
+
+### Install from PyPI
+
+```bash
+uvx fantastical-mcp
+```
+
+### Local development
+
+```bash
+git clone https://github.com/jaydenk/fantastical-mcp.git
+cd fantastical-mcp
+uv venv && uv pip install -e ".[test]"
+```
+
+## Configuration
+
+### Claude Code
+
+Add to your `.claude/settings.json` (or project-level settings):
+
+**Published package:**
+
+```json
+{
+  "mcpServers": {
+    "fantastical": {
+      "command": "uvx",
+      "args": ["fantastical-mcp"]
+    }
+  }
+}
+```
+
+**Local development:**
+
+```json
+{
+  "mcpServers": {
+    "fantastical": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/fantastical-mcp", "fantastical-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "fantastical": {
+      "command": "uvx",
+      "args": ["fantastical-mcp"]
+    }
+  }
+}
+```
+
+See [docs/configuration.md](docs/configuration.md) for environment variables, calendar exclusion, and transport options.
+
+## Available tools
+
+| Tool | Description |
+|------|-------------|
+| `get_today` | All events for today, grouped by calendar |
+| `get_upcoming` | Events for the next N days, grouped by date |
+| `get_calendars` | List all calendars with event counts |
+| `get_event` | Full details for a specific event by ID |
+| `search_events` | Full-text search across titles, locations, notes, attendees |
+| `get_events_by_calendar` | Events from a specific calendar |
+| `get_availability` | Free/busy time slots for a date |
+| `get_recurring` | Upcoming recurring events, optionally filtered by calendar |
+| `get_invitations` | Pending event invitations that need a response |
+| `get_recent` | Most recently added or synced events |
+| `create_event` | Create an event using natural language |
+| `show_date` | Open Fantastical's mini calendar to a date |
+
+See [docs/tools.md](docs/tools.md) for parameters, types, defaults, and example output.
+
+## Limitations
+
+- **No update or delete** -- Fantastical's URL scheme only supports event creation. Modification and deletion require EventKit, which needs TCC permissions.
+- **macOS only** -- Relies on Fantastical's macOS database location and the `open` command.
+- **Read-only database access** -- The database is opened in `?mode=ro` to prevent any risk of corruption.
+- **Blob format dependency** -- The `NSKeyedArchiver` serialisation format is an internal detail of Fantastical and could change between versions. An FTS fallback path mitigates this.
+
+## Documentation
+
+- [Tool reference](docs/tools.md) -- Detailed parameters and example output for every tool
+- [Configuration guide](docs/configuration.md) -- Environment variables, transport options, calendar exclusion
+- [How it works](docs/how-it-works.md) -- Technical architecture and design decisions
+- [Development guide](docs/development.md) -- Project structure, testing, and contributing
+
+## Licence
+
+[MIT](LICENSE)

fantastical_mcp-0.1.0/README.md

@@ -0,0 +1,125 @@
+# Fantastical MCP
+
+An MCP server that gives AI assistants read/write access to your Fantastical calendar on macOS.
+
+## What it does
+
+fantastical-mcp reads calendar events directly from Fantastical's local SQLite database and creates events via Fantastical's `x-fantastical3://` URL scheme. No TCC permissions, no API keys, no network access -- it works entirely offline using the data Fantastical already stores on your Mac.
+
+- **Read** -- Query events by date range, calendar, or full-text search
+- **Write** -- Create events using Fantastical's natural language parser
+- **Navigate** -- Open Fantastical to a specific date
+
+## Requirements
+
+- macOS
+- [Fantastical](https://flexibits.com/fantastical) installed with at least one calendar
+- Python 3.12+
+
+## Quick start
+
+### Claude Desktop (1-click install)
+
+1. Download `fantastical-mcp-0.1.0.mcpb` from the [latest release](https://github.com/jaydenk/fantastical-mcp/releases/latest)
+2. Double-click the file
+3. Done — Fantastical tools are now available in Claude Desktop
+
+### Install from PyPI
+
+```bash
+uvx fantastical-mcp
+```
+
+### Local development
+
+```bash
+git clone https://github.com/jaydenk/fantastical-mcp.git
+cd fantastical-mcp
+uv venv && uv pip install -e ".[test]"
+```
+
+## Configuration
+
+### Claude Code
+
+Add to your `.claude/settings.json` (or project-level settings):
+
+**Published package:**
+
+```json
+{
+  "mcpServers": {
+    "fantastical": {
+      "command": "uvx",
+      "args": ["fantastical-mcp"]
+    }
+  }
+}
+```
+
+**Local development:**
+
+```json
+{
+  "mcpServers": {
+    "fantastical": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/fantastical-mcp", "fantastical-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "fantastical": {
+      "command": "uvx",
+      "args": ["fantastical-mcp"]
+    }
+  }
+}
+```
+
+See [docs/configuration.md](docs/configuration.md) for environment variables, calendar exclusion, and transport options.
+
+## Available tools
+
+| Tool | Description |
+|------|-------------|
+| `get_today` | All events for today, grouped by calendar |
+| `get_upcoming` | Events for the next N days, grouped by date |
+| `get_calendars` | List all calendars with event counts |
+| `get_event` | Full details for a specific event by ID |
+| `search_events` | Full-text search across titles, locations, notes, attendees |
+| `get_events_by_calendar` | Events from a specific calendar |
+| `get_availability` | Free/busy time slots for a date |
+| `get_recurring` | Upcoming recurring events, optionally filtered by calendar |
+| `get_invitations` | Pending event invitations that need a response |
+| `get_recent` | Most recently added or synced events |
+| `create_event` | Create an event using natural language |
+| `show_date` | Open Fantastical's mini calendar to a date |
+
+See [docs/tools.md](docs/tools.md) for parameters, types, defaults, and example output.
+
+## Limitations
+
+- **No update or delete** -- Fantastical's URL scheme only supports event creation. Modification and deletion require EventKit, which needs TCC permissions.
+- **macOS only** -- Relies on Fantastical's macOS database location and the `open` command.
+- **Read-only database access** -- The database is opened in `?mode=ro` to prevent any risk of corruption.
+- **Blob format dependency** -- The `NSKeyedArchiver` serialisation format is an internal detail of Fantastical and could change between versions. An FTS fallback path mitigates this.
+
+## Documentation
+
+- [Tool reference](docs/tools.md) -- Detailed parameters and example output for every tool
+- [Configuration guide](docs/configuration.md) -- Environment variables, transport options, calendar exclusion
+- [How it works](docs/how-it-works.md) -- Technical architecture and design decisions
+- [Development guide](docs/development.md) -- Project structure, testing, and contributing
+
+## Licence
+
+[MIT](LICENSE)

fantastical_mcp-0.1.0/build_mcpb.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Build the MCPB bundle for Claude Desktop 1-click install.
+# Requires: npm install -g @anthropic-ai/mcpb
+set -euo pipefail
+
+VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+OUTPUT="fantastical-mcp-${VERSION}.mcpb"
+
+mcpb pack mcpb "$OUTPUT"
+echo "Built: $OUTPUT"

fantastical_mcp-0.1.0/docs/configuration.md

@@ -0,0 +1,165 @@
+# Configuration Guide
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FANTASTICAL_DB_PATH` | Auto-detected | Override the auto-discovered database path. Must point to an existing `.fcdata` file. |
+| `FANTASTICAL_EXCLUDE_CALENDARS` | `Weather,Openings,RSVP Invitations,Proposals,Notifications` | Comma-separated calendar names to hide from all query results. Replaces the default exclusion list entirely when set. |
+| `FANTASTICAL_RECURRING_EXCLUDE_CALENDARS` | `Birthdays,Anniversaries` | Comma-separated calendar names to additionally exclude from `get_recurring` results. Replaces the default recurring exclusion list when set. |
+| `FANTASTICAL_MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` (default for CLI tools) or `sse` (HTTP server). |
+| `FANTASTICAL_MCP_HOST` | `127.0.0.1` | Host address for SSE transport. |
+| `FANTASTICAL_MCP_PORT` | `8000` | Port for SSE transport. |
+
+An example `.env` file is provided as `env.example` in the project root.
+
+---
+
+## Claude Code
+
+### Published package
+
+Add to `.claude/settings.json` (user-level) or `.claude/settings.local.json` (project-level):
+
+```json
+{
+  "mcpServers": {
+    "fantastical": {
+      "command": "uvx",
+      "args": ["fantastical-mcp"]
+    }
+  }
+}
+```
+
+### Local development
+
+Use `uv run --directory` to point at the cloned repository:
+
+```json
+{
+  "mcpServers": {
+    "fantastical": {
+      "command": "uv",
+      "args": ["run", "--directory", "/Users/you/path/to/fantastical-mcp", "fantastical-mcp"]
+    }
+  }
+}
+```
+
+### With environment variables
+
+```json
+{
+  "mcpServers": {
+    "fantastical": {
+      "command": "uv",
+      "args": ["run", "--directory", "/Users/you/path/to/fantastical-mcp", "fantastical-mcp"],
+      "env": {
+        "FANTASTICAL_EXCLUDE_CALENDARS": "Weather,Openings,RSVP Invitations"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "fantastical": {
+      "command": "uvx",
+      "args": ["fantastical-mcp"]
+    }
+  }
+}
+```
+
+For local development:
+
+```json
+{
+  "mcpServers": {
+    "fantastical": {
+      "command": "uv",
+      "args": ["run", "--directory", "/Users/you/path/to/fantastical-mcp", "fantastical-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Calendar Exclusion
+
+By default, several Fantastical system calendars are hidden from results:
+
+- Weather
+- Openings
+- RSVP Invitations
+- Proposals
+- Notifications
+
+### Override via environment variable
+
+Setting `FANTASTICAL_EXCLUDE_CALENDARS` **replaces** the default list entirely. To exclude only Weather and Proposals:
+
+```bash
+FANTASTICAL_EXCLUDE_CALENDARS="Weather,Proposals"
+```
+
+To exclude nothing (show all calendars):
+
+```bash
+FANTASTICAL_EXCLUDE_CALENDARS=""
+```
+
+### Override via constructor
+
+When using `FantasticalDB` directly (e.g. in tests), pass `exclude_calendars`:
+
+```python
+db = FantasticalDB(db_path, exclude_calendars={"Weather"})
+```
+
+Priority order:
+1. `exclude_calendars` constructor parameter (highest)
+2. `FANTASTICAL_EXCLUDE_CALENDARS` environment variable
+3. Built-in default set (lowest)
+
+### Recurring Event Exclusion
+
+The `get_recurring` tool additionally excludes Birthdays and Anniversaries calendars by default, since these dominate recurring results without adding scheduling value.
+
+Override with `FANTASTICAL_RECURRING_EXCLUDE_CALENDARS`:
+
+```bash
+# Include birthdays in recurring results
+FANTASTICAL_RECURRING_EXCLUDE_CALENDARS=""
+
+# Exclude different calendars
+FANTASTICAL_RECURRING_EXCLUDE_CALENDARS="Birthdays,Holidays in Australia"
+```
+
+---
+
+## Transport Options
+
+### stdio (default)
+
+Used by Claude Code and Claude Desktop. The MCP client spawns the server as a subprocess and communicates over stdin/stdout. No configuration needed beyond the MCP server entry.
+
+### SSE (Server-Sent Events)
+
+For use cases where the server runs as a persistent HTTP process:
+
+```bash
+FANTASTICAL_MCP_TRANSPORT=sse FANTASTICAL_MCP_HOST=127.0.0.1 FANTASTICAL_MCP_PORT=8000 fantastical-mcp
+```
+
+The server will listen on `http://127.0.0.1:8000` and serve the MCP protocol over SSE. This is useful for development, debugging, or connecting from MCP clients that support HTTP transport.