dav-mcp 3.0.0

package/src/tools/todos/todo-query.js

@@ -0,0 +1,112 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput, todoQuerySchema } from '../../validation.js';
+import { formatTodoList } from '../../formatters.js';
+
+/**
+ * Search and filter todos efficiently
+ */
+export const todoQuery = {
+  name: 'todo_query',
+  description: '⭐ PREFERRED: Search and filter todos efficiently. Use instead of list_todos to conserve tokens. Omit calendar_url to search across ALL calendars automatically.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      calendar_url: {
+        type: 'string',
+        description: 'Optional: Specific calendar URL. Omit to search ALL calendars (recommended).',
+      },
+      summary_filter: {
+        type: 'string',
+        description: 'Search todo summaries/titles containing this text (case-insensitive). Example: "write report" or "review PR". Can be used alone as sufficient filter.',
+      },
+      status_filter: {
+        type: 'string',
+        enum: ['NEEDS-ACTION', 'IN-PROCESS', 'COMPLETED', 'CANCELLED'],
+        description: 'Filter by todo status. Use "NEEDS-ACTION" for pending tasks, "COMPLETED" for done tasks. Can be used alone as sufficient filter.',
+      },
+      time_range_start: {
+        type: 'string',
+        description: 'Start datetime for due date filtering (ISO 8601). If provided, time_range_end is REQUIRED. Both dates together form a complete filter.',
+      },
+      time_range_end: {
+        type: 'string',
+        description: 'End datetime for due date filtering (ISO 8601). If provided, time_range_start is REQUIRED. Both dates together form a complete filter.',
+      },
+    },
+    required: [],
+  },
+  handler: async (args) => {
+    const validated = validateInput(todoQuerySchema, args);
+    const client = tsdavManager.getCalDavClient();
+    const calendars = await client.fetchCalendars();
+
+    // If specific calendar requested, use it
+    let calendarsToSearch = calendars;
+    if (validated.calendar_url) {
+      const calendar = calendars.find(c => c.url === validated.calendar_url);
+      if (!calendar) {
+        const availableUrls = calendars.map(c => c.url).join('\n- ');
+        throw new Error(
+          `Calendar not found: ${validated.calendar_url}\n\n` +
+          `Available calendar URLs:\n- ${availableUrls}\n\n` +
+          `Tip: Omit calendar_url to search across all calendars automatically.`
+        );
+      }
+      calendarsToSearch = [calendar];
+    }
+
+    // Fetch todos from all selected calendars
+    let todos = [];
+    for (const calendar of calendarsToSearch) {
+      const calendarTodos = await client.fetchTodos({ calendar });
+      // Add calendar info to each todo
+      calendarTodos.forEach(todo => {
+        todo._calendarName = calendar.displayName || calendar.url;
+      });
+      todos = todos.concat(calendarTodos);
+    }
+
+    // Client-side filtering (tsdav doesn't support server-side VTODO filtering yet)
+    if (validated.summary_filter) {
+      const summaryLower = validated.summary_filter.toLowerCase();
+      todos = todos.filter(todo => {
+        const summary = todo.data?.match(/SUMMARY:(.+)/)?.[1] || '';
+        return summary.toLowerCase().includes(summaryLower);
+      });
+    }
+
+    if (validated.status_filter) {
+      todos = todos.filter(todo => {
+        const status = todo.data?.match(/STATUS:(.+)/)?.[1] || 'NEEDS-ACTION';
+        return status === validated.status_filter;
+      });
+    }
+
+    if (validated.time_range_start && validated.time_range_end) {
+      const startTime = new Date(validated.time_range_start).getTime();
+      const endTime = new Date(validated.time_range_end).getTime();
+
+      todos = todos.filter(todo => {
+        const dueMatch = todo.data?.match(/DUE:(\d{8}T\d{6}Z?)/);
+        if (!dueMatch) return false;
+
+        const dueStr = dueMatch[1];
+        const year = parseInt(dueStr.substr(0, 4));
+        const month = parseInt(dueStr.substr(4, 2)) - 1;
+        const day = parseInt(dueStr.substr(6, 2));
+        const hour = parseInt(dueStr.substr(9, 2));
+        const minute = parseInt(dueStr.substr(11, 2));
+        const dueTime = new Date(Date.UTC(year, month, day, hour, minute)).getTime();
+
+        return dueTime >= startTime && dueTime <= endTime;
+      });
+    }
+
+    // Determine calendar name for display
+    const calendarName = calendarsToSearch.length === 1
+      ? (calendarsToSearch[0].displayName || calendarsToSearch[0].url)
+      : `All Calendars (${calendarsToSearch.length})`;
+
+    return formatTodoList(todos, calendarName);
+  },
+};

