calendar-mcp 1.0.0

package/dist/tools/list-events.js

@@ -0,0 +1,46 @@
+import { readCalendarFile } from '../utils/ical.js';
+import { parseNaturalDate } from '../utils/dates.js';
+const DEFAULT_LIMIT = 50;
+/**
+ * List calendar events with optional filtering
+ * @param params - Filter parameters
+ * @returns List of events with count and hasMore indicator
+ */
+export async function listEvents(params = {}) {
+    // Read all events
+    let events = await readCalendarFile();
+    // Filter by start date
+    if (params.startDate) {
+        const startFilter = parseNaturalDate(params.startDate);
+        events = events.filter(event => new Date(event.start) >= startFilter);
+    }
+    // Filter by end date
+    if (params.endDate) {
+        const endFilter = parseNaturalDate(params.endDate);
+        events = events.filter(event => new Date(event.start) <= endFilter);
+    }
+    // Sort by start date
+    const sortOrder = params.sortOrder ?? 'asc';
+    events.sort((a, b) => {
+        const dateA = new Date(a.start).getTime();
+        const dateB = new Date(b.start).getTime();
+        return sortOrder === 'asc' ? dateA - dateB : dateB - dateA;
+    });
+    // Calculate total count before limiting
+    const totalCount = events.length;
+    // Apply limit
+    const limit = params.limit ?? DEFAULT_LIMIT;
+    const hasMore = events.length > limit;
+    events = events.slice(0, limit);
+    return {
+        events,
+        count: events.length,
+        hasMore,
+    };
+}
+/**
+ * Get all events without filtering (internal use)
+ */
+export async function getAllEvents() {
+    return readCalendarFile();
+}

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

@@ -0,0 +1,7 @@
+import type { SearchEventsParams, CalendarEvent } from '../types.js';
+/**
+ * Search for events matching criteria
+ * @param params - Search parameters
+ * @returns List of matching events
+ */
+export declare function searchEvents(params?: SearchEventsParams): Promise<CalendarEvent[]>;

package/dist/tools/search-events.js

@@ -0,0 +1,43 @@
+import { readCalendarFile } from '../utils/ical.js';
+import { parseNaturalDate } from '../utils/dates.js';
+const DEFAULT_LIMIT = 20;
+/**
+ * Search for events matching criteria
+ * @param params - Search parameters
+ * @returns List of matching events
+ */
+export async function searchEvents(params = {}) {
+    // Read all events
+    let events = await readCalendarFile();
+    // Text search (case-insensitive)
+    if (params.query) {
+        const query = params.query.toLowerCase();
+        events = events.filter(event => {
+            const titleMatch = event.title.toLowerCase().includes(query);
+            const descriptionMatch = event.description?.toLowerCase().includes(query) ?? false;
+            const locationMatch = event.location?.toLowerCase().includes(query) ?? false;
+            return titleMatch || descriptionMatch || locationMatch;
+        });
+    }
+    // Filter by start date
+    if (params.startDate) {
+        const startFilter = parseNaturalDate(params.startDate);
+        events = events.filter(event => new Date(event.start) >= startFilter);
+    }
+    // Filter by end date
+    if (params.endDate) {
+        const endFilter = parseNaturalDate(params.endDate);
+        events = events.filter(event => new Date(event.start) <= endFilter);
+    }
+    // Filter by location (case-insensitive contains)
+    if (params.location) {
+        const locationQuery = params.location.toLowerCase();
+        events = events.filter(event => event.location?.toLowerCase().includes(locationQuery) ?? false);
+    }
+    // Sort by start date (most recent first for search results)
+    events.sort((a, b) => new Date(a.start).getTime() - new Date(b.start).getTime());
+    // Apply limit
+    const limit = params.limit ?? DEFAULT_LIMIT;
+    events = events.slice(0, limit);
+    return events;
+}

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

@@ -0,0 +1,7 @@
+import type { UpdateEventParams } from '../types.js';
+/**
+ * Update an existing calendar event
+ * @param params - Update parameters (id required, other fields optional)
+ * @returns Success message
+ */
+export declare function updateEvent(params: UpdateEventParams): Promise<string>;

package/dist/tools/update-event.js

