Merge pull request #20 from PhilflowIO/feature/integrate-tsdav-utils

Integrate tsdav-utils for field-agnostic updates

Author: PhilflowIO

.gitignore

@@ -33,9 +33,13 @@ full-test.js
 # tsdav library (npm dependency)
 tsdav/
 
-# Internal development guides
+# Internal development guides (keep local only, never commit)
 CLAUDE.md
+GIT_WORKFLOW.md
+RESEARCH_FINDINGS.md
 COMPATIBILITY.md
+INTEGRATION_NOTES.md
+MIGRATION_*.md
 
 # Test artifacts
 tests/integration/test-results-*.json

CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+- **Field-agnostic updates**: Integrated tsdav-utils for universal field update support
+  - `update_event` now supports all RFC 5545 iCalendar properties (SUMMARY, DESCRIPTION, LOCATION, DTSTART, DTEND, STATUS, etc.)
+  - `update_todo` now supports all RFC 5545 VTODO properties (SUMMARY, DESCRIPTION, STATUS, PRIORITY, DUE, PERCENT-COMPLETE, etc.)
+  - `update_contact` now supports all RFC 6350 vCard properties (FN, N, EMAIL, TEL, ORG, TITLE, NOTE, URL, ADR, BDAY, etc.)
+  - All update tools now accept custom X-* properties for extensions (e.g., X-ZOOM-LINK, X-MEETING-ROOM)
+- Replaced manual iCal/vCard string manipulation with structured field updates via tsdav-utils
+- Simplified update tool implementations (reduced code by 40-45% per tool)
+- Updated input schemas to accept any RFC property name (field-agnostic validation)
+
+### Added
+- **New dependency**: tsdav-utils v0.1.0 for field-based calendar/contact operations
+- Support for updating event locations (LOCATION field)
+- Support for updating event date/time (DTSTART, DTEND fields)
+- Support for updating event status (STATUS: TENTATIVE/CONFIRMED/CANCELLED)
+- Support for updating todo status (STATUS: NEEDS-ACTION/IN-PROCESS/COMPLETED/CANCELLED)
+- Support for updating todo priority (PRIORITY: 0-9)
+- Support for updating todo due dates (DUE field)
+- Support for updating todo completion percentage (PERCENT-COMPLETE: 0-100)
+- Support for updating contact addresses (ADR field)
+- Support for updating contact birthdays (BDAY field)
+- Support for custom X-* properties across all update tools
+
+### Dependencies
+- Added: tsdav-utils (v0.1.0) - Field-agnostic utility layer for RFC-compliant updates
+
+## [2.6.0] - Previous Release
+
+Initial release with 26 MCP tools for CalDAV, CardDAV, and VTODO operations.
+

README.md

@@ -20,7 +20,7 @@ When partial tools force your AI to improvise, complete tools let it **execute p
 | **Calendar Management** | ✅ Full CRUD (11 tools) | ⚠️ Create + list only (2-3 tools) |
 | **Contact Management** | ✅ Complete CardDAV (8 tools) | ❌ Often missing entirely |
 | **Task Management** | ✅ Full VTODO support (7 tools) | ❌ Rarely included |
-| **Field-Based Updates** | ✅ LLM-friendly (no iCal/vCard format) | ❌ Rarely available |
+| **Field-Based Updates** | ✅ All RFC properties + custom fields | ❌ Rarely available |
 | **Server-Side Filtering** | ✅ Efficient queries | ❌ Dumps all data |
 | **Multi-Provider** | ✅ Any CalDAV/CardDAV server | ⚠️ Limited provider support |
 | **Total Tools** | **26 tools** | **2-6 tools** |
@@ -35,7 +35,7 @@ When partial tools force your AI to improvise, complete tools let it **execute p
 - **CalDAV Integration**: ~88% tsdav coverage (11 tools)
 - **CardDAV Integration**: 100% tsdav coverage (8 tools)
 - **VTODO Support**: Full task management with status, priorities, due dates (7 tools)
-- **Field-Based Updates**: LLM-friendly update tools (no iCal/vCard formatting required)
+- **Field-Based Updates**: Field-agnostic updates via tsdav-utils - supports all RFC 5545/6350 properties + custom X-* fields
 - **RFC-Compliant**: ical.js for RFC 5545 (iCalendar) and RFC 6350 (vCard) support
 
 ### Production-Ready Infrastructure
@@ -61,7 +61,7 @@ When partial tools force your AI to improvise, complete tools let it **execute p
 1. **list_calendars** - List all available calendars
 2. **list_events** - List ALL events (⚠️ WARNING: use calendar_query for filtered searches)
 3. **create_event** - Create a new calendar event
-4. **update_event** - ⭐ PREFERRED: Update event fields (summary, description) without iCal formatting
+4. **update_event** - ⭐ PREFERRED: Update any event field (SUMMARY, LOCATION, DTSTART, STATUS, custom X-* properties)
 5. **update_event_raw** - Update event with raw iCal data (advanced)
 6. **delete_event** - Delete an event permanently
 7. **calendar_query** - ⭐ PREFERRED: Search and filter events efficiently by text, date range, or location