package/src/tools/todos/update-todo-fields.js

@@ -0,0 +1,119 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput } from '../../validation.js';
+import { formatSuccess, formatError } from '../../formatters.js';
+import { z } from 'zod';
+import { updateFields } from 'tsdav-utils';
+
+/**
+ * Schema for field-based todo updates
+ * Supports all RFC 5545 VTODO properties via tsdav-utils
+ * Common fields: SUMMARY, DESCRIPTION, STATUS, PRIORITY, DUE, PERCENT-COMPLETE
+ * Custom properties: Any X-* property
+ */
+const updateTodoFieldsSchema = z.object({
+  todo_url: z.string().url('Todo URL must be a valid URL'),
+  todo_etag: z.string().min(1, 'Todo etag is required'),
+  fields: z.record(z.string()).optional()
+});
+
+/**
+ * Field-agnostic todo update tool powered by tsdav-utils
+ * Supports all RFC 5545 VTODO properties without validation
+ *
+ * Features:
+ * - Any standard VTODO property (SUMMARY, DESCRIPTION, STATUS, PRIORITY, DUE, etc.)
+ * - Custom X-* properties for extensions
+ * - Field-agnostic: no pre-defined field list required
+ */
+export const updateTodoFields = {
+  name: 'update_todo',
+  description: 'PREFERRED: Update todo fields without iCal formatting. Supports: SUMMARY (title), DESCRIPTION (details), STATUS (NEEDS-ACTION/IN-PROCESS/COMPLETED/CANCELLED), PRIORITY (0-9), DUE (due date), PERCENT-COMPLETE (0-100), and any RFC 5545 VTODO property including custom X-* properties.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      todo_url: {
+        type: 'string',
+        description: 'The URL of the todo to update'
+      },
+      todo_etag: {
+        type: 'string',
+        description: 'The etag of the todo (required for conflict detection)'
+      },
+      fields: {
+        type: 'object',
+        description: 'Fields to update - use UPPERCASE property names (e.g., SUMMARY, STATUS, PRIORITY). Any RFC 5545 VTODO property or custom X-* property is supported.',
+        additionalProperties: {
+          type: 'string'
+        },
+        properties: {
+          SUMMARY: {
+            type: 'string',
+            description: 'Todo title/summary'
+          },
+          DESCRIPTION: {
+            type: 'string',
+            description: 'Todo description/details'
+          },
+          STATUS: {
+            type: 'string',
+            description: 'Todo status: NEEDS-ACTION, IN-PROCESS, COMPLETED, or CANCELLED'
+          },
+          PRIORITY: {
+            type: 'string',
+            description: 'Priority level: 0 (undefined), 1 (highest) to 9 (lowest)'
+          },
+          DUE: {
+            type: 'string',
+            description: 'Due date (ISO 8601 or iCal format: 20250128T100000Z)'
+          },
+          'PERCENT-COMPLETE': {
+            type: 'string',
+            description: 'Completion percentage: 0-100'
+          }
+        }
+      }
+    },
+    required: ['todo_url', 'todo_etag']
+  },
+  handler: async (args) => {
+    try {
+      const validated = validateInput(updateTodoFieldsSchema, args);
+      const client = tsdavManager.getCalDavClient();
+
+      // Step 1: Fetch the current todo from server
+      const calendarUrl = validated.todo_url.substring(0, validated.todo_url.lastIndexOf('/') + 1);
+      const currentTodos = await client.fetchTodos({
+        calendar: { url: calendarUrl },
+        objectUrls: [validated.todo_url]
+      });
+
+      if (!currentTodos || currentTodos.length === 0) {
+        throw new Error('Todo not found');
+      }
+
+      const todoObject = currentTodos[0];
+
+      // Step 2: Update fields using tsdav-utils (field-agnostic)
+      // Accepts any RFC 5545 VTODO property name (UPPERCASE)
+      const updatedData = updateFields(todoObject, validated.fields || {});
+
+      // Step 3: Send the updated todo back to server
+      const updateResponse = await client.updateTodo({
+        todo: {
+          url: validated.todo_url,
+          data: updatedData,
+          etag: validated.todo_etag
+        }
+      });
+
+      return formatSuccess('Todo updated successfully', {
+        etag: updateResponse.etag,
+        updated_fields: Object.keys(validated.fields || {}),
+        message: `Updated ${Object.keys(validated.fields || {}).length} field(s): ${Object.keys(validated.fields || {}).join(', ')}`
+      });
+
+    } catch (error) {
+      return formatError('update_todo', error);
+    }
+  }
+};

