calendar-mcp 1.0.0

package/README.md

@@ -0,0 +1,159 @@
+# Calendar MCP Server
+
+MCP (Model Context Protocol) server for calendar management via Claude Code. Uses iCalendar format (RFC 5545) for data storage.
+
+## Features
+
+- **6 Calendar Tools**: Create, list, update, delete, find free time, and search events
+- **Natural Language Dates**: Supports inputs like "tomorrow at 2pm" or "next Tuesday"
+- **iCalendar Format**: Standard `.ics` format for portability
+- **Git Integration**: Automatic commits for change tracking
+- **Multi-Device Support**: Configure per-device vault paths
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+Add to your Claude Code MCP settings (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "calendar": {
+      "command": "node",
+      "args": ["/path/to/calendar-mcp/dist/index.js"],
+      "env": {
+        "VAULT_PATH": "/path/to/your/obsidian-vault"
+      }
+    }
+  }
+}
+```
+
+The server creates and manages a `Calendar/events.ics` file within your vault.
+
+## Tools
+
+### calendar_create_event
+
+Create a new calendar event.
+
+```
+Parameters:
+- title (required): Event title
+- start (required): Start date/time (ISO 8601 or natural language)
+- end: End date/time (defaults to start + 1 hour)
+- location: Event location
+- description: Event description
+- allDay: Whether this is an all-day event
+```
+
+### calendar_list_events
+
+List calendar events with optional filtering.
+
+```
+Parameters:
+- startDate: Filter events after this date
+- endDate: Filter events before this date
+- limit: Maximum events to return (default: 50)
+- sortOrder: 'asc' or 'desc' (default: 'asc')
+```
+
+### calendar_update_event
+
+Update an existing event.
+
+```
+Parameters:
+- id (required): Event ID to update
+- title: New title
+- start: New start date/time
+- end: New end date/time
+- location: New location
+- description: New description
+```
+
+### calendar_delete_event
+
+Delete an event by ID.
+
+```
+Parameters:
+- id (required): Event ID to delete
+```
+
+### calendar_find_free_time
+
+Find available time slots.
+
+```
+Parameters:
+- duration (required): Duration in minutes
+- startDate (required): Start of search range
+- endDate (required): End of search range
+- workingHoursOnly: Only 9am-5pm (default: true)
+- maxResults: Maximum slots to return (default: 5)
+```
+
+### calendar_search_events
+
+Search for events by text or criteria.
+
+```
+Parameters:
+- query: Search text (searches title, description, location)
+- startDate: Filter after this date
+- endDate: Filter before this date
+- location: Filter by location
+- limit: Maximum results (default: 20)
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Watch mode for development
+npm run dev
+```
+
+## Data Format
+
+Calendar data is stored in standard iCalendar format:
+
+```ics
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Calendar MCP//EN
+BEGIN:VEVENT
+UID:uuid@calendar.local
+DTSTAMP:20250125T120000Z
+DTSTART:20250125T140000Z
+DTEND:20250125T150000Z
+SUMMARY:Event Title
+LOCATION:Event Location
+DESCRIPTION:Event Description
+STATUS:CONFIRMED
+END:VEVENT
+END:VCALENDAR
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { createEvent } from './tools/create-event.js';
+import { listEvents } from './tools/list-events.js';
+import { updateEvent } from './tools/update-event.js';
+import { deleteEvent } from './tools/delete-event.js';
+import { findFreeTime } from './tools/find-free.js';
+import { searchEvents } from './tools/search-events.js';
+const server = new Server({
+    name: 'calendar-mcp',
+    version: '1.0.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'calendar_create_event',
+                description: 'Create a new calendar event. Supports natural language dates like "tomorrow at 2pm" or "next Tuesday".',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        title: {
+                            type: 'string',
+                            description: 'Event title/summary (required)',
+                        },
+                        start: {
+                            type: 'string',
+                            description: 'Start date/time - ISO 8601 format or natural language (required)',
+                        },
+                        end: {
+                            type: 'string',
+                            description: 'End date/time - ISO 8601 format or natural language (optional, defaults to start + 1 hour)',
+                        },
+                        location: {
+                            type: 'string',
+                            description: 'Event location (optional)',
+                        },
+                        description: {
+                            type: 'string',
+                            description: 'Event description/notes (optional)',
+                        },
+                        allDay: {
+                            type: 'boolean',
+                            description: 'Whether this is an all-day event (optional, default: false)',
+                        },
+                    },
+                    required: ['title', 'start'],
+                },
+            },
+            {
+                name: 'calendar_list_events',
+                description: 'List calendar events with optional filtering by date range.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        startDate: {
+                            type: 'string',
+                            description: 'Filter events starting after this date (optional)',
+                        },
+                        endDate: {
+                            type: 'string',
+                            description: 'Filter events ending before this date (optional)',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Maximum number of events to return (default: 50)',
+                        },
+                        sortOrder: {
+                            type: 'string',
+                            enum: ['asc', 'desc'],
+                            description: 'Sort order by start date (default: asc)',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'calendar_update_event',
+                description: 'Update an existing calendar event. Only provided fields will be updated.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'Event ID to update (required)',
+                        },
+                        title: {
+                            type: 'string',
+                            description: 'New event title (optional)',
+                        },
+                        start: {
+                            type: 'string',
+                            description: 'New start date/time (optional)',
+                        },
+                        end: {
+                            type: 'string',
+                            description: 'New end date/time (optional)',
+                        },
+                        location: {
+                            type: 'string',
+                            description: 'New location (optional)',
+                        },
+                        description: {
+                            type: 'string',
+                            description: 'New description (optional)',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'calendar_delete_event',
+                description: 'Delete a calendar event by ID.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'Event ID to delete (required)',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'calendar_find_free_time',
+                description: 'Find available time slots in the calendar that match the specified duration.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        duration: {
+                            type: 'number',
+                            description: 'Required duration in minutes',
+                        },
+                        startDate: {
+                            type: 'string',
+                            description: 'Start of search range - ISO 8601 or natural language',
+                        },
+                        endDate: {
+                            type: 'string',
+                            description: 'End of search range - ISO 8601 or natural language',
+                        },
+                        workingHoursOnly: {
+                            type: 'boolean',
+                            description: 'Only search during working hours 9am-5pm (default: true)',
+                        },
+                        maxResults: {
+                            type: 'number',
+                            description: 'Maximum number of slots to return (default: 5)',
+                        },
+                    },
+                    required: ['duration', 'startDate', 'endDate'],
+                },
+            },
+            {
+                name: 'calendar_search_events',
+                description: 'Search for events by text, date range, or location.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: {
+                            type: 'string',
+                            description: 'Search text - searches title, description, and location',
+                        },
+                        startDate: {
+                            type: 'string',
+                            description: 'Filter events after this date (optional)',
+                        },
+                        endDate: {
+                            type: 'string',
+                            description: 'Filter events before this date (optional)',
+                        },
+                        location: {
+                            type: 'string',
+                            description: 'Filter by location (optional)',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Maximum results (default: 20)',
+                        },
+                    },
+                },
+            },
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case 'calendar_create_event': {
+                const result = await createEvent(args);
+                return { content: [{ type: 'text', text: result }] };
+            }
+            case 'calendar_list_events': {
+                const result = await listEvents((args ?? {}));
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'calendar_update_event': {
+                const result = await updateEvent(args);
+                return { content: [{ type: 'text', text: result }] };
+            }
+            case 'calendar_delete_event': {
+                const result = await deleteEvent(args);
+                return { content: [{ type: 'text', text: result }] };
+            }
+            case 'calendar_find_free_time': {
+                const result = await findFreeTime(args);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'calendar_search_events': {
+                const result = await searchEvents((args ?? {}));
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            content: [{ type: 'text', text: `Error: ${errorMessage}` }],
+            isError: true,
+        };
+    }
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Calendar MCP server running');
+}
+main().catch(console.error);

