icloud-mcp 2.2.0 → 2.3.0

package/.claude/settings.local.json

@@ -16,7 +16,16 @@
       "mcp__icloud-mail__archive_older_than",
       "mcp__icloud-mail__bulk_move_by_sender",
       "mcp__icloud-mail__get_move_status",
-      "mcp__icloud-mail__bulk_move_by_domain"
+      "mcp__icloud-mail__bulk_move_by_domain",
+      "WebSearch",
+      "WebFetch(domain:www.mdcourts.gov)",
+      "WebFetch(domain:probonomd.org)",
+      "WebFetch(domain:www.courts.state.md.us)",
+      "WebFetch(domain:msa.maryland.gov)",
+      "WebFetch(domain:www.harford.edu)",
+      "WebFetch(domain:thedailyrecord.com)",
+      "WebFetch(domain:ballotpedia.org)",
+      "mcp__icloud-mail__compose_email"
     ]
   },
   "enableAllProjectMcpServers": true,

package/README.md

@@ -1,6 +1,6 @@
 # icloud-mcp
 
-A Model Context Protocol (MCP) server that connects Claude to your iCloud Mail account. Read, search, organize, send, and automate your inbox directly through Claude.
+A Model Context Protocol (MCP) server that connects Claude to your iCloud account — Mail, Contacts, and Calendar. Read, search, organize, send, and automate across the full iCloud suite.
 
 ## Features
 
@@ -21,6 +21,8 @@ A Model Context Protocol (MCP) server that connects Claude to your iCloud Mail a
 - 🔄 Dry run mode for bulk operations — preview before committing
 - 🔐 Safe move — emails are fingerprinted and verified in the destination before removal from source
 - 📝 Session logging — Claude tracks progress across long multi-step operations
+- 👤 Contacts — list, search, create, update, and delete iCloud Contacts via CardDAV
+- 📅 Calendar — list calendars, query events by date, create/update/delete events via CalDAV
 
 ## Prerequisites
 
@@ -161,7 +163,7 @@ You're all set. Try asking Claude:
 - *"Show me the top senders in my iCloud inbox"*
 - *"How many unread emails do I have?"*
 
-## Available Tools (55)
+## Available Tools (65)
 
 ### Read & Search
 
@@ -247,6 +249,29 @@ You're all set. Try asking Claude:
 | `run_all_rules` | Run all saved rules in sequence; supports `dryRun` |
 | `delete_rule` | Delete a saved rule by name |
 
+### Contacts (CardDAV)
+
+| Tool | Description |
+|------|-------------|
+| `list_contacts` | List contacts from iCloud Contacts; supports `limit`, `offset` for pagination |
+| `search_contacts` | Search contacts by name, email, or phone number |
+| `get_contact` | Get full details for a specific contact by ID |
+| `create_contact` | Create a new contact; supports name, phones, emails, address, org, birthday, note |
+| `update_contact` | Update an existing contact; only provided fields are changed |
+| `delete_contact` | Permanently delete a contact |
+
+### Calendar (CalDAV)
+
+| Tool | Description |
+|------|-------------|
+| `list_calendars` | List all iCloud calendars with name, ID, and supported event types |
+| `list_events` | List events in a calendar within a date range; supports `since`, `before`, `limit` |
+| `get_event` | Get full details of a specific event by ID |
+| `create_event` | Create a new event; supports title, start/end, timezone, all-day, description, location, recurrence |
+| `update_event` | Update an existing event; only provided fields are changed |
+| `delete_event` | Permanently delete a calendar event |
+| `search_events` | Search for events by title across all calendars; supports date range |
+
 ### Session Log
 
 | Tool | Description |
@@ -299,6 +324,11 @@ Once configured, you can ask Claude things like:
 - *"Create a rule that moves all emails from spotify.com to bulk-mail/services"*
 - *"Reply to the last email from John and cc Sarah"*
 - *"Draft a follow-up email to the team about the Q1 report"*
+- *"Find John Smith's phone number in my contacts"*
+- *"Add a new contact: Jane Doe, jane@example.com, +1 555 123 4567"*
+- *"What's on my calendar next week?"*
+- *"Create an event: dentist appointment Monday at 10am Eastern"*
+- *"Find all my calendar events about 'team meeting'"*
 
 ## Security
 

package/index.js

@@ -19,6 +19,9 @@ import {
 } from './lib/imap.js';
 import { logRead, logWrite, logClear } from './lib/session.js';
 import { composeEmail, replyToEmail, forwardEmail, saveDraft } from './lib/smtp.js';
+import { listContacts, searchContacts, getContact, createContact, updateContact, deleteContact } from './lib/carddav.js';
+import { formatEmailForExtraction } from './lib/event-extractor.js';
+import { listCalendars, listEvents, getEvent, createEvent, updateEvent, deleteEvent, searchEvents } from './lib/caldav.js';
 
 const IMAP_USER = process.env.IMAP_USER;
 const IMAP_PASSWORD = process.env.IMAP_PASSWORD;