package/src/tools/todos/update-todo-raw.js

@@ -0,0 +1,46 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput, updateTodoSchema } from '../../validation.js';
+import { formatSuccess } from '../../formatters.js';
+
+/**
+ * Update an existing todo/task with raw VTODO iCal data
+ */
+export const updateTodoRaw = {
+  name: 'update_todo_raw',
+  description: 'ADVANCED: Update todo with raw VTODO iCal data. Requires manual iCal formatting - use update_todo instead for simple field updates (summary, description, status). Only use this if you have complete pre-formatted VTODO data or need to update advanced iCal properties.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      todo_url: {
+        type: 'string',
+        description: 'The URL of the todo to update',
+      },
+      todo_etag: {
+        type: 'string',
+        description: 'The current ETag of the todo (required for conflict detection)',
+      },
+      updated_ical_data: {
+        type: 'string',
+        description: 'Complete updated VTODO iCalendar data',
+      },
+    },
+    required: ['todo_url', 'todo_etag', 'updated_ical_data'],
+  },
+  handler: async (args) => {
+    const validated = validateInput(updateTodoSchema, args);
+    const client = tsdavManager.getCalDavClient();
+
+    const result = await client.updateTodo({
+      todo: {
+        url: validated.todo_url,
+        data: validated.updated_ical_data,
+        etag: validated.todo_etag,
+      },
+    });
+
+    return formatSuccess('Todo updated successfully', {
+      url: result.url,
+      etag: result.etag,
+    });
+  },
+};

package/src/tsdav-client.js