@@ -0,0 +1,64 @@
+import { readCalendarFile, writeCalendarFile } from '../utils/ical.js';
+import { parseNaturalDate, toISO, formatForDisplay } from '../utils/dates.js';
+import { commitAndPush } from '../utils/git.js';
+/**
+ * Update an existing calendar event
+ * @param params - Update parameters (id required, other fields optional)
+ * @returns Success message
+ */
+export async function updateEvent(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 update
+    const eventIndex = events.findIndex(e => e.id === params.id);
+    if (eventIndex === -1) {
+        throw new Error(`Event not found: ${params.id}`);
+    }
+    const event = events[eventIndex];
+    const originalTitle = event.title;
+    // Update fields if provided
+    if (params.title !== undefined) {
+        if (params.title.trim() === '') {
+            throw new Error('Event title cannot be empty');
+        }
+        event.title = params.title.trim();
+    }
+    if (params.start !== undefined) {
+        const startDate = parseNaturalDate(params.start);
+        event.start = toISO(startDate);
+    }
+    if (params.end !== undefined) {
+        const endDate = parseNaturalDate(params.end);
+        event.end = toISO(endDate);
+    }
+    if (params.location !== undefined) {
+        event.location = params.location.trim() || undefined;
+    }
+    if (params.description !== undefined) {
+        event.description = params.description.trim() || undefined;
+    }
+    // Validate end is after start if both are set
+    if (event.end) {
+        const startDate = new Date(event.start);
+        const endDate = new Date(event.end);
+        if (endDate <= startDate) {
+            throw new Error('End date/time must be after start date/time');
+        }
+    }
+    // Update lastModified
+    event.lastModified = toISO(new Date());
+    // Update in array
+    events[eventIndex] = event;
+    // Write back to file
+    await writeCalendarFile(events);
+    // Commit changes
+    await commitAndPush(`Update event: ${event.title}`);
+    // Return success message
+    const startDate = new Date(event.start);
+    const displayDate = formatForDisplay(startDate, event.allDay);
+    return `Updated "${originalTitle}" - now "${event.title}" on ${displayDate}`;
+}