@@ -36,7 +39,7 @@ if (!IMAP_USER || !IMAP_PASSWORD) {
 
 async function main() {
   const server = new Server(
-    { name: 'icloud-mail', version: '2.1.0' },
+    { name: 'icloud-mail', version: '2.3.0' },
     { capabilities: { tools: {} } }
   );
 
@@ -673,6 +676,208 @@ async function main() {
           },
           required: ['to', 'subject']
         }
+      },
+      // ── CardDAV / Contacts ──
+      {
+        name: 'list_contacts',
+        description: 'List contacts from iCloud Contacts. Returns names, phones, emails, and other fields.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            limit: { type: 'number', description: 'Max contacts to return (default 50)' },
+            offset: { type: 'number', description: 'Skip this many contacts (default 0, for pagination)' }
+          }
+        }
+      },
+      {
+        name: 'search_contacts',
+        description: 'Search iCloud Contacts by name, email address, or phone number.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'Text to search for (matched against name, email, and phone)' }
+          },
+          required: ['query']
+        }
+      },
+      {
+        name: 'get_contact',
+        description: 'Get full details for a specific contact by ID. Use list_contacts or search_contacts to find a contactId.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            contactId: { type: 'string', description: 'Contact ID (UUID from list_contacts or search_contacts)' }
+          },
+          required: ['contactId']
+        }
+      },
+      {
+        name: 'create_contact',
+        description: 'Create a new contact in iCloud Contacts.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            firstName: { type: 'string', description: 'First name' },
+            lastName: { type: 'string', description: 'Last name' },
+            fullName: { type: 'string', description: 'Full display name (overrides firstName + lastName for FN field)' },
+            org: { type: 'string', description: 'Organization / company name' },
+            phone: { type: 'string', description: 'Primary phone number (shorthand for phones array)' },
+            email: { type: 'string', description: 'Primary email address (shorthand for emails array)' },
+            phones: { type: 'array', description: 'Array of phone objects: [{ number, type }] where type is cell/home/work/etc.' },
+            emails: { type: 'array', description: 'Array of email objects: [{ email, type }] where type is home/work/etc.' },
+            addresses: { type: 'array', description: 'Array of address objects: [{ street, city, state, zip, country, type }]' },
+            birthday: { type: 'string', description: 'Birthday in YYYY-MM-DD format' },
+            note: { type: 'string', description: 'Notes / free text' },
+            url: { type: 'string', description: 'Website URL' }
+          }
+        }
+      },
+      {
+        name: 'update_contact',
+        description: 'Update an existing contact in iCloud Contacts. Only provided fields are changed; others are preserved.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            contactId: { type: 'string', description: 'Contact ID to update' },
+            firstName: { type: 'string' },
+            lastName: { type: 'string' },
+            fullName: { type: 'string' },
+            org: { type: 'string' },
+            phone: { type: 'string' },
+            email: { type: 'string' },
+            phones: { type: 'array' },
+            emails: { type: 'array' },
+            addresses: { type: 'array' },
+            birthday: { type: 'string' },
+            note: { type: 'string' },
+            url: { type: 'string' }
+          },
+          required: ['contactId']
+        }
+      },
+      {
+        name: 'delete_contact',
+        description: 'Delete a contact from iCloud Contacts permanently.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            contactId: { type: 'string', description: 'Contact ID to delete' }
+          },
+          required: ['contactId']
+        }
+      },
+      // ── CalDAV / Calendar ──
+      {
+        name: 'list_calendars',
+        description: 'List all calendars in iCloud Calendar (e.g. Personal, Work, LSAT PREP). Returns calendarId, name, and supported event types.',
+        inputSchema: { type: 'object', properties: {} }
+      },
+      {
+        name: 'list_events',
+        description: 'List events in a specific iCloud calendar within a date range. Use list_calendars first to get a calendarId.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            calendarId: { type: 'string', description: 'Calendar ID from list_calendars' },
+            since: { type: 'string', description: 'Start of range (YYYY-MM-DD, default: 30 days ago)' },
+            before: { type: 'string', description: 'End of range (YYYY-MM-DD, default: 30 days ahead)' },
+            limit: { type: 'number', description: 'Max events to return (default 50)' }
+          },
+          required: ['calendarId']
+        }
+      },
+      {
+        name: 'get_event',
+        description: 'Get full details of a specific calendar event by its ID.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            calendarId: { type: 'string', description: 'Calendar ID containing the event' },
+            eventId: { type: 'string', description: 'Event ID (UUID from list_events or search_events)' }
+          },
+          required: ['calendarId', 'eventId']
+        }
+      },
+      {
+        name: 'create_event',
+        description: 'Create a new event in an iCloud calendar. For all-day events use allDay:true and YYYY-MM-DD for start/end.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            calendarId: { type: 'string', description: 'Calendar ID to add the event to' },
+            summary: { type: 'string', description: 'Event title' },
+            start: { type: 'string', description: 'Start date/time — ISO 8601 (e.g. 2026-03-15T10:00:00) or YYYY-MM-DD for all-day' },
+            end: { type: 'string', description: 'End date/time — ISO 8601 or YYYY-MM-DD. Defaults to 1 hour after start.' },
+            timezone: { type: 'string', description: 'IANA timezone (e.g. America/New_York). Use "UTC" or omit for UTC.' },
+            allDay: { type: 'boolean', description: 'True for all-day event (uses DATE values, no time)' },
+            description: { type: 'string', description: 'Event description / notes' },
+            location: { type: 'string', description: 'Event location' },
+            recurrence: { type: 'string', description: 'iCal RRULE string (e.g. FREQ=WEEKLY;BYDAY=MO,WE,FR)' },
+            status: { type: 'string', description: 'Event status: CONFIRMED, TENTATIVE, or CANCELLED' },
+            reminder: { type: 'number', description: 'Alert this many minutes before the event (default 30, set to 0 to disable)' }
+          },
+          required: ['calendarId', 'summary', 'start']
+        }
+      },
+      {
+        name: 'update_event',
+        description: 'Update an existing calendar event. Only provided fields are changed; others are preserved.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            calendarId: { type: 'string', description: 'Calendar ID containing the event' },
+            eventId: { type: 'string', description: 'Event ID to update' },
+            summary: { type: 'string' },
+            start: { type: 'string' },
+            end: { type: 'string' },
+            timezone: { type: 'string' },
+            allDay: { type: 'boolean' },
+            description: { type: 'string' },
+            location: { type: 'string' },
+            recurrence: { type: 'string' },
+            status: { type: 'string' },
+            reminder: { type: 'number', description: 'Alert minutes before event (0 to disable)' }
+          },
+          required: ['calendarId', 'eventId']
+        }
+      },
+      {
+        name: 'delete_event',
+        description: 'Delete a calendar event permanently from iCloud Calendar.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            calendarId: { type: 'string', description: 'Calendar ID containing the event' },
+            eventId: { type: 'string', description: 'Event ID to delete' }
+          },
+          required: ['calendarId', 'eventId']
+        }
+      },
+      {
+        name: 'search_events',
+        description: 'Search for events by title/summary across all calendars within an optional date range.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'Text to search for in event titles' },
+            since: { type: 'string', description: 'Start of search range (YYYY-MM-DD, default: 1 year ago)' },
+            before: { type: 'string', description: 'End of search range (YYYY-MM-DD, default: 1 year ahead)' }
+          },
+          required: ['query']
+        }
+      },
+      // ── Smart extraction ──
+      {
+        name: 'suggest_event_from_email',
+        description: 'Fetch an email and return its content formatted for calendar event extraction. After calling this tool, extract the event fields from the returned content (pay attention to _dateAnchor for resolving relative dates like "Tuesday"), present a summary to the user for confirmation, then call create_event. No API key required.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            uid: { type: 'number', description: 'Email UID to extract event from' },
+            mailbox: { type: 'string', description: 'Mailbox containing the email (default INBOX)' }
+          },
+          required: ['uid']
+        }
       }
     ]
   }));