@@ -0,0 +1,199 @@
+import { DAVClient } from 'tsdav';
+import { logger } from './logger.js';
+import { CalDAVError, CardDAVError } from './error-handler.js';
+
+/**
+ * Singleton CalDAV/CardDAV Client Manager
+ *
+ * Supports both Basic Auth and OAuth2 authentication:
+ * - Basic Auth: Standard CalDAV servers (Radicale, Baikal, Nextcloud)
+ * - OAuth2: Google Calendar and other OAuth2-enabled CalDAV servers
+ */
+class TsdavClientManager {
+  constructor() {
+    this.calDavClient = null;
+    this.cardDavClient = null;
+    this.config = null;
+    this.authMethod = null;
+  }
+
+  /**
+   * Initialize clients with configuration
+   *
+   * @param {Object} config - Client configuration
+   * @param {string} config.serverUrl - CalDAV/CardDAV server URL
+   * @param {string} config.authMethod - 'Basic' or 'OAuth' (note: tsdav uses 'Oauth')
+   *
+   * For Basic Auth:
+   * @param {string} config.username - Username
+   * @param {string} config.password - Password
+   *
+   * For OAuth2:
+   * @param {string} config.username - User email (for OAuth2)
+   * @param {string} config.clientId - OAuth2 client ID
+   * @param {string} config.clientSecret - OAuth2 client secret
+   * @param {string} config.refreshToken - OAuth2 refresh token
+   * @param {string} config.tokenUrl - OAuth2 token endpoint (default: Google's)
+   */
+  async initialize(config) {
+    this.config = config;
+    this.authMethod = config.authMethod || 'Basic';
+
+    try {
+      // Determine authentication method
+      const useOAuth = this.authMethod === 'OAuth' || this.authMethod === 'Oauth';
+
+      if (useOAuth) {
+        logger.info({ serverUrl: config.serverUrl }, 'Initializing tsdav clients with OAuth2');
+        await this._initializeOAuth(config);
+      } else {
+        logger.info({ serverUrl: config.serverUrl }, 'Initializing tsdav clients with Basic Auth');
+        await this._initializeBasicAuth(config);
+      }
+
+      logger.info({
+        serverUrl: config.serverUrl,
+        authMethod: this.authMethod
+      }, 'tsdav clients initialized and logged in');
+    } catch (error) {
+      logger.error({
+        error: error.message,
+        serverUrl: config.serverUrl,
+        authMethod: this.authMethod
+      }, 'Failed to initialize tsdav clients');
+      throw error;
+    }
+  }
+
+  /**
+   * Initialize clients with Basic Authentication
+   * @private
+   */
+  async _initializeBasicAuth(config) {
+    // Validate required fields
+    if (!config.username || !config.password) {
+      throw new Error('Basic Auth requires username and password');
+    }
+
+    // CalDAV Client
+    this.calDavClient = new DAVClient({
+      serverUrl: config.serverUrl,
+      credentials: {
+        username: config.username,
+        password: config.password,
+      },
+      authMethod: 'Basic',
+      defaultAccountType: 'caldav',
+    });
+
+    // CardDAV Client
+    this.cardDavClient = new DAVClient({
+      serverUrl: config.serverUrl,
+      credentials: {
+        username: config.username,
+        password: config.password,
+      },
+      authMethod: 'Basic',
+      defaultAccountType: 'carddav',
+    });
+
+    // Login to both clients
+    await this.calDavClient.login();
+    logger.debug({ accountType: 'caldav' }, 'CalDAV client logged in (Basic Auth)');
+
+    await this.cardDavClient.login();
+    logger.debug({ accountType: 'carddav' }, 'CardDAV client logged in (Basic Auth)');
+  }
+
+  /**
+   * Initialize clients with OAuth2 Authentication
+   * @private
+   */
+  async _initializeOAuth(config) {
+    // Validate required OAuth fields
+    if (!config.username) {
+      throw new Error('OAuth requires username (user email)');
+    }
+    if (!config.clientId || !config.clientSecret || !config.refreshToken) {
+      throw new Error('OAuth requires clientId, clientSecret, and refreshToken');
+    }
+
+    // Default to Google's token endpoint if not specified
+    const tokenUrl = config.tokenUrl || 'https://accounts.google.com/o/oauth2/token';
+
+    const oauthCredentials = {
+      tokenUrl,
+      username: config.username,
+      refreshToken: config.refreshToken,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    };
+
+    logger.debug({
+      username: config.username,
+      tokenUrl,
+      serverUrl: config.serverUrl
+    }, 'Configuring OAuth2 credentials');
+
+    // CalDAV Client with OAuth
+    this.calDavClient = new DAVClient({
+      serverUrl: config.serverUrl,
+      credentials: oauthCredentials,
+      authMethod: 'Oauth', // Note: tsdav expects 'Oauth' with capital O
+      defaultAccountType: 'caldav',
+    });
+
+    // CardDAV Client with OAuth
+    // Note: Google Calendar doesn't support CardDAV, but we initialize it anyway
+    // for compatibility with other OAuth2 CalDAV/CardDAV servers
+    this.cardDavClient = new DAVClient({
+      serverUrl: config.serverUrl,
+      credentials: oauthCredentials,
+      authMethod: 'Oauth',
+      defaultAccountType: 'carddav',
+    });
+
+    // Login to CalDAV client
+    await this.calDavClient.login();
+    logger.debug({ accountType: 'caldav' }, 'CalDAV client logged in (OAuth2)');
+
+    // Try to login to CardDAV client, but don't fail if it doesn't work
+    // (Google Calendar doesn't support CardDAV)
+    try {
+      await this.cardDavClient.login();
+      logger.debug({ accountType: 'carddav' }, 'CardDAV client logged in (OAuth2)');
+    } catch (error) {
+      logger.warn({
+        error: error.message
+      }, 'CardDAV login failed (expected for Google Calendar)');
+      // Don't throw - CardDAV is optional for OAuth2 providers like Google
+    }
+  }
+
+  /**
+   * Get CalDAV client
+   */
+  getCalDavClient() {
+    if (!this.calDavClient) {
+      const error = new CalDAVError('CalDAV client not initialized. Call initialize() first.');
+      logger.error('CalDAV client not initialized');
+      throw error;
+    }
+    return this.calDavClient;
+  }
+
+  /**
+   * Get CardDAV client
+   */
+  getCardDavClient() {
+    if (!this.cardDavClient) {
+      const error = new CardDAVError('CardDAV client not initialized. Call initialize() first.');
+      logger.error('CardDAV client not initialized');
+      throw error;
+    }
+    return this.cardDavClient;
+  }
+}
+
+// Export singleton instance
+export const tsdavManager = new TsdavClientManager();