dav-mcp 3.0.0

package/src/tools/contacts/list-addressbooks.js

@@ -0,0 +1,21 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { formatAddressBookList } from '../../formatters.js';
+
+/**
+ * List all available address books from the CardDAV server
+ */
+export const listAddressbooks = {
+  name: 'list_addressbooks',
+  description: 'List all available address books from the CardDAV server. Use this to get address book URLs needed for other contact operations',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+    required: [],
+  },
+  handler: async () => {
+    const client = tsdavManager.getCardDavClient();
+    const addressBooks = await client.fetchAddressBooks();
+
+    return formatAddressBookList(addressBooks);
+  },
+};

package/src/tools/contacts/list-contacts.js

@@ -0,0 +1,32 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput, listContactsSchema } from '../../validation.js';
+import { formatContactList } from '../../formatters.js';
+import { findAddressbookOrThrow } from '../shared/helpers.js';
+
+/**
+ * List ALL contacts from an address book without filtering
+ */
+export const listContacts = {
+  name: 'list_contacts',
+  description: 'List ALL contacts from an address book without filtering. WARNING: Returns all contacts which can be thousands - use addressbook_query instead when searching for specific contacts by name, email, or organization to save tokens',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      addressbook_url: {
+        type: 'string',
+        description: 'The URL of the address book to fetch contacts from',
+      },
+    },
+    required: ['addressbook_url'],
+  },
+  handler: async (args) => {
+    const validated = validateInput(listContactsSchema, args);
+    const client = tsdavManager.getCardDavClient();
+    const addressBooks = await client.fetchAddressBooks();
+    const addressBook = findAddressbookOrThrow(addressBooks, validated.addressbook_url);
+
+    const vcards = await client.fetchVCards({ addressBook });
+
+    return formatContactList(vcards, addressBook);
+  },
+};

package/src/tools/contacts/update-contact-fields.js

@@ -0,0 +1,135 @@
+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 vCard updates
+ * Supports all RFC 6350 vCard properties via tsdav-utils
+ * Common fields: FN, N, EMAIL, TEL, ORG, TITLE, NOTE, URL, ADR
+ * Custom properties: Any X-* property
+ */
+const updateContactFieldsSchema = z.object({
+  vcard_url: z.string().url('vCard URL must be a valid URL'),
+  vcard_etag: z.string().min(1, 'vCard etag is required'),
+  fields: z.record(z.string()).optional()
+});
+
+/**
+ * Field-agnostic contact update tool powered by tsdav-utils
+ * Supports all RFC 6350 vCard properties without validation
+ *
+ * Features:
+ * - Any standard vCard property (FN, N, EMAIL, TEL, ORG, TITLE, ADR, etc.)
+ * - Custom X-* properties for extensions
+ * - Field-agnostic: no pre-defined field list required
+ */
+export const updateContactFields = {
+  name: 'update_contact',
+  description: 'PREFERRED: Update contact fields without vCard formatting. Supports: FN (full name), N (structured name), EMAIL, TEL (phone), ORG (organization), TITLE (job title), NOTE, URL, ADR (address), BDAY (birthday), and any RFC 6350 vCard property including custom X-* properties.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      vcard_url: {
+        type: 'string',
+        description: 'The URL of the vCard to update'
+      },
+      vcard_etag: {
+        type: 'string',
+        description: 'The etag of the vCard (required for conflict detection)'
+      },
+      fields: {
+        type: 'object',
+        description: 'Fields to update - use UPPERCASE property names (e.g., FN, EMAIL, TEL). Any RFC 6350 vCard property or custom X-* property is supported.',
+        additionalProperties: {
+          type: 'string'
+        },
+        properties: {
+          FN: {
+            type: 'string',
+            description: 'Full formatted name (e.g., "John Doe")'
+          },
+          N: {
+            type: 'string',
+            description: 'Structured name (format: "Family;Given;Additional;Prefix;Suffix")'
+          },
+          EMAIL: {
+            type: 'string',
+            description: 'Email address'
+          },
+          TEL: {
+            type: 'string',
+            description: 'Phone number'
+          },
+          ORG: {
+            type: 'string',
+            description: 'Organization/company name'
+          },
+          TITLE: {
+            type: 'string',
+            description: 'Job title'
+          },
+          NOTE: {
+            type: 'string',
+            description: 'Notes/comments'
+          },
+          URL: {
+            type: 'string',
+            description: 'Web URL'
+          },
+          ADR: {
+            type: 'string',
+            description: 'Address (format: "POBox;Extended;Street;City;Region;PostalCode;Country")'
+          },
+          BDAY: {
+            type: 'string',
+            description: 'Birthday (ISO 8601 format: 1990-01-01)'
+          }
+        }
+      }
+    },
+    required: ['vcard_url', 'vcard_etag']
+  },
+  handler: async (args) => {
+    try {
+      const validated = validateInput(updateContactFieldsSchema, args);
+      const client = tsdavManager.getCardDavClient();
+
+      // Step 1: Fetch the current vCard from server
+      const addressBookUrl = validated.vcard_url.substring(0, validated.vcard_url.lastIndexOf('/') + 1);
+      const currentVCards = await client.fetchVCards({
+        addressBook: { url: addressBookUrl },
+        objectUrls: [validated.vcard_url]
+      });
+
+      if (!currentVCards || currentVCards.length === 0) {
+        throw new Error('Contact not found');
+      }
+
+      const vCardObject = currentVCards[0];
+
+      // Step 2: Update fields using tsdav-utils (field-agnostic)
+      // Accepts any RFC 6350 vCard property name (UPPERCASE)
+      const updatedData = updateFields(vCardObject, validated.fields || {});
+
+      // Step 3: Send the updated vCard back to server
+      const updateResponse = await client.updateVCard({
+        vCard: {
+          url: validated.vcard_url,
+          data: updatedData,
+          etag: validated.vcard_etag
+        }
+      });
+
+      return formatSuccess('Contact 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_contact', error);
+    }
+  }
+};