@@ -75,7 +75,7 @@ When partial tools force your AI to improvise, complete tools let it **execute p
 12. **list_addressbooks** - List all available address books
 13. **list_contacts** - List ALL contacts (⚠️ WARNING: use addressbook_query for filtered searches)
 14. **create_contact** - Create a new contact (vCard)
-15. **update_contact** - ⭐ PREFERRED: Update contact fields (name, email, phone, etc.) without vCard formatting
+15. **update_contact** - ⭐ PREFERRED: Update any contact field (FN, EMAIL, TEL, ORG, ADR, custom X-* properties)
 16. **update_contact_raw** - Update contact with raw vCard data (advanced)
 17. **delete_contact** - Delete a contact permanently
 18. **addressbook_query** - ⭐ PREFERRED: Search and filter contacts efficiently by name, email, or organization
@@ -85,7 +85,7 @@ When partial tools force your AI to improvise, complete tools let it **execute p
 
 20. **list_todos** - List ALL todos/tasks (⚠️ WARNING: use todo_query for filtered searches)
 21. **create_todo** - Create a new todo/task with optional due date, priority, status
-22. **update_todo** - ⭐ PREFERRED: Update todo fields (summary, description) without iCal formatting
+22. **update_todo** - ⭐ PREFERRED: Update any todo field (SUMMARY, STATUS, PRIORITY, DUE, PERCENT-COMPLETE, custom X-* properties)
 23. **update_todo_raw** - Update todo with raw VTODO iCal data (advanced)
 24. **delete_todo** - Delete a todo/task permanently
 25. **todo_query** - ⭐ PREFERRED: Search and filter todos efficiently by status/due date