package/dist/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Calendar event representation (internal format)
+ */
+export interface CalendarEvent {
+    /** Unique identifier (UID from iCal, without domain suffix) */
+    id: string;
+    /** Event title/summary */
+    title: string;
+    /** Start date/time in ISO 8601 format */
+    start: string;
+    /** End date/time in ISO 8601 format (optional) */
+    end?: string;
+    /** Event location (optional) */
+    location?: string;
+    /** Event description (optional) */
+    description?: string;
+    /** Whether this is an all-day event */
+    allDay: boolean;
+    /** Event status: TENTATIVE, CONFIRMED, or CANCELLED */
+    status: EventStatus;
+    /** Creation timestamp in ISO 8601 format */
+    created?: string;
+    /** Last modification timestamp in ISO 8601 format */
+    lastModified?: string;
+}
+export type EventStatus = 'TENTATIVE' | 'CONFIRMED' | 'CANCELLED';
+/**
+ * iCalendar VEVENT component fields
+ */
+export interface ICalEvent {
+    uid: string;
+    dtstamp: Date;
+    dtstart: Date;
+    dtend?: Date;
+    summary: string;
+    description?: string;
+    location?: string;
+    status?: EventStatus;
+    created?: Date;
+    lastModified?: Date;
+    allDay: boolean;
+}
+/**
+ * Parsed iCalendar file structure
+ */
+export interface ICalendar {
+    prodId: string;
+    version: string;
+    calName?: string;
+    timezone?: string;
+    events: ICalEvent[];
+}
+export interface CreateEventParams {
+    /** Event title/summary (required) */
+    title: string;
+    /** Start date/time - ISO 8601 or natural language (required) */
+    start: string;
+    /** End date/time - ISO 8601 or natural language (optional) */
+    end?: string;
+    /** Event location (optional) */
+    location?: string;
+    /** Event description (optional) */
+    description?: string;
+    /** Whether this is an all-day event (optional, default: false) */
+    allDay?: boolean;
+}
+export interface ListEventsParams {
+    /** Filter events starting after this date (optional) */
+    startDate?: string;
+    /** Filter events ending before this date (optional) */
+    endDate?: string;
+    /** Maximum number of events to return (default: 50) */
+    limit?: number;
+    /** Sort order by start date (default: 'asc') */
+    sortOrder?: 'asc' | 'desc';
+}
+export interface UpdateEventParams {
+    /** Event ID to update (required) */
+    id: string;
+    /** New title (optional) */
+    title?: string;
+    /** New start date/time (optional) */
+    start?: string;
+    /** New end date/time (optional) */
+    end?: string;
+    /** New location (optional) */
+    location?: string;
+    /** New description (optional) */
+    description?: string;
+}
+export interface DeleteEventParams {
+    /** Event ID to delete (required) */
+    id: string;
+}
+export interface FindFreeTimeParams {
+    /** Required duration in minutes */
+    duration: number;
+    /** Start of search range - ISO 8601 or natural language */
+    startDate: string;
+    /** End of search range - ISO 8601 or natural language */
+    endDate: string;
+    /** Only search during working hours 9am-5pm (default: true) */
+    workingHoursOnly?: boolean;
+    /** Maximum number of slots to return (default: 5) */
+    maxResults?: number;
+}
+export interface SearchEventsParams {
+    /** Search text - searches title, description, location */
+    query?: string;
+    /** Filter events after this date (optional) */
+    startDate?: string;
+    /** Filter events before this date (optional) */
+    endDate?: string;
+    /** Filter by location (optional) */
+    location?: string;
+    /** Maximum results (default: 20) */
+    limit?: number;
+}
+export interface ListEventsResult {
+    events: CalendarEvent[];
+    count: number;
+    hasMore: boolean;
+}
+export interface FreeSlot {
+    /** Start of free slot in ISO 8601 format */
+    start: string;
+    /** End of free slot in ISO 8601 format */
+    end: string;
+    /** Duration in minutes */
+    durationMinutes: number;
+}
+export interface FindFreeTimeResult {
+    freeSlots: FreeSlot[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/dates.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Parse a date string that can be either ISO 8601 or natural language
+ * @param input - Date string (e.g., "2025-01-25T14:00:00Z" or "tomorrow at 2pm")
+ * @param referenceDate - Reference date for natural language parsing (defaults to now)
+ * @returns Parsed Date object
+ * @throws Error if the date cannot be parsed
+ */
+export declare function parseNaturalDate(input: string, referenceDate?: Date): Date;
+/**
+ * Format a Date object to iCalendar DATE-TIME format (UTC)
+ * Format: YYYYMMDDTHHMMSSZ
+ */
+export declare function formatICalDateTime(date: Date): string;
+/**
+ * Format a Date object to iCalendar DATE format (for all-day events)
+ * Format: YYYYMMDD
+ */
+export declare function formatICalDate(date: Date): string;
+/**
+ * Parse an iCalendar DATE-TIME or DATE string to a Date object
+ * Supports: YYYYMMDDTHHMMSSZ (UTC) or YYYYMMDD (date only)
+ */
+export declare function parseICalDate(icalDate: string): {
+    date: Date;
+    allDay: boolean;
+};
+/**
+ * Add a duration in minutes to a date
+ */
+export declare function addMinutes(date: Date, minutes: number): Date;
+/**
+ * Add hours to a date
+ */
+export declare function addHours(date: Date, hours: number): Date;
+/**
+ * Add days to a date
+ */
+export declare function addDays(date: Date, days: number): Date;
+/**
+ * Format a Date to ISO 8601 string
+ */
+export declare function toISO(date: Date): string;
+/**
+ * Get the start of a day (midnight UTC)
+ */
+export declare function startOfDay(date: Date): Date;
+/**
+ * Get the end of a day (23:59:59.999 UTC)
+ */
+export declare function endOfDay(date: Date): Date;
+/**
+ * Check if two time ranges overlap
+ */
+export declare function rangesOverlap(start1: Date, end1: Date, start2: Date, end2: Date): boolean;
+/**
+ * Format a date for human-readable display
+ */
+export declare function formatForDisplay(date: Date, allDay: boolean): string;

package/dist/utils/dates.js

@@ -0,0 +1,145 @@
+import * as chrono from 'chrono-node';
+/**
+ * Parse a date string that can be either ISO 8601 or natural language
+ * @param input - Date string (e.g., "2025-01-25T14:00:00Z" or "tomorrow at 2pm")
+ * @param referenceDate - Reference date for natural language parsing (defaults to now)
+ * @returns Parsed Date object
+ * @throws Error if the date cannot be parsed
+ */
+export function parseNaturalDate(input, referenceDate) {
+    // First try parsing as ISO 8601
+    const isoDate = new Date(input);
+    if (!isNaN(isoDate.getTime()) && input.includes('-')) {
+        return isoDate;
+    }
+    // Try natural language parsing with chrono
+    const ref = referenceDate ?? new Date();
+    const results = chrono.parse(input, ref, { forwardDate: true });
+    if (results.length === 0) {
+        throw new Error(`Could not parse date: "${input}"`);
+    }
+    const parsed = results[0].start.date();
+    return parsed;
+}
+/**
+ * Format a Date object to iCalendar DATE-TIME format (UTC)
+ * Format: YYYYMMDDTHHMMSSZ
+ */
+export function formatICalDateTime(date) {
+    const year = date.getUTCFullYear();
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(date.getUTCDate()).padStart(2, '0');
+    const hours = String(date.getUTCHours()).padStart(2, '0');
+    const minutes = String(date.getUTCMinutes()).padStart(2, '0');
+    const seconds = String(date.getUTCSeconds()).padStart(2, '0');
+    return `${year}${month}${day}T${hours}${minutes}${seconds}Z`;
+}
+/**
+ * Format a Date object to iCalendar DATE format (for all-day events)
+ * Format: YYYYMMDD
+ */
+export function formatICalDate(date) {
+    const year = date.getUTCFullYear();
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(date.getUTCDate()).padStart(2, '0');
+    return `${year}${month}${day}`;
+}
+/**
+ * Parse an iCalendar DATE-TIME or DATE string to a Date object
+ * Supports: YYYYMMDDTHHMMSSZ (UTC) or YYYYMMDD (date only)
+ */
+export function parseICalDate(icalDate) {
+    // Remove any VALUE=DATE: prefix
+    const cleanDate = icalDate.replace(/^VALUE=DATE:?/, '');
+    // All-day format: YYYYMMDD
+    if (cleanDate.length === 8 && !cleanDate.includes('T')) {
+        const year = parseInt(cleanDate.slice(0, 4), 10);
+        const month = parseInt(cleanDate.slice(4, 6), 10) - 1;
+        const day = parseInt(cleanDate.slice(6, 8), 10);
+        return { date: new Date(Date.UTC(year, month, day)), allDay: true };
+    }
+    // DateTime format: YYYYMMDDTHHMMSSZ or YYYYMMDDTHHMMSS
+    if (cleanDate.includes('T')) {
+        const datePart = cleanDate.slice(0, 8);
+        const timePart = cleanDate.slice(9, 15);
+        const isUtc = cleanDate.endsWith('Z');
+        const year = parseInt(datePart.slice(0, 4), 10);
+        const month = parseInt(datePart.slice(4, 6), 10) - 1;
+        const day = parseInt(datePart.slice(6, 8), 10);
+        const hours = parseInt(timePart.slice(0, 2), 10);
+        const minutes = parseInt(timePart.slice(2, 4), 10);
+        const seconds = parseInt(timePart.slice(4, 6), 10);
+        if (isUtc) {
+            return { date: new Date(Date.UTC(year, month, day, hours, minutes, seconds)), allDay: false };
+        }
+        else {
+            return { date: new Date(year, month, day, hours, minutes, seconds), allDay: false };
+        }
+    }
+    throw new Error(`Invalid iCal date format: "${icalDate}"`);
+}
+/**
+ * Add a duration in minutes to a date
+ */
+export function addMinutes(date, minutes) {
+    return new Date(date.getTime() + minutes * 60 * 1000);
+}
+/**
+ * Add hours to a date
+ */
+export function addHours(date, hours) {
+    return addMinutes(date, hours * 60);
+}
+/**
+ * Add days to a date
+ */
+export function addDays(date, days) {
+    return addMinutes(date, days * 24 * 60);
+}
+/**
+ * Format a Date to ISO 8601 string
+ */
+export function toISO(date) {
+    return date.toISOString();
+}
+/**
+ * Get the start of a day (midnight UTC)
+ */
+export function startOfDay(date) {
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate(), 0, 0, 0, 0));
+}
+/**
+ * Get the end of a day (23:59:59.999 UTC)
+ */
+export function endOfDay(date) {
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate(), 23, 59, 59, 999));
+}
+/**
+ * Check if two time ranges overlap
+ */
+export function rangesOverlap(start1, end1, start2, end2) {
+    return start1 < end2 && end1 > start2;
+}
+/**
+ * Format a date for human-readable display
+ */
+export function formatForDisplay(date, allDay) {
+    if (allDay) {
+        return date.toLocaleDateString('en-US', {
+            weekday: 'long',
+            year: 'numeric',
+            month: 'long',
+            day: 'numeric',
+            timeZone: 'UTC'
+        });
+    }
+    return date.toLocaleString('en-US', {
+        weekday: 'long',
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: '2-digit',
+        timeZoneName: 'short'
+    });
+}