package/src/tools/contacts/update-contact-raw.js

@@ -0,0 +1,45 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput, updateContactSchema } from '../../validation.js';
+import { formatSuccess } from '../../formatters.js';
+
+/**
+ * Update an existing contact with raw vCard data
+ */
+export const updateContactRaw = {
+  name: 'update_contact_raw',
+  description: 'ADVANCED: Update contact with raw vCard data. Requires manual vCard formatting - use update_contact instead for simple field updates (name, email, phone). Only use this if you have complete pre-formatted vCard data or need to update advanced vCard properties.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      vcard_url: {
+        type: 'string',
+        description: 'The URL of the vCard to update',
+      },
+      vcard_etag: {
+        type: 'string',
+        description: 'The etag of the vCard',
+      },
+      updated_vcard_data: {
+        type: 'string',
+        description: 'The complete updated vCard data',
+      },
+    },
+    required: ['vcard_url', 'vcard_etag', 'updated_vcard_data'],
+  },
+  handler: async (args) => {
+    const validated = validateInput(updateContactSchema, args);
+    const client = tsdavManager.getCardDavClient();
+
+    const response = await client.updateVCard({
+      vCard: {
+        url: validated.vcard_url,
+        data: validated.updated_vcard_data,
+        etag: validated.vcard_etag,
+      },
+    });
+
+    return formatSuccess('Contact updated successfully', {
+      etag: response.etag,
+    });
+  },
+};

package/src/tools/index.js