package/dist/tools/create-event.d.ts

@@ -0,0 +1,7 @@
+import type { CreateEventParams } from '../types.js';
+/**
+ * Create a new calendar event
+ * @param params - Event parameters
+ * @returns Success message with event details
+ */
+export declare function createEvent(params: CreateEventParams): Promise<string>;

package/dist/tools/create-event.js

@@ -0,0 +1,57 @@
+import { v4 as uuidv4 } from 'uuid';
+import { readCalendarFile, writeCalendarFile } from '../utils/ical.js';
+import { parseNaturalDate, addHours, toISO, formatForDisplay } from '../utils/dates.js';
+import { commitAndPush } from '../utils/git.js';
+/**
+ * Create a new calendar event
+ * @param params - Event parameters
+ * @returns Success message with event details
+ */
+export async function createEvent(params) {
+    // Validate required fields
+    if (!params.title || params.title.trim() === '') {
+        throw new Error('Event title is required');
+    }
+    if (!params.start) {
+        throw new Error('Event start date/time is required');
+    }
+    // Parse dates
+    const startDate = parseNaturalDate(params.start);
+    let endDate;
+    if (params.end) {
+        endDate = parseNaturalDate(params.end);
+    }
+    else if (!params.allDay) {
+        // Default to 1 hour duration for non-all-day events
+        endDate = addHours(startDate, 1);
+    }
+    // Validate end is after start
+    if (endDate && endDate <= startDate) {
+        throw new Error('End date/time must be after start date/time');
+    }
+    // Read existing events
+    const events = await readCalendarFile();
+    // Create new event
+    const now = new Date();
+    const newEvent = {
+        id: uuidv4(),
+        title: params.title.trim(),
+        start: toISO(startDate),
+        end: endDate ? toISO(endDate) : undefined,
+        location: params.location?.trim(),
+        description: params.description?.trim(),
+        allDay: params.allDay ?? false,
+        status: 'CONFIRMED',
+        created: toISO(now),
+        lastModified: toISO(now),
+    };
+    // Add to events list
+    events.push(newEvent);
+    // Write back to file
+    await writeCalendarFile(events);
+    // Commit changes
+    await commitAndPush(`Add event: ${newEvent.title}`);
+    // Return success message
+    const displayDate = formatForDisplay(startDate, newEvent.allDay);
+    return `Created event "${newEvent.title}" on ${displayDate}`;
+}

