@jnss95/ical-mcp 1.0.0

package/README.md

@@ -0,0 +1,250 @@
+# iCal MCP Server
+
+A modern Model Context Protocol (MCP) server for managing iCalendar files. This server allows AI assistants to interact with calendar data through a standardized protocol.
+
+## Features
+
+- **Load calendars** from:
+  - Local files (`.ics`)
+  - HTTP/HTTPS URLs
+  - Raw iCal strings
+- **Query events** with filters for:
+  - Date ranges
+  - Search text (summary, description, location)
+  - Location
+  - Recurring event expansion
+- **Full CRUD operations**:
+  - Create new events
+  - Update existing events
+  - Delete events
+- **Multiple calendar support**: Load and manage multiple calendars simultaneously
+- **Read-only mode**: HTTP calendars are automatically read-only
+
+## Installation
+
+### Using npx (recommended)
+
+You can run the server directly without installation:
+
+```bash
+npx @jonas/ical-mcp
+```
+
+### Global Installation
+
+```bash
+npm install -g @jonas/ical-mcp
+ical-mcp
+```
+
+### Local Development
+
+```bash
+git clone https://github.com/jnss95/ical-mcp.git
+cd ical-mcp
+npm install
+npm run build
+npm start
+```
+
+## Configuration
+
+### Environment Variables
+
+You can pre-configure calendars using environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `ICAL_URL` | URL to an iCal calendar (http/https) |
+| `ICAL_FILE` | Path to a local .ics file |
+| `ICAL_ALIAS` | Alias for the calendar (default: "default") |
+| `ICAL_CALENDARS` | JSON array for multiple calendars |
+
+**Multiple calendars example:**
+```bash
+ICAL_CALENDARS='[{"alias":"work","source":"https://example.com/work.ics"},{"alias":"personal","source":"/path/to/personal.ics"}]'
+```
+
+### VS Code MCP Configuration
+
+Add to your VS Code settings (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "ical": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@jnss95/ical-mcp"],
+      "env": {
+        "ICAL_URL": "https://example.com/your-calendar.ics"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop Configuration
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ical": {
+      "command": "npx",
+      "args": ["@jnss95/ical-mcp"],
+      "env": {
+        "ICAL_URL": "https://example.com/your-calendar.ics"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Calendar Management
+
+| Tool | Description |
+|------|-------------|
+| `load_calendar` | Load a calendar from a file path or URL |
+| `create_calendar` | Create a new empty calendar file |
+| `list_loaded_calendars` | List all currently loaded calendars |
+| `unload_calendar` | Unload a calendar from memory |
+| `export_calendar` | Export calendar as iCal string |
+| `get_calendar_info` | Get metadata about a loaded calendar |
+
+### Event Operations
+
+| Tool | Description |
+|------|-------------|
+| `list_events` | List all events in a calendar |
+| `search_events` | Search events with filters |
+| `get_event` | Get details of a specific event |
+| `create_event` | Create a new event |
+| `update_event` | Update an existing event |
+| `delete_event` | Delete an event |
+
+## Tool Examples
+
+### Load a Calendar
+
+```json
+{
+  "tool": "load_calendar",
+  "arguments": {
+    "source": "/path/to/calendar.ics",
+    "alias": "work"
+  }
+}
+```
+
+### Search Events
+
+```json
+{
+  "tool": "search_events",
+  "arguments": {
+    "calendarId": "work",
+    "startDate": "2024-01-01T00:00:00Z",
+    "endDate": "2024-01-31T23:59:59Z",
+    "searchText": "meeting",
+    "expandRecurring": true
+  }
+}
+```
+
+### Create Event
+
+```json
+{
+  "tool": "create_event",
+  "arguments": {
+    "calendarId": "work",
+    "summary": "Team Meeting",
+    "start": "2024-01-15T10:00:00Z",
+    "end": "2024-01-15T11:00:00Z",
+    "description": "Weekly team sync",
+    "location": "Conference Room A"
+  }
+}
+```
+
+### Create Recurring Event
+
+```json
+{
+  "tool": "create_event",
+  "arguments": {
+    "calendarId": "work",
+    "summary": "Daily Standup",
+    "start": "2024-01-15T09:00:00Z",
+    "end": "2024-01-15T09:15:00Z",
+    "rrule": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
+  }
+}
+```
+
+### Update Event
+
+```json
+{
+  "tool": "update_event",
+  "arguments": {
+    "calendarId": "work",
+    "eventId": "event-uid@example.com",
+    "summary": "Updated Meeting Title",
+    "location": "New Location"
+  }
+}
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+### Building
+
+```bash
+# Build TypeScript
+npm run build
+
+# Watch mode
+npm run watch
+```
+
+## Project Structure
+
+```
+ical_mcp/
+├── src/
+│   ├── index.ts              # MCP server entry point
+│   ├── calendar/
+│   │   ├── calendar.ts       # Calendar class (CRUD operations)
+│   │   ├── loader.ts         # Calendar loading utilities
+│   │   └── index.ts          # Module exports
+│   └── types/
+│       ├── calendar.ts       # Type definitions
+│       ├── ical.d.ts         # ical.js type declarations
+│       └── index.ts          # Type exports
+├── build/                    # Compiled JavaScript
+├── package.json
+├── tsconfig.json
+└── vitest.config.ts
+```
+
+## License
+
+MIT

package/build/calendar/calendar.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Calendar class for parsing and manipulating iCal data
+ */
+import type { CalendarEvent, CalendarMetadata, CreateEventOptions, UpdateEventOptions, QueryEventsOptions, QueryResult, CalendarSource } from '../types/calendar.js';
+/**
+ * Manages calendar operations including parsing, querying, and modifying events
+ */
+export declare class Calendar {
+    private vcalendar;
+    private source;
+    constructor(source: CalendarSource);
+    /**
+     * Load and parse iCal data from a string
+     */
+    loadFromString(icalString: string): void;
+    /**
+     * Get the raw iCal string representation
+     */
+    toString(): string;
+    /**
+     * Get calendar metadata
+     */
+    getMetadata(): CalendarMetadata;
+    /**
+     * Get all events in the calendar
+     */
+    getAllEvents(): CalendarEvent[];
+    /**
+     * Get a single event by UID
+     */
+    getEvent(uid: string): CalendarEvent | null;
+    /**
+     * Query events with various filters
+     */
+    queryEvents(options?: QueryEventsOptions): QueryResult;
+    /**
+     * Create a new event
+     */
+    createEvent(options: CreateEventOptions): CalendarEvent;
+    /**
+     * Update an existing event
+     */
+    updateEvent(uid: string, options: UpdateEventOptions): CalendarEvent;
+    /**
+     * Delete an event by UID
+     */
+    deleteEvent(uid: string): boolean;
+    /**
+     * Get the calendar source configuration
+     */
+    getSource(): CalendarSource;
+    /**
+     * Check if the calendar is writable
+     */
+    isWritable(): boolean;
+    /**
+     * Parse a VEVENT component into a CalendarEvent
+     */
+    private parseVEvent;
+    /**
+     * Parse a date/time string into an ICAL.Time
+     */
+    private parseDateTime;
+    /**
+     * Expand recurring events within a date range
+     */
+    private expandRecurringEvents;
+}
+//# sourceMappingURL=calendar.d.ts.map

package/build/calendar/calendar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../src/calendar/calendar.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,cAAc,EACf,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,MAAM,CAAiB;gBAEnB,MAAM,EAAE,cAAc;IAQlC;;OAEG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKxC;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,WAAW,IAAI,gBAAgB;IAc/B;;OAEG;IACH,YAAY,IAAI,aAAa,EAAE;IAK/B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAc3C;;OAEG;IACH,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW;IAoF1D;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,aAAa;IAsFvD;;OAEG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,aAAa;IA6HpE;;OAEG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAkBjC;;OAEG;IACH,SAAS,IAAI,cAAc;IAI3B;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,OAAO,CAAC,WAAW;IAoDnB;;OAEG;IACH,OAAO,CAAC,aAAa;IAcrB;;OAEG;IACH,OAAO,CAAC,qBAAqB;CA8D9B"}