@@ -0,0 +1,57 @@
+/**
+ * MCP Tools Main Index
+ * Combines all tool modules into a single exportable array
+ */
+
+// Calendar Tools (CalDAV)
+import * as calendarTools from './calendar/index.js';
+
+// Contact Tools (CardDAV)
+import * as contactTools from './contacts/index.js';
+
+// Todo Tools (VTODO)
+import * as todoTools from './todos/index.js';
+
+/**
+ * All available MCP tools
+ * Total: 26 tools organized in 3 categories
+ */
+export const tools = [
+  // ================================
+  // CALENDAR TOOLS (11 tools)
+  // ================================
+  calendarTools.listCalendars,
+  calendarTools.listEvents,
+  calendarTools.createEvent,
+  calendarTools.updateEventFields,
+  calendarTools.updateEventRaw,
+  calendarTools.deleteEvent,
+  calendarTools.calendarQuery,
+  calendarTools.makeCalendar,
+  calendarTools.updateCalendar,
+  calendarTools.deleteCalendar,
+  calendarTools.calendarMultiGet,
+
+  // ================================
+  // CONTACT TOOLS (8 tools)
+  // ================================
+  contactTools.listAddressbooks,
+  contactTools.listContacts,
+  contactTools.createContact,
+  contactTools.updateContactFields,
+  contactTools.updateContactRaw,
+  contactTools.deleteContact,
+  contactTools.addressbookQuery,
+  contactTools.addressbookMultiGet,
+
+  // ================================
+  // TODO TOOLS (7 tools)
+  // ================================
+  todoTools.listTodos,
+  todoTools.createTodo,
+  todoTools.updateTodoFields,
+  todoTools.updateTodoRaw,
+  todoTools.deleteTodo,
+  todoTools.todoQuery,
+  todoTools.todoMultiGet,
+];

package/src/tools/shared/helpers.js