package/dist/tools/delete-event.d.ts

@@ -0,0 +1,7 @@
+import type { DeleteEventParams } from '../types.js';
+/**
+ * Delete a calendar event
+ * @param params - Delete parameters (id required)
+ * @returns Success message
+ */
+export declare function deleteEvent(params: DeleteEventParams): Promise<string>;

package/dist/tools/delete-event.js

@@ -0,0 +1,29 @@
+import { readCalendarFile, writeCalendarFile } from '../utils/ical.js';
+import { commitAndPush } from '../utils/git.js';
+/**
+ * Delete a calendar event
+ * @param params - Delete parameters (id required)
+ * @returns Success message
+ */
+export async function deleteEvent(params) {
+    // Validate required field
+    if (!params.id) {
+        throw new Error('Event ID is required');
+    }
+    // Read existing events
+    const events = await readCalendarFile();
+    // Find the event to delete
+    const eventIndex = events.findIndex(e => e.id === params.id);
+    if (eventIndex === -1) {
+        throw new Error(`Event not found: ${params.id}`);
+    }
+    const deletedEvent = events[eventIndex];
+    // Remove from array
+    events.splice(eventIndex, 1);
+    // Write back to file
+    await writeCalendarFile(events);
+    // Commit changes
+    await commitAndPush(`Delete event: ${deletedEvent.title}`);
+    // Return success message
+    return `Deleted event "${deletedEvent.title}"`;
+}

package/dist/tools/find-free.d.ts

@@ -0,0 +1,7 @@
+import type { FindFreeTimeParams, FindFreeTimeResult } from '../types.js';
+/**
+ * Find available time slots in the calendar
+ * @param params - Search parameters
+ * @returns List of free time slots
+ */
+export declare function findFreeTime(params: FindFreeTimeParams): Promise<FindFreeTimeResult>;

package/dist/tools/find-free.js