@@ -815,6 +1020,70 @@ async function main() {
         result = await withTimeout('save_draft', TIMEOUT.FETCH, () =>
           saveDraft(args.to, args.subject, args.body, { html: args.html, cc: args.cc, bcc: args.bcc })
         );
+      // ── CardDAV / Contacts (FETCH tier 30s) ──
+      } else if (name === 'list_contacts') {
+        result = await withTimeout('list_contacts', TIMEOUT.FETCH, () =>
+          listContacts(args.limit || 50, args.offset || 0)
+        );
+      } else if (name === 'search_contacts') {
+        result = await withTimeout('search_contacts', TIMEOUT.FETCH, () =>
+          searchContacts(args.query)
+        );
+      } else if (name === 'get_contact') {
+        result = await withTimeout('get_contact', TIMEOUT.FETCH, () =>
+          getContact(args.contactId)
+        );
+      } else if (name === 'create_contact') {
+        const { contactId: _ignore, ...fields } = args;
+        result = await withTimeout('create_contact', TIMEOUT.FETCH, () =>
+          createContact(fields)
+        );
+      } else if (name === 'update_contact') {
+        const { contactId, ...fields } = args;
+        result = await withTimeout('update_contact', TIMEOUT.FETCH, () =>
+          updateContact(contactId, fields)
+        );
+      } else if (name === 'delete_contact') {
+        result = await withTimeout('delete_contact', TIMEOUT.SINGLE, () =>
+          deleteContact(args.contactId)
+        );
+      // ── CalDAV / Calendar (FETCH tier 30s) ──
+      } else if (name === 'list_calendars') {
+        result = await withTimeout('list_calendars', TIMEOUT.FETCH, () =>
+          listCalendars()
+        );
+      } else if (name === 'list_events') {
+        result = await withTimeout('list_events', TIMEOUT.FETCH, () =>
+          listEvents(args.calendarId, args.since || null, args.before || null, args.limit || 50)
+        );
+      } else if (name === 'get_event') {
+        result = await withTimeout('get_event', TIMEOUT.FETCH, () =>
+          getEvent(args.calendarId, args.eventId)
+        );
+      } else if (name === 'create_event') {
+        const { calendarId, ...fields } = args;
+        result = await withTimeout('create_event', TIMEOUT.FETCH, () =>
+          createEvent(calendarId, fields)
+        );
+      } else if (name === 'update_event') {
+        const { calendarId, eventId, ...fields } = args;
+        result = await withTimeout('update_event', TIMEOUT.FETCH, () =>
+          updateEvent(calendarId, eventId, fields)
+        );
+      } else if (name === 'delete_event') {
+        result = await withTimeout('delete_event', TIMEOUT.SINGLE, () =>
+          deleteEvent(args.calendarId, args.eventId)
+        );
+      } else if (name === 'search_events') {
+        result = await withTimeout('search_events', TIMEOUT.FETCH, () =>
+          searchEvents(args.query, args.since || null, args.before || null)
+        );
+      // ── Smart extraction (SCAN tier 60s — LLM round-trip) ──
+      } else if (name === 'suggest_event_from_email') {
+        const email = await withTimeout('get_email_for_extraction', TIMEOUT.FETCH, () =>
+          getEmailContent(args.uid, args.mailbox || 'INBOX', 10000, false)
+        );
+        result = formatEmailForExtraction(email);
       } else {
         throw new Error(`Unknown tool: ${name}`);
       }

package/lib/caldav.js