@@ -0,0 +1,132 @@
+/**
+ * Shared helper functions for tool implementations
+ */
+
+/**
+ * Format iCal date (ISO 8601 to iCal format)
+ * @param {string|Date} date - Date to format
+ * @returns {string} Formatted iCal date string (YYYYMMDDTHHmmssZ)
+ */
+export function formatICalDate(date) {
+  return new Date(date).toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+}
+
+/**
+ * Generate unique UID for calendar objects
+ * @param {string} prefix - Prefix for the UID (e.g., 'event', 'todo', 'contact')
+ * @returns {string} Unique identifier
+ */
+export function generateUID(prefix = 'object') {
+  return `${prefix}-${Date.now()}@tsdav-mcp`;
+}
+
+/**
+ * Extract calendar home URL from existing calendar URL or account
+ * @param {Object} client - CalDAV client instance
+ * @returns {Promise<string>} Calendar home URL
+ */
+export async function getCalendarHome(client) {
+  // Try to get from account first
+  let calendarHome = client.account?.homeUrl;
+
+  // Fallback: Extract from existing calendar
+  if (!calendarHome) {
+    const calendars = await client.fetchCalendars();
+
+    if (!calendars || calendars.length === 0) {
+      throw new Error('Cannot determine calendar home: No calendar home found and no existing calendars available.');
+    }
+
+    // Extract calendar home from an existing calendar URL
+    // Example: https://dav.example.com/calendars/user/calendar-name/ -> https://dav.example.com/calendars/user/
+    const existingCalendarUrl = calendars[0].url;
+    calendarHome = existingCalendarUrl.substring(0, existingCalendarUrl.lastIndexOf('/', existingCalendarUrl.length - 2) + 1);
+  }
+
+  return calendarHome;
+}
+
+/**
+ * Sanitize calendar/event name for URL usage
+ * @param {string} name - Display name
+ * @returns {string} Sanitized name suitable for URLs
+ */
+export function sanitizeNameForUrl(name) {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/**
+ * Find calendar by URL and provide helpful error if not found
+ * @param {Array} calendars - List of calendars
+ * @param {string} calendarUrl - URL to search for
+ * @returns {Object} Calendar object
+ * @throws {Error} If calendar not found
+ */
+export function findCalendarOrThrow(calendars, calendarUrl) {
+  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;
+}
+
+/**
+ * Find addressbook by URL and provide helpful error if not found
+ * @param {Array} addressbooks - List of addressbooks
+ * @param {string} addressbookUrl - URL to search for
+ * @returns {Object} Addressbook object
+ * @throws {Error} If addressbook not found
+ */
+export function findAddressbookOrThrow(addressbooks, addressbookUrl) {
+  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 URLs.`
+    );
+  }
+
+  return addressbook;
+}
+
+/**
+ * Build time range options for queries
+ * @param {string} timeRangeStart - Start date (ISO 8601)
+ * @param {string} timeRangeEnd - End date (ISO 8601)
+ * @returns {Object} Time range options object
+ */
+export function buildTimeRangeOptions(timeRangeStart, timeRangeEnd) {
+  const options = {};
+
+  if (timeRangeStart && !timeRangeEnd) {
+    // Default to 1 year from start if only start provided
+    const startDate = new Date(timeRangeStart);
+    const endDate = new Date(startDate);
+    endDate.setFullYear(endDate.getFullYear() + 1);
+    options.timeRange = {
+      start: timeRangeStart,
+      end: endDate.toISOString(),
+    };
+  } else if (timeRangeStart && timeRangeEnd) {
+    options.timeRange = {
+      start: timeRangeStart,
+      end: timeRangeEnd,
+    };
+  }
+
+  return options;
+}

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

@@ -0,0 +1,101 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput, createTodoSchema, sanitizeICalString } from '../../validation.js';
+import { formatSuccess } from '../../formatters.js';
+import { formatICalDate } from '../shared/helpers.js';
+
+/**
+ * Create a new todo/task in a calendar
+ */
+export const createTodo = {
+  name: 'create_todo',
+  description: 'Create a new todo/task in a calendar. Use this when user wants to add a task, todo item, or reminder with optional due date, priority, and status.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      calendar_url: {
+        type: 'string',
+        description: 'The URL of the calendar to create the todo in',
+      },
+      summary: {
+        type: 'string',
+        description: 'The title/summary of the todo (required)',
+      },
+      description: {
+        type: 'string',
+        description: 'Optional detailed description',
+      },
+      due_date: {
+        type: 'string',
+        description: 'Optional due date in ISO 8601 format (e.g., 2025-12-31T23:59:59+02:00)',
+      },
+      priority: {
+        type: 'number',
+        description: 'Optional priority: 0=none, 1-3=high, 4-6=medium, 7-9=low',
+      },
+      status: {
+        type: 'string',
+        enum: ['NEEDS-ACTION', 'IN-PROCESS', 'COMPLETED', 'CANCELLED'],
+        description: 'Optional status (default: NEEDS-ACTION)',
+      },
+      percent_complete: {
+        type: 'number',
+        description: 'Optional completion percentage (0-100)',
+      },
+    },
+    required: ['calendar_url', 'summary'],
+  },
+  handler: async (args) => {
+    const validated = validateInput(createTodoSchema, args);
+    const client = tsdavManager.getCalDavClient();
+
+    // Build VTODO iCalendar string
+    const uid = `${Date.now()}-${Math.random().toString(36).substr(2, 9)}@tsdav-mcp`;
+    const dtstamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+
+    let vtodo = 'BEGIN:VCALENDAR\r\n';
+    vtodo += 'VERSION:2.0\r\n';
+    vtodo += 'PRODID:-//tsdav-mcp-server//NONSGML v1.2.0//EN\r\n';
+    vtodo += 'BEGIN:VTODO\r\n';
+    vtodo += `UID:${uid}\r\n`;
+    vtodo += `DTSTAMP:${dtstamp}\r\n`;
+    vtodo += `SUMMARY:${sanitizeICalString(validated.summary)}\r\n`;
+
+    if (validated.description) {
+      vtodo += `DESCRIPTION:${sanitizeICalString(validated.description)}\r\n`;
+    }
+
+    if (validated.status) {
+      vtodo += `STATUS:${validated.status}\r\n`;
+    } else {
+      vtodo += 'STATUS:NEEDS-ACTION\r\n';
+    }
+
+    if (validated.priority !== undefined) {
+      vtodo += `PRIORITY:${validated.priority}\r\n`;
+    }
+
+    if (validated.due_date) {
+      const dueDate = new Date(validated.due_date).toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+      vtodo += `DUE:${dueDate}\r\n`;
+    }
+
+    if (validated.percent_complete !== undefined) {
+      vtodo += `PERCENT-COMPLETE:${validated.percent_complete}\r\n`;
+    }
+
+    vtodo += 'END:VTODO\r\n';
+    vtodo += 'END:VCALENDAR\r\n';
+
+    const result = await client.createTodo({
+      calendar: { url: validated.calendar_url },
+      filename: `${Date.now()}.ics`,
+      iCalString: vtodo,
+    });
+
+    return formatSuccess('Todo created successfully', {
+      url: result.url,
+      etag: result.etag,
+      summary: validated.summary,
+    });
+  },
+};

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

@@ -0,0 +1,38 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput, deleteTodoSchema } from '../../validation.js';
+import { formatSuccess } from '../../formatters.js';
+
+/**
+ * Delete a todo/task permanently
+ */
+export const deleteTodo = {
+  name: 'delete_todo',
+  description: 'Delete a todo/task permanently from the calendar. Cannot be undone. Requires todo URL and etag.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      todo_url: {
+        type: 'string',
+        description: 'The URL of the todo to delete',
+      },
+      todo_etag: {
+        type: 'string',
+        description: 'The current ETag of the todo',
+      },
+    },
+    required: ['todo_url', 'todo_etag'],
+  },
+  handler: async (args) => {
+    const validated = validateInput(deleteTodoSchema, args);
+    const client = tsdavManager.getCalDavClient();
+
+    await client.deleteTodo({
+      todo: {
+        url: validated.todo_url,
+        etag: validated.todo_etag,
+      },
+    });
+
+    return formatSuccess('Todo deleted successfully');
+  },
+};

package/src/tools/todos/index.js

@@ -0,0 +1,12 @@
+/**
+ * Todo Tools - VTODO operations
+ * Exports all todo/task-related tools
+ */
+
+export { listTodos } from './list-todos.js';
+export { createTodo } from './create-todo.js';
+export { updateTodoFields } from './update-todo-fields.js';
+export { updateTodoRaw } from './update-todo-raw.js';
+export { deleteTodo } from './delete-todo.js';
+export { todoQuery } from './todo-query.js';
+export { todoMultiGet } from './todo-multi-get.js';

package/src/tools/todos/list-todos.js

@@ -0,0 +1,30 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput, listTodosSchema } from '../../validation.js';
+import { formatTodoList } from '../../formatters.js';
+
+/**
+ * List ALL todos/tasks from a calendar
+ */
+export const listTodos = {
+  name: 'list_todos',
+  description: 'List ALL todos/tasks from a calendar. WARNING: Returns all todos without filtering - use todo_query for searches with filters by status, summary, or due date.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      calendar_url: {
+        type: 'string',
+        description: 'The URL of the calendar containing todos',
+      },
+    },
+    required: ['calendar_url'],
+  },
+  handler: async (args) => {
+    const validated = validateInput(listTodosSchema, args);
+    const client = tsdavManager.getCalDavClient();
+
+    const calendar = { url: validated.calendar_url };
+    const todos = await client.fetchTodos({ calendar });
+
+    return formatTodoList(todos, validated.calendar_url);
+  },
+};

package/src/tools/todos/todo-multi-get.js

@@ -0,0 +1,37 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput, todoMultiGetSchema } from '../../validation.js';
+import { formatTodoList } from '../../formatters.js';
+
+/**
+ * Batch fetch multiple specific todos by their URLs
+ */
+export const todoMultiGet = {
+  name: 'todo_multi_get',
+  description: 'Batch fetch multiple specific todos by their URLs. More efficient than fetching one by one when you have exact todo URLs.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      todo_urls: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Array of todo URLs to fetch',
+      },
+    },
+    required: ['todo_urls'],
+  },
+  handler: async (args) => {
+    const validated = validateInput(todoMultiGetSchema, args);
+    const client = tsdavManager.getCalDavClient();
+
+    // Extract calendar URL from first todo URL
+    const calendarUrl = validated.todo_urls[0].split('/').slice(0, -1).join('/');
+
+    const todos = await client.todoMultiGet({
+      url: calendarUrl,
+      props: [{ name: 'getetag', namespace: 'DAV:' }, { name: 'calendar-data', namespace: 'urn:ietf:params:xml:ns:caldav' }],
+      objectUrls: validated.todo_urls,
+    });
+
+    return formatTodoList(todos, calendarUrl);
+  },
+};