@@ -0,0 +1,119 @@
+import { readCalendarFile } from '../utils/ical.js';
+import { parseNaturalDate, addMinutes, toISO, rangesOverlap, } from '../utils/dates.js';
+const DEFAULT_MAX_RESULTS = 5;
+const WORKING_HOURS_START = 9; // 9 AM
+const WORKING_HOURS_END = 17; // 5 PM
+const SLOT_INCREMENT_MINUTES = 30; // Check every 30 minutes
+/**
+ * Find available time slots in the calendar
+ * @param params - Search parameters
+ * @returns List of free time slots
+ */
+export async function findFreeTime(params) {
+    // Validate required fields
+    if (!params.duration || params.duration <= 0) {
+        throw new Error('Duration must be a positive number of minutes');
+    }
+    if (!params.startDate) {
+        throw new Error('Start date is required');
+    }
+    if (!params.endDate) {
+        throw new Error('End date is required');
+    }
+    const searchStart = parseNaturalDate(params.startDate);
+    const searchEnd = parseNaturalDate(params.endDate);
+    if (searchEnd <= searchStart) {
+        throw new Error('End date must be after start date');
+    }
+    const workingHoursOnly = params.workingHoursOnly ?? true;
+    const maxResults = params.maxResults ?? DEFAULT_MAX_RESULTS;
+    // Read all events in the search range
+    const allEvents = await readCalendarFile();
+    // Filter events that overlap with search range
+    const events = allEvents.filter(event => {
+        const eventStart = new Date(event.start);
+        const eventEnd = event.end ? new Date(event.end) : addMinutes(eventStart, 60);
+        return rangesOverlap(eventStart, eventEnd, searchStart, searchEnd);
+    });
+    // Sort events by start time
+    events.sort((a, b) => new Date(a.start).getTime() - new Date(b.start).getTime());
+    // Find free slots
+    const freeSlots = [];
+    let currentTime = new Date(searchStart);
+    while (currentTime < searchEnd && freeSlots.length < maxResults) {
+        // Adjust for working hours if needed
+        if (workingHoursOnly) {
+            const adjustedTime = adjustForWorkingHours(currentTime);
+            if (!adjustedTime) {
+                // Move to next day
+                currentTime = getNextWorkingDayStart(currentTime);
+                continue;
+            }
+            currentTime = adjustedTime;
+        }
+        // Check if this slot is free
+        const slotEnd = addMinutes(currentTime, params.duration);
+        // Make sure slot end doesn't exceed working hours
+        if (workingHoursOnly) {
+            const dayEnd = getWorkingHoursEnd(currentTime);
+            if (slotEnd > dayEnd) {
+                // Move to next day
+                currentTime = getNextWorkingDayStart(currentTime);
+                continue;
+            }
+        }
+        // Make sure slot end doesn't exceed search range
+        if (slotEnd > searchEnd) {
+            break;
+        }
+        // Check for conflicts with existing events
+        const hasConflict = events.some(event => {
+            const eventStart = new Date(event.start);
+            const eventEnd = event.end ? new Date(event.end) : addMinutes(eventStart, 60);
+            return rangesOverlap(currentTime, slotEnd, eventStart, eventEnd);
+        });
+        if (!hasConflict) {
+            freeSlots.push({
+                start: toISO(currentTime),
+                end: toISO(slotEnd),
+                durationMinutes: params.duration,
+            });
+            // Skip past this slot
+            currentTime = slotEnd;
+        }
+        else {
+            // Move to next slot increment
+            currentTime = addMinutes(currentTime, SLOT_INCREMENT_MINUTES);
+        }
+    }
+    return { freeSlots };
+}
+/**
+ * Adjust a time to be within working hours
+ * Returns null if the time is after working hours for the day
+ */
+function adjustForWorkingHours(time) {
+    const hours = time.getUTCHours();
+    if (hours < WORKING_HOURS_START) {
+        // Before working hours - move to start of working hours
+        return new Date(Date.UTC(time.getUTCFullYear(), time.getUTCMonth(), time.getUTCDate(), WORKING_HOURS_START, 0, 0, 0));
+    }
+    if (hours >= WORKING_HOURS_END) {
+        // After working hours - return null to trigger next day
+        return null;
+    }
+    return time;
+}
+/**
+ * Get the start of the next working day
+ */
+function getNextWorkingDayStart(time) {
+    const nextDay = new Date(Date.UTC(time.getUTCFullYear(), time.getUTCMonth(), time.getUTCDate() + 1, WORKING_HOURS_START, 0, 0, 0));
+    return nextDay;
+}
+/**
+ * Get the end of working hours for a given day
+ */
+function getWorkingHoursEnd(time) {
+    return new Date(Date.UTC(time.getUTCFullYear(), time.getUTCMonth(), time.getUTCDate(), WORKING_HOURS_END, 0, 0, 0));
+}

package/dist/tools/list-events.d.ts

@@ -0,0 +1,11 @@
+import type { ListEventsParams, ListEventsResult, CalendarEvent } from '../types.js';
+/**
+ * List calendar events with optional filtering
+ * @param params - Filter parameters
+ * @returns List of events with count and hasMore indicator
+ */
+export declare function listEvents(params?: ListEventsParams): Promise<ListEventsResult>;
+/**
+ * Get all events without filtering (internal use)
+ */
+export declare function getAllEvents(): Promise<CalendarEvent[]>;