@@ -248,6 +248,7 @@ MIT License - see [LICENSE](LICENSE) for details
 
 Built with:
 - **[tsdav](https://github.com/natelindev/tsdav)** - Excellent TypeScript CalDAV/CardDAV library
+- **[tsdav-utils](https://github.com/PhilflowIO/tsdav-utils)** - Field-agnostic utility layer for RFC-compliant field updates
 - **[MCP SDK](https://modelcontextprotocol.io)** - Model Context Protocol by Anthropic
 - **[ical.js](https://github.com/kewisch/ical.js)** - RFC-compliant iCalendar parser
 

package-lock.json

@@ -65,6 +65,7 @@
     "express-rate-limit": "^8.1.0",
     "ical.js": "^2.2.1",
     "tsdav": "github:PhilflowIO/tsdav#master",
+    "tsdav-utils": "file:../tsdav_utils",
     "zod": "^3.25.76"
   },
   "devDependencies": {

package.json

@@ -2,78 +2,32 @@ import { tsdavManager } from '../../tsdav-client.js';
 import { validateInput } from '../../validation.js';
 import { formatSuccess, formatError } from '../../formatters.js';
 import { z } from 'zod';
-import ICAL from 'ical.js';
-// Import using namespace import for maximum CommonJS/ESM compatibility
-import * as tsdavAll from 'tsdav';
-// Access as property - works in both ESM (named export) and CJS (exports.xxx)
-const tsdavUpdateEventFields = tsdavAll.updateEventFields;
-
-/**
- * Manual iCal field update function as fallback
- * Updates specific fields in an iCal string when tsdav's updateEventFields is not available
- */
-function manualUpdateEventFields(calendarObject, fields) {
-  const jcalData = ICAL.parse(calendarObject.data);
-  const comp = new ICAL.Component(jcalData);
-  const vevent = comp.getFirstSubcomponent('vevent');
-  
-  if (!vevent) {
-    throw new Error('No VEVENT component found in calendar object');
-  }
-  
-  const modified = [];
-  const warnings = [];
-  
-  // Update fields
-  if (fields.summary !== undefined) {
-    vevent.updatePropertyWithValue('summary', fields.summary);
-    modified.push('summary');
-  }
-  
-  if (fields.description !== undefined) {
-    vevent.updatePropertyWithValue('description', fields.description);
-    modified.push('description');
-  }
-  
-  // Convert back to iCal string
-  const updatedData = comp.toString();
-  
-  return {
-    data: updatedData,
-    modified,
-    warnings
-  };
-}
+import { updateFields } from 'tsdav-utils';
 
 /**
  * Schema for field-based event updates
- * Currently supports MVP fields from tsdav v2.2.0: SUMMARY and DESCRIPTION
- * Note: tsdav uses UPPERCASE field names internally for iCal compatibility
+ * Supports all RFC 5545 iCalendar properties via tsdav-utils
+ * Common fields: SUMMARY, DESCRIPTION, LOCATION, DTSTART, DTEND, STATUS
+ * Custom properties: Any X-* property
  */
 const updateEventFieldsSchema = z.object({
   event_url: z.string().url('Event URL must be a valid URL'),
   event_etag: z.string().min(1, 'Event etag is required'),
-  fields: z.object({
-    summary: z.string().optional(),
-    description: z.string().optional(),
-    // Future fields (pending tsdav support):
-    // location: z.string().optional(),
-    // start_date: z.string().optional(),
-    // end_date: z.string().optional(),
-  }).optional()
+  fields: z.record(z.string()).optional()
 });
 
 /**
- * Wrapper for tsdav's native updateEventFields function
- * Uses the field-based update implementation from tsdav v2.2.0 MVP
+ * Field-agnostic event update tool powered by tsdav-utils
+ * Supports all RFC 5545 iCalendar properties without validation
  *
- * Current MVP limitations:
- * - Only SUMMARY and DESCRIPTION fields are officially supported
- * - Other iCal fields require using the full update_event tool
+ * Features:
+ * - Any standard VEVENT property (SUMMARY, DESCRIPTION, LOCATION, DTSTART, etc.)
+ * - Custom X-* properties for extensions
+ * - Field-agnostic: no pre-defined field list required
  */
 export const updateEventFields = {
   name: 'update_event',
-  description: 'PREFERRED: Update event fields (summary, description) easily without iCal formatting. Use this for simple event updates. For advanced iCal properties, use update_event_raw instead. Currently supports summary and description fields only.',
+  description: 'PREFERRED: Update event fields without iCal formatting. Supports: SUMMARY (title), DESCRIPTION (details), LOCATION (place), DTSTART (start time), DTEND (end time), STATUS (TENTATIVE/CONFIRMED/CANCELLED), and any RFC 5545 property including custom X-* properties (e.g., X-ZOOM-LINK, X-MEETING-ROOM).',
   inputSchema: {
     type: 'object',
     properties: {
@@ -87,15 +41,34 @@ export const updateEventFields = {
       },
       fields: {
         type: 'object',
-        description: 'Fields to update - only include fields you want to change. Currently supported: summary, description',
+        description: 'Fields to update - use UPPERCASE property names (e.g., SUMMARY, LOCATION, DTSTART). Any RFC 5545 property or custom X-* property is supported.',
+        additionalProperties: {
+          type: 'string'
+        },
         properties: {
-          summary: {
+          SUMMARY: {
+            type: 'string',
+            description: 'Event title/summary'
+          },
+          DESCRIPTION: {
+            type: 'string',
+            description: 'Event description/details'
+          },
+          LOCATION: {
             type: 'string',
-            description: 'Event title/summary - the main heading shown in calendars'
+            description: 'Physical or virtual meeting location'
           },
-          description: {
+          DTSTART: {
             type: 'string',
-            description: 'Event description - detailed information about the event'
+            description: 'Start datetime (ISO 8601 or iCal format: 20250128T100000Z)'
+          },
+          DTEND: {
+            type: 'string',
+            description: 'End datetime (ISO 8601 or iCal format)'
+          },
+          STATUS: {
+            type: 'string',
+            description: 'Event status: TENTATIVE, CONFIRMED, or CANCELLED'
           }
         }
       }
@@ -120,42 +93,23 @@ export const updateEventFields = {
 
       const calendarObject = currentEvents[0];
 
-      // Step 2: Transform snake_case field names to UPPERCASE for tsdav
-      // tsdav's updateEventFields expects UPPERCASE iCal property names
-      const tsdavFields = {};
-      if (validated.fields) {
-        if (validated.fields.summary !== undefined) {
-          tsdavFields.summary = validated.fields.summary;
-        }
-        if (validated.fields.description !== undefined) {
-          tsdavFields.description = validated.fields.description;
-        }
-      }
-
-      // Step 3: Use tsdav's native updateEventFields function or fallback to manual implementation
-      let result;
-      if (typeof tsdavUpdateEventFields === 'function') {
-        // Use tsdav's native function if available
-        result = tsdavUpdateEventFields(calendarObject, tsdavFields);
-      } else {
-        // Fallback to manual iCal manipulation
-        result = manualUpdateEventFields(calendarObject, tsdavFields);
-      }
+      // Step 2: Update fields using tsdav-utils (field-agnostic)
+      // Accepts any RFC 5545 property name (UPPERCASE)
+      const updatedData = updateFields(calendarObject, validated.fields || {});
 
-      // Step 4: Send the updated event back to server
+      // Step 3: Send the updated event back to server
       const updateResponse = await client.updateCalendarObject({
         calendarObject: {
           url: validated.event_url,
-          data: result.data,
+          data: updatedData,
           etag: validated.event_etag
         }
       });
 
       return formatSuccess('Event updated successfully', {
         etag: updateResponse.etag,
-        updated_fields: Object.keys(tsdavFields),
-        modified: result.modified,
-        warnings: result.warnings
+        updated_fields: Object.keys(validated.fields || {}),
+        message: `Updated ${Object.keys(validated.fields || {}).length} field(s): ${Object.keys(validated.fields || {}).join(', ')}`
       });
 
     } catch (error) {