@@ -0,0 +1,502 @@
+// ─── lib/caldav.js — iCloud CalDAV (Calendar) ────────────────────────────────
+import { randomUUID } from 'crypto';
+
+const CALDAV_HOST = 'https://caldav.icloud.com';
+// Calendars to exclude from list_calendars (scheduling containers, not user calendars)
+const EXCLUDED_NAMES = new Set(['inbox', 'outbox', 'notification', 'notification/']);
+
+// ─── Credentials & HTTP ───────────────────────────────────────────────────────
+
+function getCredentials() {
+  const user = process.env.IMAP_USER;
+  const pass = process.env.IMAP_PASSWORD;
+  if (!user || !pass) throw new Error('IMAP_USER and IMAP_PASSWORD are required');
+  return { user, auth: Buffer.from(`${user}:${pass}`).toString('base64') };
+}
+
+async function davRequest(method, url, opts = {}) {
+  const { auth } = getCredentials();
+  const headers = {
+    Authorization: `Basic ${auth}`,
+    ...(opts.depth !== undefined ? { Depth: String(opts.depth) } : {}),
+    ...(opts.contentType ? { 'Content-Type': opts.contentType } : {}),
+    ...(opts.etag ? { 'If-Match': opts.etag } : {}),
+  };
+  const res = await fetch(url, { method, headers, body: opts.body });
+  const text = await res.text();
+  return { status: res.status, etag: res.headers.get('etag'), body: text };
+}
+
+function propfindBody(props) {
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<A:propfind xmlns:A="DAV:"><A:prop>${props}</A:prop></A:propfind>`;
+}
+
+// ─── Discovery ────────────────────────────────────────────────────────────────
+
+let _discoveryCache = null;
+
+async function discover() {
+  if (_discoveryCache) return _discoveryCache;
+
+  // Step 1: well-known → principal
+  const wk = await davRequest('PROPFIND', `${CALDAV_HOST}/.well-known/caldav`, {
+    depth: 0,
+    contentType: 'application/xml; charset=utf-8',
+    body: propfindBody('<A:current-user-principal/>'),
+  });
+
+  let principalPath = extractHrefIn(wk.body, 'current-user-principal');
+  if (!principalPath) {
+    const root = await davRequest('PROPFIND', `${CALDAV_HOST}/`, {
+      depth: 0,
+      contentType: 'application/xml; charset=utf-8',
+      body: propfindBody('<A:current-user-principal/>'),
+    });
+    principalPath = extractHrefIn(root.body, 'current-user-principal');
+  }
+  if (!principalPath) throw new Error('CalDAV: could not discover principal URL');
+
+  // Step 2: principal → calendar-home-set
+  const principalUrl = principalPath.startsWith('http')
+    ? principalPath
+    : `${CALDAV_HOST}${principalPath}`;
+
+  const principalResp = await davRequest('PROPFIND', principalUrl, {
+    depth: 0,
+    contentType: 'application/xml; charset=utf-8',
+    body: propfindBody('<C:calendar-home-set xmlns:C="urn:ietf:params:xml:ns:caldav"/>'),
+  });
+
+  const homeHref = extractHrefIn(principalResp.body, 'calendar-home-set');
+  if (!homeHref) throw new Error('CalDAV: could not find calendar-home-set');
+
+  // homeHref includes partition host (e.g. https://p137-caldav.icloud.com:443/dsid/calendars/)
+  const dataHost = homeHref.startsWith('http') ? new URL(homeHref).origin : CALDAV_HOST;
+  const calendarsPath = homeHref.startsWith('http')
+    ? new URL(homeHref).pathname
+    : homeHref;
+
+  _discoveryCache = { dataHost, calendarsPath };
+  return _discoveryCache;
+}
+
+// ─── XML helpers ──────────────────────────────────────────────────────────────
+
+function extractHrefIn(xml, parentTag) {
+  const re = new RegExp(
+    `<[^>:]*:?${parentTag}[\\s\\S]*?>[\\s\\S]*?<[^>:]*:?href[^>]*>([^<]+)<\\/[^>:]*:?href>`,
+    'i'
+  );
+  const m = xml.match(re);
+  return m ? m[1].trim() : null;
+}
+
+function splitResponses(xml) {
+  return [...xml.matchAll(/<[^>:]*:?response[\s\S]*?<\/[^>:]*:?response>/g)].map(m => m[0]);
+}
+
+function xmlText(xml, tag) {
+  const re = new RegExp(`<[^>:]*:?${tag}[^>]*>([\\s\\S]*?)<\\/[^>:]*:?${tag}>`, 'i');
+  const m = xml.match(re);
+  return m ? m[1].trim() : null;
+}
+
+// ─── iCal text escaping ───────────────────────────────────────────────────────
+// iCal property values must not contain raw newlines — escape as \n (literal backslash-n)
+
+function icalEscape(str) {
+  if (!str) return str;
+  return str
+    .replace(/\\/g, '\\\\')   // backslash → \\
+    .replace(/\n/g, '\\n')    // newline → \n (literal)
+    .replace(/\r/g, '');      // strip carriage returns
+}
+
+function icalUnescape(str) {
+  if (!str) return str;
+  return str
+    .replace(/\\n/g, '\n')
+    .replace(/\\,/g, ',')
+    .replace(/\\;/g, ';')
+    .replace(/\\\\/g, '\\');
+}
+
+// ─── iCal date helpers ────────────────────────────────────────────────────────
+
+function toIcalUtc(date) {
+  // YYYYMMDDTHHMMSSZ
+  return date.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+}
+
+function toIcalLocal(date) {
+  // YYYYMMDDTHHMMSS (no Z, for use with TZID=...)
+  const pad = n => String(n).padStart(2, '0');
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}` +
+    `T${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+
+function parseIcalDate(val, fullKey = '') {
+  if (fullKey.includes('VALUE=DATE')) {
+    // YYYYMMDD → YYYY-MM-DD
+    const m = val.match(/^(\d{4})(\d{2})(\d{2})$/);
+    return m ? `${m[1]}-${m[2]}-${m[3]}` : val;
+  }
+  // YYYYMMDDTHHMMSS[Z] → YYYY-MM-DDTHH:MM:SS[Z]
+  const m = val.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(Z?)$/);
+  if (!m) return val;
+  return `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}${m[7]}`;
+}
+
+// ─── iCal parsing ─────────────────────────────────────────────────────────────
+
+function parseVEvent(ical) {
+  // Unfold continuation lines
+  const unfolded = ical.replace(/\r?\n[ \t]/g, '');
+  const lines = unfolded.split(/\r?\n/);
+
+  let inEvent = false;
+  const event = {};
+
+  for (const line of lines) {
+    if (line === 'BEGIN:VEVENT') { inEvent = true; continue; }
+    if (line === 'END:VEVENT') { inEvent = false; continue; }
+    if (!inEvent) continue;
+
+    const colonIdx = line.indexOf(':');
+    if (colonIdx < 0) continue;
+    const fullKey = line.slice(0, colonIdx);
+    const val = line.slice(colonIdx + 1);
+    const key = fullKey.split(';')[0].toUpperCase();
+
+    switch (key) {
+      case 'UID': event.uid = val; break;
+      case 'SUMMARY': event.summary = icalUnescape(val); break;
+      case 'DESCRIPTION': event.description = icalUnescape(val); break;
+      case 'LOCATION': event.location = icalUnescape(val); break;
+      case 'STATUS': event.status = val; break;
+      case 'RRULE': event.recurrence = val; break;
+      case 'DTSTART': {
+        event.start = parseIcalDate(val, fullKey);
+        const tzM = fullKey.match(/TZID=([^;:]+)/);
+        if (tzM) event.timezone = tzM[1];
+        event.allDay = fullKey.includes('VALUE=DATE');
+        break;
+      }
+      case 'DTEND': {
+        event.end = parseIcalDate(val, fullKey);
+        break;
+      }
+      case 'CREATED': event.created = parseIcalDate(val, fullKey); break;
+      case 'LAST-MODIFIED': event.lastModified = parseIcalDate(val, fullKey); break;
+      case 'ORGANIZER': event.organizer = val.replace(/^mailto:/i, ''); break;
+      case 'ATTENDEE': {
+        if (!event.attendees) event.attendees = [];
+        const cn = fullKey.match(/CN=([^;:]+)/i)?.[1];
+        const email = val.replace(/^mailto:/i, '');
+        event.attendees.push(cn ? `${cn} <${email}>` : email);
+        break;
+      }
+      case 'EXDATE': {
+        if (!event.exDates) event.exDates = [];
+        event.exDates.push(parseIcalDate(val, fullKey));
+        break;
+      }
+    }
+  }
+
+  return event;
+}
+
+// ─── iCal serialization ───────────────────────────────────────────────────────
+
+function serializeVEvent(fields, uid = null) {
+  const id = uid || randomUUID().toUpperCase();
+  const now = new Date();
+  const dtstamp = toIcalUtc(now);
+
+  const lines = [
+    'BEGIN:VCALENDAR',
+    'CALSCALE:GREGORIAN',
+    'PRODID:-//icloud-mcp//EN',
+    'VERSION:2.0',
+    'BEGIN:VEVENT',
+    `DTSTAMP:${dtstamp}`,
+    `CREATED:${dtstamp}`,
+    `UID:${id}`,
+    `SUMMARY:${icalEscape(fields.summary || '(No title)')}`,
+  ];
+
+  if (fields.allDay) {
+    const start = (fields.start || '').replace(/-/g, '').slice(0, 8);
+    const end = (fields.end || fields.start || '').replace(/-/g, '').slice(0, 8);
+    lines.push(`DTSTART;VALUE=DATE:${start}`);
+    lines.push(`DTEND;VALUE=DATE:${end}`);
+  } else {
+    const tz = fields.timezone || 'UTC';
+    const startDate = fields.start ? new Date(fields.start) : now;
+    const endDate = fields.end ? new Date(fields.end) : new Date(startDate.getTime() + 3600_000);
+
+    if (tz === 'UTC') {
+      lines.push(`DTSTART:${toIcalUtc(startDate)}`);
+      lines.push(`DTEND:${toIcalUtc(endDate)}`);
+    } else {
+      lines.push(`DTSTART;TZID=${tz}:${toIcalLocal(startDate)}`);
+      lines.push(`DTEND;TZID=${tz}:${toIcalLocal(endDate)}`);
+    }
+  }
+
+  if (fields.description) lines.push(`DESCRIPTION:${icalEscape(fields.description)}`);
+  if (fields.location) lines.push(`LOCATION:${icalEscape(fields.location)}`);
+  if (fields.recurrence) lines.push(`RRULE:${fields.recurrence}`);
+  if (fields.status) lines.push(`STATUS:${fields.status}`);
+
+  // VALARM — reminder N minutes before (default: 30 min if not specified, 0 to disable)
+  const reminderMins = fields.reminder !== undefined ? Number(fields.reminder) : 30;
+  if (reminderMins > 0) {
+    lines.push(
+      'BEGIN:VALARM',
+      'ACTION:DISPLAY',
+      'DESCRIPTION:Reminder',
+      `TRIGGER:-PT${reminderMins}M`,
+      'END:VALARM'
+    );
+  }
+
+  lines.push('SEQUENCE:0', 'END:VEVENT', 'END:VCALENDAR');
+  return { ical: lines.join('\r\n') + '\r\n', uid: id };
+}
+
+// ─── Parse REPORT response blocks ────────────────────────────────────────────
+
+function parseEventBlocks(xml) {
+  return splitResponses(xml).map(block => {
+    const hrefMatch = block.match(/<[^>:]*:?href[^>]*>([^<]+)<\/[^>:]*:?href>/);
+    const etagMatch = block.match(/<[^>:]*:?getetag[^>]*>"?([^"<]+)"?<\/[^>:]*:?getetag>/);
+
+    // Extract calendar-data — may be in CDATA or as plain text
+    let icalText = null;
+    const cdataMatch = block.match(/<!\[CDATA\[([\s\S]*?)\]\]>/);
+    if (cdataMatch) {
+      icalText = cdataMatch[1];
+    } else {
+      const dataMatch = block.match(/<[^>:]*:?calendar-data[^>]*>([\s\S]*?)<\/[^>:]*:?calendar-data>/i);
+      if (dataMatch) icalText = dataMatch[1];
+    }
+
+    if (!hrefMatch || !icalText) return null;
+
+    const href = hrefMatch[1];
+    const parts = href.split('/').filter(Boolean);
+    const filename = parts[parts.length - 1];
+    const eventId = filename.replace(/\.ics$/i, '');
+    // calendarId is the UUID segment before the filename
+    const calendarId = parts[parts.length - 2] || null;
+
+    const event = parseVEvent(icalText);
+    return { eventId, calendarId, etag: etagMatch?.[1] || null, href, ...event };
+  }).filter(Boolean);
+}
+
+function parseCalendarBlocks(xml) {
+  return splitResponses(xml).map(block => {
+    const hrefMatch = block.match(/<[^>:]*:?href[^>]*>([^<]+)<\/[^>:]*:?href>/);
+    if (!hrefMatch) return null;
+
+    const href = hrefMatch[1];
+    const parts = href.split('/').filter(Boolean);
+    const last = parts[parts.length - 1];
+
+    // Skip scheduling/system containers
+    if (EXCLUDED_NAMES.has(last)) return null;
+
+    // Must have resourcetype = calendar
+    if (!block.includes('calendar') || !block.includes('collection')) return null;
+    // Skip the home-set itself (no calendar element, just collection)
+    const resourceBlock = xmlText(block, 'resourcetype') || '';
+    if (!resourceBlock.includes('calendar')) return null;
+
+    const displayName = xmlText(block, 'displayname') || last;
+    const syncToken = xmlText(block, 'sync-token') || null;
+
+    // supported component types
+    const compMatches = [...block.matchAll(/comp\s+name=['"]([^'"]+)['"]/g)].map(m => m[1]);
+
+    // calendarId is the last non-empty path segment
+    const calendarId = last.replace(/\/$/, '');
+
+    return { calendarId, name: displayName, href, supportedTypes: compMatches, syncToken };
+  }).filter(Boolean);
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export async function listCalendars() {
+  const { dataHost, calendarsPath } = await discover();
+
+  const body = propfindBody(`
+    <A:resourcetype/>
+    <A:displayname/>
+    <A:sync-token/>
+    <C:supported-calendar-component-set xmlns:C="urn:ietf:params:xml:ns:caldav"/>
+  `);
+
+  const resp = await davRequest('PROPFIND', `${dataHost}${calendarsPath}`, {
+    depth: 1,
+    contentType: 'application/xml; charset=utf-8',
+    body,
+  });
+
+  const calendars = parseCalendarBlocks(resp.body);
+  return { calendars, count: calendars.length };
+}
+
+export async function listEvents(calendarId, since = null, before = null, limit = 50) {
+  const { dataHost, calendarsPath } = await discover();
+
+  const sinceDate = since ? new Date(since) : new Date(Date.now() - 30 * 86400_000);
+  const beforeDate = before ? new Date(before) : new Date(Date.now() + 30 * 86400_000);
+
+  const start = toIcalUtc(sinceDate);
+  const end = toIcalUtc(beforeDate);
+
+  const body = `<?xml version="1.0" encoding="UTF-8"?>
+<C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav" xmlns:A="DAV:">
+  <A:prop><A:getetag/><C:calendar-data/></A:prop>
+  <C:filter>
+    <C:comp-filter name="VCALENDAR">
+      <C:comp-filter name="VEVENT">
+        <C:time-range start="${start}" end="${end}"/>
+      </C:comp-filter>
+    </C:comp-filter>
+  </C:filter>
+</C:calendar-query>`;
+
+  const url = `${dataHost}${calendarsPath}${calendarId}/`;
+  const resp = await davRequest('REPORT', url, {
+    depth: 1,
+    contentType: 'application/xml; charset=utf-8',
+    body,
+  });
+
+  if (resp.status === 403 || resp.status === 404) {
+    throw new Error(`Calendar not found or access denied: ${calendarId} (${resp.status})`);
+  }
+
+  const events = parseEventBlocks(resp.body).slice(0, limit);
+  return { events, count: events.length, calendarId, since: sinceDate.toISOString(), before: beforeDate.toISOString() };
+}
+
+export async function getEvent(calendarId, eventId) {
+  const { dataHost, calendarsPath } = await discover();
+  const url = `${dataHost}${calendarsPath}${calendarId}/${eventId}.ics`;
+  const resp = await davRequest('GET', url);
+
+  if (resp.status === 404) throw new Error(`Event not found: ${calendarId}/${eventId}`);
+  if (resp.status >= 400) throw new Error(`CalDAV GET failed: ${resp.status}`);
+
+  const event = parseVEvent(resp.body);
+  return { eventId, calendarId, etag: resp.etag, ...event };
+}
+
+export async function createEvent(calendarId, fields) {
+  const { dataHost, calendarsPath } = await discover();
+  const { ical, uid } = serializeVEvent(fields);
+  const eventId = uid;
+  const url = `${dataHost}${calendarsPath}${calendarId}/${eventId}.ics`;
+
+  const resp = await davRequest('PUT', url, {
+    contentType: 'text/calendar; charset=utf-8',
+    body: ical,
+  });
+
+  if (resp.status !== 201 && resp.status !== 204 && resp.status !== 200) {
+    throw new Error(`CalDAV PUT failed: ${resp.status} — ${resp.body.slice(0, 200)}`);
+  }
+
+  return { created: true, eventId, calendarId, etag: resp.etag };
+}
+
+export async function updateEvent(calendarId, eventId, fields) {
+  const { dataHost, calendarsPath } = await discover();
+  const url = `${dataHost}${calendarsPath}${calendarId}/${eventId}.ics`;
+
+  // Fetch current to get etag and existing fields
+  const existing = await davRequest('GET', url);
+  if (existing.status === 404) throw new Error(`Event not found: ${calendarId}/${eventId}`);
+
+  const current = parseVEvent(existing.body);
+  const merged = { ...current, ...fields };
+  const { ical } = serializeVEvent(merged, eventId);
+
+  const resp = await davRequest('PUT', url, {
+    contentType: 'text/calendar; charset=utf-8',
+    etag: existing.etag,
+    body: ical,
+  });
+
+  if (resp.status !== 204 && resp.status !== 200) {
+    throw new Error(`CalDAV PUT (update) failed: ${resp.status} — ${resp.body.slice(0, 200)}`);
+  }
+
+  return { updated: true, eventId, calendarId, etag: resp.etag };
+}
+
+export async function deleteEvent(calendarId, eventId) {
+  const { dataHost, calendarsPath } = await discover();
+  const url = `${dataHost}${calendarsPath}${calendarId}/${eventId}.ics`;
+
+  const resp = await davRequest('DELETE', url);
+  if (resp.status === 404) throw new Error(`Event not found: ${calendarId}/${eventId}`);
+  if (resp.status !== 204 && resp.status !== 200) {
+    throw new Error(`CalDAV DELETE failed: ${resp.status}`);
+  }
+
+  return { deleted: true, eventId, calendarId };
+}
+
+export async function searchEvents(query, since = null, before = null) {
+  const { dataHost, calendarsPath } = await discover();
+
+  const sinceDate = since ? new Date(since) : new Date(Date.now() - 365 * 86400_000);
+  const beforeDate = before ? new Date(before) : new Date(Date.now() + 365 * 86400_000);
+  const start = toIcalUtc(sinceDate);
+  const end = toIcalUtc(beforeDate);
+
+  // First list all calendars to search across all of them
+  const cals = await listCalendars();
+  const veventCals = cals.calendars.filter(c => c.supportedTypes.includes('VEVENT'));
+
+  const body = `<?xml version="1.0" encoding="UTF-8"?>
+<C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav" xmlns:A="DAV:">
+  <A:prop><A:getetag/><C:calendar-data/></A:prop>
+  <C:filter>
+    <C:comp-filter name="VCALENDAR">
+      <C:comp-filter name="VEVENT">
+        <C:time-range start="${start}" end="${end}"/>
+        <C:prop-filter name="SUMMARY">
+          <C:text-match collation="i;unicode-casemap" match-type="contains">${query}</C:text-match>
+        </C:prop-filter>
+      </C:comp-filter>
+    </C:comp-filter>
+  </C:filter>
+</C:calendar-query>`;
+
+  const results = await Promise.allSettled(
+    veventCals.map(cal =>
+      davRequest('REPORT', `${dataHost}${calendarsPath}${cal.calendarId}/`, {
+        depth: 1,
+        contentType: 'application/xml; charset=utf-8',
+        body,
+      })
+    )
+  );
+
+  const events = [];
+  for (const r of results) {
+    if (r.status === 'fulfilled' && r.value.status === 207) {
+      events.push(...parseEventBlocks(r.value.body));
+    }
+  }
+
+  return { events, count: events.length, query };
+}

package/lib/carddav.js

@@ -0,0 +1,401 @@
+// ─── lib/carddav.js — iCloud CardDAV (Contacts) ──────────────────────────────
+import { randomUUID } from 'crypto';
+
+const CONTACTS_HOST = 'https://contacts.icloud.com';
+
+// ─── Credentials & HTTP ───────────────────────────────────────────────────────
+
+function getCredentials() {
+  const user = process.env.IMAP_USER;
+  const pass = process.env.IMAP_PASSWORD;
+  if (!user || !pass) throw new Error('IMAP_USER and IMAP_PASSWORD are required');
+  return { user, auth: Buffer.from(`${user}:${pass}`).toString('base64') };
+}
+
+async function davRequest(method, url, opts = {}) {
+  const { auth } = getCredentials();
+  const headers = {
+    Authorization: `Basic ${auth}`,
+    ...(opts.depth !== undefined ? { Depth: String(opts.depth) } : {}),
+    ...(opts.contentType ? { 'Content-Type': opts.contentType } : {}),
+    ...(opts.etag ? { 'If-Match': opts.etag } : {}),
+  };
+  const res = await fetch(url, { method, headers, body: opts.body });
+  const text = await res.text();
+  return { status: res.status, etag: res.headers.get('etag'), body: text };
+}
+
+function propfindBody(props) {
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<A:propfind xmlns:A="DAV:"><A:prop>${props}</A:prop></A:propfind>`;
+}
+
+// ─── Discovery ────────────────────────────────────────────────────────────────
+
+let _discoveryCache = null;
+
+async function discover() {
+  if (_discoveryCache) return _discoveryCache;
+
+  // Step 1: well-known → current-user-principal
+  const wk = await davRequest('PROPFIND', `${CONTACTS_HOST}/.well-known/carddav`, {
+    depth: 0,
+    contentType: 'application/xml; charset=utf-8',
+    body: propfindBody('<A:current-user-principal/>'),
+  });
+
+  let principalPath = extractHrefIn(wk.body, 'current-user-principal');
+  if (!principalPath) {
+    const root = await davRequest('PROPFIND', `${CONTACTS_HOST}/`, {
+      depth: 0,
+      contentType: 'application/xml; charset=utf-8',
+      body: propfindBody('<A:current-user-principal/>'),
+    });
+    principalPath = extractHrefIn(root.body, 'current-user-principal');
+  }
+  if (!principalPath) throw new Error('CardDAV: could not discover principal URL');
+
+  // Step 2: principal → addressbook-home-set
+  const principalUrl = toAbsolute(principalPath, CONTACTS_HOST);
+  const principalResp = await davRequest('PROPFIND', principalUrl, {
+    depth: 0,
+    contentType: 'application/xml; charset=utf-8',
+    body: propfindBody('<C:addressbook-home-set xmlns:C="urn:ietf:params:xml:ns:carddav"/>'),
+  });
+
+  const homeHref = extractHrefIn(principalResp.body, 'addressbook-home-set');
+  if (!homeHref) throw new Error('CardDAV: could not find addressbook-home-set');
+
+  const homeSetUrl = homeHref.startsWith('http') ? homeHref : null;
+  // The home-set URL includes the partition host (e.g. p137-contacts.icloud.com)
+  const dataHost = homeSetUrl ? new URL(homeSetUrl).origin : CONTACTS_HOST;
+  const homeSetPath = homeHref.startsWith('http') ? new URL(homeHref).pathname : homeHref;
+
+  // Step 3: list address books, find the main one (resourcetype = addressbook)
+  const listing = await davRequest('PROPFIND', `${dataHost}${homeSetPath}`, {
+    depth: 1,
+    contentType: 'application/xml; charset=utf-8',
+    body: propfindBody('<A:resourcetype/><A:displayname/>'),
+  });
+
+  const blocks = splitResponses(listing.body);
+  let addressBookPath = null;
+  for (const block of blocks) {
+    if (block.includes('addressbook')) {
+      const hrefMatch = block.match(/<[^>:]*:?href[^>]*>([^<]+)<\/[^>:]*:?href>/);
+      if (hrefMatch) {
+        const p = hrefMatch[1].startsWith('http') ? new URL(hrefMatch[1]).pathname : hrefMatch[1];
+        if (!addressBookPath || p.includes('/card')) addressBookPath = p;
+      }
+    }
+  }
+  if (!addressBookPath) throw new Error('CardDAV: could not find address book');
+
+  _discoveryCache = { dataHost, homeSetPath, addressBookPath };
+  return _discoveryCache;
+}
+
+// ─── XML / text helpers ───────────────────────────────────────────────────────
+
+function toAbsolute(path, base) {
+  return path.startsWith('http') ? path : `${base}${path}`;
+}
+
+function extractHrefIn(xml, parentTag) {
+  const re = new RegExp(
+    `<[^>:]*:?${parentTag}[\\s\\S]*?>[\\s\\S]*?<[^>:]*:?href[^>]*>([^<]+)<\\/[^>:]*:?href>`,
+    'i'
+  );
+  const m = xml.match(re);
+  return m ? m[1].trim() : null;
+}
+
+function splitResponses(xml) {
+  return [...xml.matchAll(/<[^>:]*:?response[\s\S]*?<\/[^>:]*:?response>/g)].map(m => m[0]);
+}
+
+// ─── VCARD value escaping ─────────────────────────────────────────────────────
+
+// VCARD 3.0: newlines in values must be \n (backslash-n), not actual newlines
+function vcardEscape(str) {
+  if (!str) return str;
+  return str.replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/\r/g, '');
+}
+
+function vcardUnescape(str) {
+  if (!str) return str;
+  return str.replace(/\\n/gi, '\n').replace(/\\,/g, ',').replace(/\\;/g, ';').replace(/\\\\/g, '\\');
+}
+
+// ─── VCARD parsing ────────────────────────────────────────────────────────────
+
+function parseVCard(text) {
+  // Unfold continuation lines (CRLF + SPACE/TAB)
+  const unfolded = text.replace(/\r?\n[ \t]/g, '');
+  const lines = unfolded.split(/\r?\n/).filter(l => l && l !== 'BEGIN:VCARD' && l !== 'END:VCARD');
+
+  const contact = { phones: [], emails: [], addresses: [], _rawLines: [] };
+
+  for (const line of lines) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx < 0) continue;
+    const fullKey = line.slice(0, colonIdx);
+    const val = line.slice(colonIdx + 1);
+    const key = fullKey.split(';')[0].toUpperCase();
+
+    switch (key) {
+      case 'VERSION': break;
+      case 'PRODID': break;
+      case 'FN': contact.fullName = val; break;
+      case 'UID': contact.uid = val; break;
+      case 'ORG': contact.org = val.replace(/;$/, '').trim(); break;
+      case 'BDAY': contact.birthday = val; break;
+      case 'REV': contact.rev = val; break;
+      case 'NOTE': contact.note = vcardUnescape(val); break;
+      case 'URL': contact.url = vcardUnescape(val); break;
+      case 'N': {
+        const parts = val.split(';');
+        contact.lastName = parts[0] || '';
+        contact.firstName = parts[1] || '';
+        break;
+      }
+      default: {
+        if (key.includes('TEL')) {
+          const typeMatch = fullKey.match(/type=([^;:]+)/i);
+          const rawType = typeMatch?.[1]?.toLowerCase() || 'phone';
+          // Skip 'pref' as the type label, use the next type if available
+          const types = fullKey.match(/type=([^;:]+)/gi)?.map(t => t.split('=')[1].toLowerCase()) || [];
+          const type = types.find(t => t !== 'pref') || rawType;
+          contact.phones.push({ type, number: val });
+        } else if (key.includes('EMAIL')) {
+          const types = fullKey.match(/type=([^;:]+)/gi)?.map(t => t.split('=')[1].toLowerCase()) || [];
+          const type = types.find(t => !['internet', 'pref'].includes(t)) || 'home';
+          contact.emails.push({ type, email: val });
+        } else if (key.includes('ADR')) {
+          const parts = val.split(';');
+          const types = fullKey.match(/type=([^;:]+)/gi)?.map(t => t.split('=')[1].toLowerCase()) || [];
+          const type = types.find(t => t !== 'pref') || 'home';
+          contact.addresses.push({
+            type,
+            street: parts[2] || '',
+            city: parts[3] || '',
+            state: parts[4] || '',
+            zip: parts[5] || '',
+            country: parts[6] || '',
+          });
+        } else {
+          // Preserve unknown lines: PHOTO, X-*, item*.X-ABLabel, TITLE, etc.
+          contact._rawLines.push(line);
+        }
+      }
+    }
+  }
+
+  return contact;
+}
+
+// ─── VCARD serialization ──────────────────────────────────────────────────────
+
+function serializeVCard(fields, uid = null) {
+  const lines = [
+    'BEGIN:VCARD',
+    'VERSION:3.0',
+    'PRODID:-//icloud-mcp//EN',
+  ];
+  const vcardUid = uid || randomUUID().toUpperCase();
+
+  const fn = fields.fullName ||
+    [fields.firstName, fields.lastName].filter(Boolean).join(' ') ||
+    fields.org || 'Unknown';
+
+  lines.push(`N:${fields.lastName || ''};${fields.firstName || ''};;;`);
+  lines.push(`FN:${fn}`);
+
+  if (fields.org) lines.push(`ORG:${fields.org};`);
+  if (fields.birthday) lines.push(`BDAY:${fields.birthday}`);
+  if (fields.note) lines.push(`NOTE:${vcardEscape(fields.note)}`);
+  if (fields.url) lines.push(`URL:${vcardEscape(fields.url)}`);
+
+  const phones = normalizeArray(fields.phones, fields.phone ? { number: fields.phone, type: 'cell' } : null);
+  phones.forEach((p, i) => {
+    lines.push(`item${i + 1}.TEL;type=${(p.type || 'cell').toLowerCase()};type=pref:${p.number}`);
+  });
+
+  const emails = normalizeArray(fields.emails, fields.email ? { email: fields.email, type: 'home' } : null);
+  emails.forEach(e => {
+    lines.push(`EMAIL;type=INTERNET;type=${(e.type || 'home').toLowerCase()};type=pref:${e.email}`);
+  });
+
+  const addresses = Array.isArray(fields.addresses) ? fields.addresses : [];
+  addresses.forEach(a => {
+    lines.push(`ADR;type=${(a.type || 'home').toLowerCase()};type=pref:;;${a.street || ''};${a.city || ''};${a.state || ''};${a.zip || ''};${a.country || ''}`);
+  });
+
+  // Preserve unknown fields from the original VCARD (PHOTO, X-*, item*.X-ABLabel, etc.)
+  if (Array.isArray(fields._rawLines)) {
+    for (const rawLine of fields._rawLines) lines.push(rawLine);
+  }
+
+  lines.push(`UID:${vcardUid}`);
+  const rev = new Date().toISOString().replace(/[-:.]/g, '').slice(0, 15) + 'Z';
+  lines.push(`REV:${rev}`);
+  lines.push('END:VCARD');
+
+  return lines.join('\r\n') + '\r\n';
+}
+
+function normalizeArray(arr, fallback) {
+  if (Array.isArray(arr) && arr.length) return arr;
+  if (fallback) return [fallback];
+  return [];
+}
+
+// ─── Parse REPORT response blocks ────────────────────────────────────────────
+
+function parseContactBlocks(xml) {
+  return splitResponses(xml).map(block => {
+    const hrefMatch = block.match(/<[^>:]*:?href[^>]*>([^<]+)<\/[^>:]*:?href>/);
+    const etagMatch = block.match(/<[^>:]*:?getetag[^>]*>"?([^"<]+)"?<\/[^>:]*:?getetag>/);
+    const dataMatch = block.match(/<[^>:]*:?address-data[^>]*>([\s\S]*?)<\/[^>:]*:?address-data>/i);
+    if (!hrefMatch || !dataMatch) return null;
+
+    const href = hrefMatch[1];
+    const filename = href.split('/').pop();
+    const contactId = filename.replace(/\.vcf$/i, '');
+    const vcard = dataMatch[1].replace(/&#13;/g, '\r');
+    const contact = parseVCard(vcard);
+
+    return { contactId, etag: etagMatch?.[1] || null, href, ...contact };
+  }).filter(Boolean);
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export async function listContacts(limit = 50, offset = 0) {
+  const { dataHost, addressBookPath } = await discover();
+
+  const fetchLimit = limit + offset;
+  const body = `<?xml version="1.0" encoding="UTF-8"?>
+<C:addressbook-query xmlns:C="urn:ietf:params:xml:ns:carddav" xmlns:A="DAV:">
+  <A:prop><A:getetag/><C:address-data/></A:prop>
+  <C:filter/>
+  <C:limit><C:nresults>${fetchLimit}</C:nresults></C:limit>
+</C:addressbook-query>`;
+
+  const resp = await davRequest('REPORT', `${dataHost}${addressBookPath}`, {
+    depth: 1,
+    contentType: 'application/xml; charset=utf-8',
+    body,
+  });
+
+  const contacts = parseContactBlocks(resp.body).slice(offset, offset + limit);
+  return { contacts, count: contacts.length, limit, offset };
+}
+
+export async function searchContacts(query) {
+  const { dataHost, addressBookPath } = await discover();
+
+  // Search FN, EMAIL, TEL — run three queries and merge
+  const makeQuery = (propName) => `<?xml version="1.0" encoding="UTF-8"?>
+<C:addressbook-query xmlns:C="urn:ietf:params:xml:ns:carddav" xmlns:A="DAV:">
+  <A:prop><A:getetag/><C:address-data/></A:prop>
+  <C:filter>
+    <C:prop-filter name="${propName}">
+      <C:text-match collation="i;unicode-casemap" match-type="contains">${query}</C:text-match>
+    </C:prop-filter>
+  </C:filter>
+</C:addressbook-query>`;
+
+  const url = `${dataHost}${addressBookPath}`;
+  const opts = { depth: 1, contentType: 'application/xml; charset=utf-8' };
+
+  const [fnResp, emailResp, telResp] = await Promise.all([
+    davRequest('REPORT', url, { ...opts, body: makeQuery('FN') }),
+    davRequest('REPORT', url, { ...opts, body: makeQuery('EMAIL') }),
+    davRequest('REPORT', url, { ...opts, body: makeQuery('TEL') }),
+  ]);
+
+  // Merge and deduplicate by contactId
+  const seen = new Set();
+  const results = [];
+  for (const resp of [fnResp, emailResp, telResp]) {
+    for (const c of parseContactBlocks(resp.body)) {
+      if (!seen.has(c.contactId)) {
+        seen.add(c.contactId);
+        results.push(c);
+      }
+    }
+  }
+
+  return { contacts: results, count: results.length, query };
+}
+
+export async function getContact(contactId) {
+  const { dataHost, addressBookPath } = await discover();
+  const url = `${dataHost}${addressBookPath}${contactId}.vcf`;
+  const resp = await davRequest('GET', url);
+
+  if (resp.status === 404) throw new Error(`Contact not found: ${contactId}`);
+  if (resp.status >= 400) throw new Error(`CardDAV GET failed: ${resp.status}`);
+
+  const contact = parseVCard(resp.body);
+  return { contactId, etag: resp.etag, ...contact };
+}
+
+export async function createContact(fields) {
+  const { dataHost, addressBookPath } = await discover();
+  const contactId = randomUUID().toUpperCase();
+  const vcard = serializeVCard({ ...fields }, contactId);
+  const url = `${dataHost}${addressBookPath}${contactId}.vcf`;
+
+  const resp = await davRequest('PUT', url, {
+    contentType: 'text/vcard; charset=utf-8',
+    body: vcard,
+  });
+
+  if (resp.status !== 201 && resp.status !== 204 && resp.status !== 200) {
+    throw new Error(`CardDAV PUT failed: ${resp.status} — ${resp.body.slice(0, 200)}`);
+  }
+
+  return { created: true, contactId, etag: resp.etag };
+}
+
+export async function updateContact(contactId, fields) {
+  const { dataHost, addressBookPath } = await discover();
+  const url = `${dataHost}${addressBookPath}${contactId}.vcf`;
+
+  // Fetch existing to get etag and merge fields
+  const existing = await davRequest('GET', url);
+  if (existing.status === 404) throw new Error(`Contact not found: ${contactId}`);
+
+  const current = parseVCard(existing.body);
+
+  // Merge: new fields override, but keep arrays from existing if not overridden
+  const merged = { ...current, ...fields };
+  // Preserve the original VCARD UID (which may differ from the filename UUID)
+  const vcard = serializeVCard(merged, current.uid || contactId);
+
+  const resp = await davRequest('PUT', url, {
+    contentType: 'text/vcard; charset=utf-8',
+    etag: existing.etag,
+    body: vcard,
+  });
+
+  if (resp.status !== 204 && resp.status !== 200) {
+    throw new Error(`CardDAV PUT (update) failed: ${resp.status} — ${resp.body.slice(0, 200)}`);
+  }
+
+  return { updated: true, contactId, etag: resp.etag };
+}
+
+export async function deleteContact(contactId) {
+  const { dataHost, addressBookPath } = await discover();
+  const url = `${dataHost}${addressBookPath}${contactId}.vcf`;
+
+  const resp = await davRequest('DELETE', url);
+  if (resp.status === 404) throw new Error(`Contact not found: ${contactId}`);
+  if (resp.status !== 204 && resp.status !== 200) {
+    throw new Error(`CardDAV DELETE failed: ${resp.status}`);
+  }
+
+  return { deleted: true, contactId };
+}

package/lib/event-extractor.js

@@ -0,0 +1,47 @@
+// ─── lib/event-extractor.js — Email content formatter for calendar extraction ─
+// Returns structured email content for Claude to extract event details from.
+// No external API calls — Claude (the calling model) does the extraction natively.
+
+export function formatEmailForExtraction(email) {
+  const sentAt = new Date(email.date);
+  const sentFormatted = sentAt.toLocaleString('en-US', {
+    timeZone: 'America/New_York',
+    weekday: 'long',
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    timeZoneName: 'short',
+  });
+
+  return {
+    // Raw email fields
+    subject: email.subject,
+    from: email.from,
+    sentAt: sentFormatted,
+    sentAtIso: email.date,
+    body: email.body,
+
+    // Anchor hint for relative date resolution
+    _dateAnchor: `The email was sent on ${sentFormatted}. Use this as the reference when resolving relative dates like "Tuesday", "tomorrow", or "next week".`,
+
+    // Extraction instructions for Claude
+    _instructions: [
+      'Review the email above and extract the following calendar event fields:',
+      '  • summary       — event title',
+      '  • start         — ISO 8601 datetime (resolve relative dates using sentAt as anchor)',
+      '  • end           — ISO 8601 datetime (estimate if not stated)',
+      '  • estimatedEnd  — true if end time was not explicitly stated',
+      '  • allDay        — true if no specific time is given',
+      '  • timezone      — IANA timezone (infer from location if not stated)',
+      '  • location      — full venue name and address',
+      '  • description   — full agenda, parking info, and any other relevant details',
+      '  • attendees     — array of named people with role/title if mentioned',
+      '  • organizer     — who sent or organized this',
+      '  • confidence    — high / medium / low',
+      '  • notes         — anything ambiguous or worth flagging to the user',
+      'Present the extracted fields to the user for confirmation before calling create_event.',
+    ].join('\n'),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icloud-mcp",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "A Model Context Protocol (MCP) server for iCloud Mail",
   "main": "index.js",
   "bin": {
@@ -22,6 +22,7 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "fast-xml-parser": "^5.4.2",
     "imapflow": "^1.2.10",
     "nodemailer": "^8.0.2"
   }