dav-mcp 3.0.0

package/src/utils/tool-helpers.js

@@ -0,0 +1,388 @@
+/**
+ * Shared helper functions for tsdav MCP tools
+ * This module eliminates code duplication across calendar, contact, and todo operations
+ */
+
+/**
+ * Escapes special XML characters to prevent injection attacks
+ * @param {string} text - Text to escape
+ * @returns {string} XML-safe string
+ */
+function escapeXml(text) {
+  if (!text) return '';
+  return text
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Validates and retrieves a calendar by URL
+ *
+ * @param {Object} client - The CalDAV client instance
+ * @param {string} calendarUrl - The URL of the calendar to find
+ * @returns {Promise<Object>} The validated calendar object
+ * @throws {Error} If calendar is not found with helpful error message
+ *
+ * @example
+ * const calendar = await getValidatedCalendar(client, 'https://dav.example.com/cal/user/work/');
+ */
+export async function getValidatedCalendar(client, calendarUrl) {
+  const calendars = await client.fetchCalendars();
+  const calendar = calendars.find(c => c.url === calendarUrl);
+
+  if (!calendar) {
+    const availableUrls = calendars.map(c => c.url).join('\n- ');
+    throw new Error(
+      `Calendar not found: ${calendarUrl}\n\n` +
+      `Available calendar URLs:\n- ${availableUrls}\n\n` +
+      `Please use list_calendars first to get the correct calendar URLs.`
+    );
+  }
+
+  return calendar;
+}
+
+/**
+ * Validates and retrieves an address book by URL
+ *
+ * @param {Object} client - The CardDAV client instance
+ * @param {string} addressBookUrl - The URL of the address book to find
+ * @returns {Promise<Object>} The validated address book object
+ * @throws {Error} If address book is not found with helpful error message
+ *
+ * @example
+ * const addressBook = await getValidatedAddressBook(client, 'https://dav.example.com/card/user/contacts/');
+ */
+export async function getValidatedAddressBook(client, addressBookUrl) {
+  const addressBooks = await client.fetchAddressBooks();
+  const addressBook = addressBooks.find(ab => ab.url === addressBookUrl);
+
+  if (!addressBook) {
+    const availableUrls = addressBooks.map(ab => ab.url).join('\n- ');
+    throw new Error(
+      `Address book not found: ${addressBookUrl}\n\n` +
+      `Available address book URLs:\n- ${availableUrls}\n\n` +
+      `Please use list_addressbooks first to get the correct address book URLs.`
+    );
+  }
+
+  return addressBook;
+}
+
+/**
+ * Builds time range options for CalDAV queries
+ * If only start date is provided, defaults end date to 1 year from start
+ *
+ * @param {string|undefined} startDate - Optional start date in ISO 8601 format
+ * @param {string|undefined} endDate - Optional end date in ISO 8601 format
+ * @returns {Object} Options object with timeRange property (or empty object if no dates)
+ *
+ * @example
+ * // Both dates provided
+ * buildTimeRangeOptions('2025-01-01T00:00:00.000Z', '2025-12-31T23:59:59.000Z')
+ * // Returns: { timeRange: { start: '2025-01-01...', end: '2025-12-31...' } }
+ *
+ * // Only start date (end = start + 1 year)
+ * buildTimeRangeOptions('2025-01-01T00:00:00.000Z', undefined)
+ * // Returns: { timeRange: { start: '2025-01-01...', end: '2026-01-01...' } }
+ *
+ * // No dates
+ * buildTimeRangeOptions(undefined, undefined)
+ * // Returns: {}
+ */
+export function buildTimeRangeOptions(startDate, endDate) {
+  // No time range specified
+  if (!startDate) {
+    return {};
+  }
+
+  // Only start date provided - default end to 1 year from start
+  if (!endDate) {
+    const start = new Date(startDate);
+    const end = new Date(start);
+    end.setFullYear(end.getFullYear() + 1);
+
+    return {
+      timeRange: {
+        start: startDate,
+        end: end.toISOString(),
+      },
+    };
+  }
+
+  // Both dates provided
+  return {
+    timeRange: {
+      start: startDate,
+      end: endDate,
+    },
+  };
+}
+
+/**
+ * Searches multiple calendars and aggregates results with calendar name annotations
+ *
+ * @param {Object} client - The CalDAV client instance
+ * @param {Array<Object>} calendars - Array of calendar objects to search
+ * @param {Object} fetchOptions - Options to pass to fetchCalendarObjects (e.g., timeRange)
+ * @returns {Promise<Array>} All events/todos from all calendars with _calendarName property
+ *
+ * @example
+ * const calendars = [cal1, cal2, cal3];
+ * const events = await searchMultipleCalendars(client, calendars, { timeRange: {...} });
+ * // Each event has event._calendarName = "Work Calendar" etc.
+ */
+export async function searchMultipleCalendars(client, calendars, fetchOptions = {}) {
+  let allItems = [];
+
+  for (const calendar of calendars) {
+    const options = { calendar, ...fetchOptions };
+    const items = await client.fetchCalendarObjects(options);
+
+    // Add calendar info to each item for display
+    items.forEach(item => {
+      item._calendarName = calendar.displayName || calendar.url;
+    });
+
+    allItems = allItems.concat(items);
+  }
+
+  return allItems;
+}
+
+/**
+ * Searches multiple calendars for todos and aggregates results
+ *
+ * @param {Object} client - The CalDAV client instance
+ * @param {Array<Object>} calendars - Array of calendar objects to search
+ * @returns {Promise<Array>} All todos from all calendars with _calendarName property
+ *
+ * @example
+ * const calendars = [cal1, cal2];
+ * const todos = await searchMultipleTodoCalendars(client, calendars);
+ */
+export async function searchMultipleTodoCalendars(client, calendars) {
+  let allTodos = [];
+
+  for (const calendar of calendars) {
+    const todos = await client.fetchTodos({ calendar });
+
+    // Add calendar info to each todo
+    todos.forEach(todo => {
+      todo._calendarName = calendar.displayName || calendar.url;
+    });
+
+    allTodos = allTodos.concat(todos);
+  }
+
+  return allTodos;
+}
+
+/**
+ * Builds WebDAV PROPPATCH XML for updating calendar properties
+ * Uses proper XML escaping to prevent injection attacks
+ *
+ * @param {Object} properties - Object with optional display_name, description, color, timezone
+ * @returns {string} Complete PROPPATCH XML string
+ * @throws {Error} If timezone format is invalid
+ *
+ * @example
+ * const xml = buildPropPatchXml({
+ *   display_name: 'My Calendar',
+ *   description: 'Work & Projects',
+ *   color: '#FF5733',
+ *   timezone: 'Europe/Berlin'
+ * });
+ */
+export function buildPropPatchXml(properties) {
+  const { display_name, description, color, timezone } = properties;
+
+  // Validate timezone format if provided
+  if (timezone && !timezone.includes('/')) {
+    throw new Error(
+      `Invalid timezone format: ${timezone}. ` +
+      `Expected format: "Europe/Berlin", "America/New_York", etc.`
+    );
+  }
+
+  let xml = '<?xml version="1.0" encoding="UTF-8"?>\n';
+  xml += '<d:propertyupdate xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav" xmlns:x="http://apple.com/ns/ical/">\n';
+  xml += '  <d:set>\n';
+  xml += '    <d:prop>\n';
+
+  if (display_name) {
+    xml += `      <d:displayname>${escapeXml(display_name)}</d:displayname>\n`;
+  }
+  if (description) {
+    xml += `      <c:calendar-description>${escapeXml(description)}</c:calendar-description>\n`;
+  }
+  if (color) {
+    xml += `      <x:calendar-color>${escapeXml(color)}</x:calendar-color>\n`;
+  }
+  if (timezone) {
+    xml += `      <c:calendar-timezone>${escapeXml(timezone)}</c:calendar-timezone>\n`;
+  }
+
+  xml += '    </d:prop>\n';
+  xml += '  </d:set>\n';
+  xml += '</d:propertyupdate>';
+
+  return xml;
+}
+
+/**
+ * Generic filter function for events, contacts, or todos
+ * Applies multiple filters with case-insensitive substring matching
+ *
+ * @param {Array<Object>} items - Array of items to filter (events/contacts/todos)
+ * @param {Object} filters - Object with filter values
+ * @param {Object} extractors - Object mapping filter keys to regex extractors
+ * @returns {Array<Object>} Filtered items
+ *
+ * @example
+ * // Filter events by summary and location
+ * const filtered = applyFilters(
+ *   events,
+ *   { summary_filter: 'meeting', location_filter: 'room' },
+ *   {
+ *     summary_filter: /SUMMARY:(.+)/,
+ *     location_filter: /LOCATION:(.+)/
+ *   }
+ * );
+ */
+export function applyFilters(items, filters, extractors) {
+  let filtered = items;
+
+  for (const [filterKey, filterValue] of Object.entries(filters)) {
+    if (!filterValue || !extractors[filterKey]) continue;
+
+    const regex = extractors[filterKey];
+    const searchLower = filterValue.toLowerCase();
+
+    filtered = filtered.filter(item => {
+      const match = item.data?.match(regex);
+      const value = match?.[1] || '';
+      return value.toLowerCase().includes(searchLower);
+    });
+  }
+
+  return filtered;
+}
+
+/**
+ * Resolves which calendars to search based on optional calendar_url parameter
+ * If calendar_url is provided, validates and returns single calendar in array
+ * Otherwise returns all calendars
+ *
+ * @param {Object} client - The CalDAV client instance
+ * @param {string|undefined} calendarUrl - Optional specific calendar URL
+ * @returns {Promise<Array<Object>>} Array of calendars to search
+ * @throws {Error} If specific calendar not found
+ *
+ * @example
+ * // Search specific calendar
+ * const calendars = await resolveCalendarsToSearch(client, 'https://...');
+ * // Returns: [specificCalendar]
+ *
+ * // Search all calendars
+ * const calendars = await resolveCalendarsToSearch(client, undefined);
+ * // Returns: [cal1, cal2, cal3, ...]
+ */
+export async function resolveCalendarsToSearch(client, calendarUrl) {
+  const calendars = await client.fetchCalendars();
+
+  // Search all calendars if no specific URL provided
+  if (!calendarUrl) {
+    return calendars;
+  }
+
+  // Find specific calendar
+  const calendar = calendars.find(c => c.url === calendarUrl);
+
+  if (!calendar) {
+    const availableUrls = calendars.map(c => c.url).join('\n- ');
+    throw new Error(
+      `Calendar not found: ${calendarUrl}\n\n` +
+      `Available calendar URLs:\n- ${availableUrls}\n\n` +
+      `Tip: Omit calendar_url to search across all calendars automatically.`
+    );
+  }
+
+  return [calendar];
+}
+
+/**
+ * Generates display name for single or multi-calendar searches
+ *
+ * @param {Array<Object>} calendars - Array of calendars that were searched
+ * @returns {string} Display name for formatter
+ *
+ * @example
+ * getCalendarDisplayName([cal1]) // Returns: "Work Calendar"
+ * getCalendarDisplayName([cal1, cal2, cal3]) // Returns: "All Calendars (3)"
+ */
+export function getCalendarDisplayName(calendars) {
+  if (calendars.length === 1) {
+    return calendars[0].displayName || calendars[0].url;
+  }
+  return `All Calendars (${calendars.length})`;
+}
+
+/**
+ * Resolves which address books to search based on optional URL
+ *
+ * @param {Object} client - The DAV client
+ * @param {string} [addressbookUrl] - Optional specific address book URL
+ * @returns {Promise<Array<Object>>} Array of address books to search
+ *
+ * @example
+ * // Search specific address book
+ * const addressbooks = await resolveAddressBooksToSearch(client, 'http://example.com/addressbook');
+ * // Returns: [addressbook1]
+ *
+ * // Search all address books
+ * const addressbooks = await resolveAddressBooksToSearch(client, undefined);
+ * // Returns: [addressbook1, addressbook2, addressbook3, ...]
+ */
+export async function resolveAddressBooksToSearch(client, addressbookUrl) {
+  const addressbooks = await client.fetchAddressBooks();
+
+  // Search all address books if no specific URL provided
+  if (!addressbookUrl) {
+    return addressbooks;
+  }
+
+  // Find specific address book
+  const addressbook = addressbooks.find(a => a.url === addressbookUrl);
+
+  if (!addressbook) {
+    const availableUrls = addressbooks.map(a => a.url).join('\n- ');
+    throw new Error(
+      `Address book not found: ${addressbookUrl}\n\n` +
+      `Available address book URLs:\n- ${availableUrls}\n\n` +
+      `Tip: Omit addressbook_url to search across all address books automatically.`
+    );
+  }
+
+  return [addressbook];
+}
+
+/**
+ * Generates display name for single or multi-addressbook searches
+ *
+ * @param {Array<Object>} addressbooks - Array of address books that were searched
+ * @returns {string} Display name for formatter
+ *
+ * @example
+ * getAddressBookDisplayName([book1]) // Returns: "Personal Contacts"
+ * getAddressBookDisplayName([book1, book2, book3]) // Returns: "All Address Books (3)"
+ */
+export function getAddressBookDisplayName(addressbooks) {
+  if (addressbooks.length === 1) {
+    return addressbooks[0].displayName || addressbooks[0].url;
+  }
+  return `All Address Books (${addressbooks.length})`;
+}

package/src/validation.js

@@ -0,0 +1,245 @@
+import { z } from 'zod';
+
+/**
+ * Validation schemas for all MCP tools
+ */
+
+// Helper: DateTime string with optional timezone offset
+// Accepts both "2026-03-02T09:00:00Z" and "2026-03-02T09:00:00"
+const dateTimeWithOptionalOffset = z.union([
+  z.string().datetime({ offset: true }), // With timezone (Z or +00:00)
+  z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/, 'Invalid datetime format') // Without timezone
+]);
+
+// Helper: Optional URL that gracefully handles LLM placeholder values
+// Transforms common LLM-generated placeholders ("", "unknown", "default", etc.) to undefined
+const optionalUrl = (message) =>
+  z.preprocess(
+    (val) => {
+      // Transform common LLM placeholder values to undefined
+      if (!val ||
+          val === '' ||
+          val === 'null' ||
+          val === 'undefined' ||
+          val === 'unknown' ||
+          val === 'default' ||
+          val === 'none' ||
+          val === 'N/A' ||
+          val === 'n/a') {
+        return undefined;
+      }
+      return val;
+    },
+    z.string().url(message).optional()
+  );
+
+// CalDAV Schemas
+export const listCalendarsSchema = z.object({});
+
+export const listEventsSchema = z.object({
+  calendar_url: optionalUrl('Invalid calendar URL'),
+  time_range_start: dateTimeWithOptionalOffset.optional(),
+  time_range_end: dateTimeWithOptionalOffset.optional(),
+});
+
+export const createEventSchema = z.object({
+  calendar_url: z.string().url('Invalid calendar URL'),
+  summary: z.string().min(1, 'Summary is required').max(500),
+  start_date: dateTimeWithOptionalOffset,
+  end_date: dateTimeWithOptionalOffset,
+  description: z.string().max(5000).optional(),
+  location: z.string().max(500).optional(),
+}).refine((data) => new Date(data.end_date) > new Date(data.start_date), {
+  message: 'End date must be after start date',
+  path: ['end_date'],
+});
+
+export const updateEventSchema = z.object({
+  event_url: z.string().url('Invalid event URL'),
+  event_etag: z.string().min(1, 'ETag is required'),
+  updated_ical_data: z.string().min(1, 'iCal data is required'),
+});
+
+export const deleteEventSchema = z.object({
+  event_url: z.string().url('Invalid event URL'),
+  event_etag: z.string().min(1, 'ETag is required'),
+});
+
+export const calendarQuerySchema = z.object({
+  calendar_url: optionalUrl('Invalid calendar URL'),
+  time_range_start: dateTimeWithOptionalOffset.optional(),
+  time_range_end: dateTimeWithOptionalOffset.optional(),
+  summary_filter: z.string().optional(),
+  location_filter: z.string().optional(),
+}).refine((data) => {
+  // Rule 1: If ANY time field used, BOTH must be present
+  if (data.time_range_start || data.time_range_end) {
+    return data.time_range_start && data.time_range_end;
+  }
+
+  // Rule 2: At least ONE filter type must exist
+  return !!(data.calendar_url ||
+            data.summary_filter ||
+            data.location_filter);
+}, {
+  message: "Provide: (time_range with BOTH dates) OR (text filter) OR (both)"
+});
+
+export const makeCalendarSchema = z.object({
+  display_name: z.string().min(1, 'Display name is required').max(200),
+  description: z.string().max(500).optional(),
+  color: z.string().regex(/^#[0-9A-Fa-f]{6}$/).optional(),
+  timezone: z.string().optional(),
+  components: z.array(z.enum(['VEVENT', 'VTODO', 'VJOURNAL'])).optional(),
+});
+
+export const updateCalendarSchema = z.object({
+  calendar_url: z.string().url('Invalid calendar URL'),
+  display_name: z.string().min(1).max(200).optional(),
+  description: z.string().max(500).optional(),
+  color: z.string().regex(/^#[0-9A-Fa-f]{6}$/).optional(),
+  timezone: z.string().optional(),
+}).refine(data => {
+  // At least one field must be provided for update
+  return data.display_name || data.description || data.color || data.timezone;
+}, {
+  message: 'At least one field (display_name, description, color, or timezone) must be provided for update',
+});
+
+export const deleteCalendarSchema = z.object({
+  calendar_url: z.string().url('Invalid calendar URL'),
+});
+
+export const calendarMultiGetSchema = z.object({
+  calendar_url: z.string().url('Invalid calendar URL'),
+  event_urls: z.array(z.string().url('Invalid event URL')).min(1, 'At least one event URL required'),
+});
+
+// CardDAV Schemas
+export const listAddressbooksSchema = z.object({});
+
+export const listContactsSchema = z.object({
+  addressbook_url: z.string().url('Invalid addressbook URL'),
+});
+
+export const createContactSchema = z.object({
+  addressbook_url: z.string().url('Invalid addressbook URL'),
+  full_name: z.string().min(1, 'Full name is required').max(200),
+  family_name: z.string().max(100).optional(),
+  given_name: z.string().max(100).optional(),
+  email: z.string().email('Invalid email format').optional(),
+  phone: z.string().max(50).optional(),
+  organization: z.string().max(200).optional(),
+  note: z.string().max(1000).optional(),
+});
+
+export const updateContactSchema = z.object({
+  vcard_url: z.string().url('Invalid vCard URL'),
+  vcard_etag: z.string().min(1, 'ETag is required'),
+  updated_vcard_data: z.string().min(1, 'vCard data is required'),
+});
+
+export const deleteContactSchema = z.object({
+  vcard_url: z.string().url('Invalid vCard URL'),
+  vcard_etag: z.string().min(1, 'ETag is required'),
+});
+
+export const addressBookQuerySchema = z.object({
+  addressbook_url: optionalUrl('Invalid addressbook URL'),
+  name_filter: z.string().optional(),
+  email_filter: z.string().optional(),
+  organization_filter: z.string().optional(),
+}).refine((data) => {
+  // At least one filter required
+  return !!(data.name_filter ||
+            data.email_filter ||
+            data.organization_filter);
+}, {
+  message: "At least one filter required: name_filter, email_filter, or organization_filter"
+});
+
+export const addressBookMultiGetSchema = z.object({
+  addressbook_url: z.string().url('Invalid addressbook URL'),
+  contact_urls: z.array(z.string().url('Invalid contact URL')).min(1, 'At least one contact URL required'),
+});
+
+// VTODO (Task) Schemas
+export const listTodosSchema = z.object({
+  calendar_url: z.string().url('Invalid calendar URL'),
+});
+
+export const createTodoSchema = z.object({
+  calendar_url: z.string().url('Invalid calendar URL'),
+  summary: z.string().min(1, 'Summary is required').max(500),
+  description: z.string().max(5000).optional(),
+  due_date: z.string().optional(), // ISO 8601 with timezone
+  priority: z.number().int().min(0).max(9).optional(), // 0=undefined, 1=highest, 9=lowest
+  status: z.enum(['NEEDS-ACTION', 'IN-PROCESS', 'COMPLETED', 'CANCELLED']).optional(),
+  percent_complete: z.number().int().min(0).max(100).optional(),
+});
+
+export const updateTodoSchema = z.object({
+  todo_url: z.string().url('Invalid todo URL'),
+  todo_etag: z.string().min(1, 'ETag is required'),
+  updated_ical_data: z.string().min(1, 'iCal data is required'),
+});
+
+export const deleteTodoSchema = z.object({
+  todo_url: z.string().url('Invalid todo URL'),
+  todo_etag: z.string().min(1, 'ETag is required'),
+});
+
+export const todoQuerySchema = z.object({
+  calendar_url: optionalUrl('Invalid calendar URL'),
+  summary_filter: z.string().optional(),
+  status_filter: z.enum(['NEEDS-ACTION', 'IN-PROCESS', 'COMPLETED', 'CANCELLED']).optional(),
+  time_range_start: dateTimeWithOptionalOffset.optional(),
+  time_range_end: dateTimeWithOptionalOffset.optional(),
+}).refine((data) => {
+  // Rule 1: If ANY time field used, BOTH must be present
+  if (data.time_range_start || data.time_range_end) {
+    return data.time_range_start && data.time_range_end;
+  }
+
+  // Rule 2: At least ONE filter type must exist
+  return !!(data.calendar_url ||
+            data.summary_filter ||
+            data.status_filter);
+}, {
+  message: "Provide: (time_range with BOTH dates) OR (text/status filter) OR (both)"
+});
+
+export const todoMultiGetSchema = z.object({
+  todo_urls: z.array(z.string().url('Invalid todo URL')).min(1, 'At least one todo URL required'),
+});
+
+/**
+ * Validate input against a schema
+ */
+export function validateInput(schema, data) {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    const errors = result.error.errors.map(err => `${err.path.join('.')}: ${err.message}`).join(', ');
+    throw new Error(`Validation failed: ${errors}`);
+  }
+  return result.data;
+}
+
+/**
+ * Sanitize string for iCal/vCard format (escape special characters)
+ */
+export function sanitizeICalString(str) {
+  if (!str) return '';
+  return str
+    .replace(/\\/g, '\\\\')  // Escape backslashes
+    .replace(/;/g, '\\;')    // Escape semicolons
+    .replace(/,/g, '\\,')    // Escape commas
+    .replace(/\n/g, '\\n');  // Escape newlines
+}
+
+/**
+ * Sanitize vCard string
+ */
+export function sanitizeVCardString(str) {
+  return sanitizeICalString(str);
+}