package/dist/utils/git.d.ts

@@ -0,0 +1,35 @@
+import { SimpleGit } from 'simple-git';
+/**
+ * Get the SimpleGit instance for the vault
+ * Uses singleton pattern to reuse the same instance
+ */
+export declare function getGit(): SimpleGit;
+/**
+ * Reset the git instance (useful for testing)
+ */
+export declare function resetGit(): void;
+/**
+ * Commit changes and push to remote
+ * @param message - Commit message
+ * @returns Success status and optional error message
+ */
+export declare function commitAndPush(message: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Get the current git status
+ */
+export declare function getStatus(): Promise<{
+    isRepo: boolean;
+    hasChanges: boolean;
+    ahead: number;
+    behind: number;
+}>;
+/**
+ * Pull latest changes from remote
+ */
+export declare function pull(): Promise<{
+    success: boolean;
+    error?: string;
+}>;

package/dist/utils/git.js

@@ -0,0 +1,88 @@
+import { simpleGit } from 'simple-git';
+import { getVaultPath } from './paths.js';
+let gitInstance = null;
+/**
+ * Get the SimpleGit instance for the vault
+ * Uses singleton pattern to reuse the same instance
+ */
+export function getGit() {
+    if (!gitInstance) {
+        gitInstance = simpleGit(getVaultPath());
+    }
+    return gitInstance;
+}
+/**
+ * Reset the git instance (useful for testing)
+ */
+export function resetGit() {
+    gitInstance = null;
+}
+/**
+ * Commit changes and push to remote
+ * @param message - Commit message
+ * @returns Success status and optional error message
+ */
+export async function commitAndPush(message) {
+    try {
+        const git = getGit();
+        // Check if there are changes to commit
+        const status = await git.status();
+        if (status.files.length === 0) {
+            return { success: true }; // Nothing to commit
+        }
+        // Add all changes in the Calendar folder
+        await git.add('Calendar/*');
+        // Commit with message
+        await git.commit(message);
+        // Try to push (may fail if no remote or offline)
+        try {
+            await git.push();
+        }
+        catch (pushError) {
+            // Push failed, but commit succeeded - that's okay for offline use
+            console.error('Push failed (may be offline):', pushError);
+        }
+        return { success: true };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        return { success: false, error: errorMessage };
+    }
+}
+/**
+ * Get the current git status
+ */
+export async function getStatus() {
+    try {
+        const git = getGit();
+        const status = await git.status();
+        return {
+            isRepo: true,
+            hasChanges: status.files.length > 0,
+            ahead: status.ahead,
+            behind: status.behind,
+        };
+    }
+    catch {
+        return {
+            isRepo: false,
+            hasChanges: false,
+            ahead: 0,
+            behind: 0,
+        };
+    }
+}
+/**
+ * Pull latest changes from remote
+ */
+export async function pull() {
+    try {
+        const git = getGit();
+        await git.pull();
+        return { success: true };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        return { success: false, error: errorMessage };
+    }
+}

package/dist/utils/ical.d.ts

@@ -0,0 +1,47 @@
+import type { CalendarEvent } from '../types.js';
+/**
+ * Generate a unique event ID
+ */
+export declare function generateUID(): string;
+/**
+ * Extract the ID part from a UID (without domain)
+ */
+export declare function extractId(uid: string): string;
+/**
+ * Create a full UID from an ID
+ */
+export declare function createUID(id: string): string;
+/**
+ * Escape special characters for iCal text fields
+ */
+export declare function escapeICalText(text: string): string;
+/**
+ * Unescape special characters from iCal text fields
+ */
+export declare function unescapeICalText(text: string): string;
+/**
+ * Fold long lines according to iCal spec (max 75 chars per line)
+ */
+export declare function foldLine(line: string): string;
+/**
+ * Unfold lines that were folded according to iCal spec
+ */
+export declare function unfoldLines(content: string): string;
+/**
+ * Parse iCalendar content to events
+ */
+export declare function parseICalendar(content: string): CalendarEvent[];
+/**
+ * Generate iCalendar content from events
+ */
+export declare function generateICalendar(events: CalendarEvent[]): string;
+/**
+ * Read the calendar file and return parsed events
+ * Returns empty array if file doesn't exist
+ */
+export declare function readCalendarFile(): Promise<CalendarEvent[]>;
+/**
+ * Write events to the calendar file
+ * Creates the Calendar directory if it doesn't exist
+ */
+export declare function writeCalendarFile(events: CalendarEvent[]): Promise<void>;