mcp-icloud 2.1.1

package/utils/applescript.js

@@ -0,0 +1,214 @@
+/**
+ * AppleScript Executor Utility
+ * Executes AppleScript and JXA scripts via osascript
+ */
+
+const { spawn } = require('child_process');
+
+/**
+ * Execute an AppleScript string via stdin (handles multi-line scripts)
+ * @param {string} script - The AppleScript code to execute
+ * @returns {Promise<string>} - The script output
+ */
+async function runAppleScript(script) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('osascript', ['-']);
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    proc.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        resolve(stdout.trim());
+      } else {
+        reject(new AppleScriptError(stderr || stdout, script));
+      }
+    });
+
+    proc.on('error', (err) => {
+      reject(new AppleScriptError(err.message, script));
+    });
+
+    // Write script to stdin
+    proc.stdin.write(script);
+    proc.stdin.end();
+  });
+}
+
+/**
+ * Execute a JXA (JavaScript for Automation) script via stdin
+ * @param {string} script - The JXA code to execute
+ * @returns {Promise<string>} - The script output
+ */
+async function runJXA(script) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('osascript', ['-l', 'JavaScript', '-']);
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    proc.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        resolve(stdout.trim());
+      } else {
+        reject(new AppleScriptError(stderr || stdout, script));
+      }
+    });
+
+    proc.on('error', (err) => {
+      reject(new AppleScriptError(err.message, script));
+    });
+
+    // Write script to stdin
+    proc.stdin.write(script);
+    proc.stdin.end();
+  });
+}
+
+/**
+ * Execute JXA and parse JSON result
+ * @param {string} script - JXA script that returns JSON.stringify() output
+ * @returns {Promise<any>} - Parsed JSON result
+ */
+async function runJXAWithJSON(script) {
+  const result = await runJXA(script);
+  if (!result) return null;
+  try {
+    return JSON.parse(result);
+  } catch (e) {
+    return result;
+  }
+}
+
+/**
+ * Escape string for use in AppleScript
+ * @param {string} str - String to escape
+ * @returns {string} - Escaped string
+ */
+function escapeAppleScript(str) {
+  if (!str) return '';
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t');
+}
+
+/**
+ * Escape string for use in JXA
+ * @param {string} str - String to escape
+ * @returns {string} - Escaped string
+ */
+function escapeJXA(str) {
+  if (!str) return '';
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/'/g, "\\'")
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r');
+}
+
+/**
+ * Coerce a value that gets interpolated into script source as a bare number.
+ * Anything non-numeric would be injected as raw AppleScript/JXA, so reject it.
+ * @param {*} value - Value to coerce
+ * @param {number} fallback - Used when value is null/undefined
+ * @returns {number} - A finite integer
+ */
+function asInt(value, fallback = 0) {
+  if (value === undefined || value === null || value === '') return Math.trunc(fallback);
+  const n = Number(value);
+  if (!Number.isFinite(n)) {
+    throw new Error(`Expected a number, got: ${JSON.stringify(value)}`);
+  }
+  return Math.trunc(n);
+}
+
+/**
+ * Coerce a value that gets interpolated into script source as a bare boolean.
+ * @param {*} value - Value to coerce
+ * @param {boolean} fallback - Used when value is null/undefined
+ * @returns {boolean}
+ */
+function asBool(value, fallback = false) {
+  if (value === undefined || value === null || value === '') return fallback;
+  if (typeof value === 'boolean') return value;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  throw new Error(`Expected a boolean, got: ${JSON.stringify(value)}`);
+}
+
+/**
+ * Format date for AppleScript
+ * @param {Date|string} date - Date to format
+ * @returns {string} - AppleScript date string
+ */
+function formatAppleScriptDate(date) {
+  const d = date instanceof Date ? date : new Date(date);
+  // Format: "January 15, 2026 at 10:30:00 AM"
+  return d.toLocaleString('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: true
+  }).replace(',', ' at');
+}
+
+/**
+ * Custom error class for AppleScript errors
+ */
+class AppleScriptError extends Error {
+  constructor(message, script) {
+    super(message);
+    this.name = 'AppleScriptError';
+    this.script = script;
+
+    // Parse common AppleScript errors
+    if (message.includes('not allowed')) {
+      this.code = 'PERMISSION_DENIED';
+      this.userMessage = 'Permission denied. Please grant access in System Settings > Privacy & Security.';
+    } else if (message.includes('Application isn\'t running')) {
+      this.code = 'APP_NOT_RUNNING';
+      this.userMessage = 'The application is not running.';
+    } else if (message.includes('Can\'t get')) {
+      this.code = 'NOT_FOUND';
+      this.userMessage = 'The requested item was not found.';
+    } else {
+      this.code = 'SCRIPT_ERROR';
+      this.userMessage = message;
+    }
+  }
+}
+
+module.exports = {
+  runAppleScript,
+  runJXA,
+  runJXAWithJSON,
+  escapeAppleScript,
+  escapeJXA,
+  asInt,
+  asBool,
+  formatAppleScriptDate,
+  AppleScriptError
+};

package/utils/date-utils.js

@@ -0,0 +1,72 @@
+/**
+ * Date formatting utilities
+ */
+
+const config = require('../config');
+
+/**
+ * Format date for display (Spanish locale by default)
+ */
+function formatDate(date, options = {}) {
+  const d = date instanceof Date ? date : new Date(date);
+
+  const defaultOptions = {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    timeZone: config.DEFAULTS.TIMEZONE
+  };
+
+  return d.toLocaleString(config.DEFAULTS.DATE_FORMAT, { ...defaultOptions, ...options });
+}
+
+/**
+ * Format date for iCalendar (YYYYMMDDTHHMMSS format)
+ */
+function formatICalDate(date) {
+  const d = date instanceof Date ? date : new Date(date);
+  return d.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+}
+
+/**
+ * Parse ISO date string
+ */
+function parseDate(dateStr) {
+  return new Date(dateStr);
+}
+
+/**
+ * Get date range for calendar queries
+ */
+function getDateRange(daysAhead = 30) {
+  const start = new Date();
+  const end = new Date();
+  end.setDate(end.getDate() + daysAhead);
+
+  return { start, end };
+}
+
+/**
+ * Format relative date (today, yesterday, etc.)
+ */
+function formatRelative(date) {
+  const d = date instanceof Date ? date : new Date(date);
+  const now = new Date();
+  const diff = Math.floor((now - d) / (1000 * 60 * 60 * 24));
+
+  if (diff === 0) return 'Hoy';
+  if (diff === 1) return 'Ayer';
+  if (diff < 7) return `Hace ${diff} días`;
+
+  return formatDate(d, { hour: undefined, minute: undefined });
+}
+
+module.exports = {
+  formatDate,
+  formatICalDate,
+  parseDate,
+  getDateRange,
+  formatRelative
+};

package/utils/error-handler.js

@@ -0,0 +1,71 @@
+/**
+ * Centralized error handling utilities
+ */
+
+/**
+ * Format error for MCP response
+ */
+function formatError(error, context = '') {
+  const prefix = context ? `[${context}] ` : '';
+
+  if (error.message === 'UNAUTHORIZED' || error.message?.includes('authentication')) {
+    return {
+      content: [{
+        type: 'text',
+        text: `${prefix}Authentication failed. Please verify your iCloud credentials in .env file.\n\nTo set up:\n1. Go to https://appleid.apple.com\n2. Security → App-Specific Passwords → Generate\n3. Copy the password to ICLOUD_APP_PASSWORD in .env`
+      }],
+      isError: true
+    };
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: `${prefix}Error: ${error.message || 'Unknown error occurred'}`
+    }],
+    isError: true
+  };
+}
+
+/**
+ * Create success response
+ *
+ * @param {string} text - Human-readable result
+ * @param {Object} [structuredContent] - Machine-readable result. Only pass this
+ *   when the tool declares an outputSchema; the SDK validates one against the
+ *   other and fails the call if they disagree.
+ */
+function formatSuccess(text, structuredContent) {
+  const response = {
+    content: [{
+      type: 'text',
+      text: text
+    }]
+  };
+
+  if (structuredContent !== undefined) {
+    response.structuredContent = structuredContent;
+  }
+
+  return response;
+}
+
+/**
+ * Wrap handler with error catching
+ */
+function withErrorHandler(handler, context) {
+  return async (args) => {
+    try {
+      return await handler(args);
+    } catch (error) {
+      console.error(`[${context}] Error:`, error.message);
+      return formatError(error, context);
+    }
+  };
+}
+
+module.exports = {
+  formatError,
+  formatSuccess,
+  withErrorHandler
+};

package/utils/schemas.js

@@ -0,0 +1,33 @@
+/**
+ * Shared output schemas for tools that return a list.
+ *
+ * Deliberately permissive: the items come from AppleScript, IMAP, CalDAV and
+ * CardDAV, whose exact fields vary by macOS version, account type and server.
+ * The SDK fails a call whose structuredContent does not match its outputSchema,
+ * so pinning field names here would turn a harmless extra property into a
+ * broken tool. The contract is "an array of objects, plus a count".
+ */
+
+const { z } = require('zod');
+
+/**
+ * @param {string} description - What the items are, e.g. 'Contacts'
+ * @returns {Object} - A zod raw shape for use as a tool outputSchema
+ */
+function listOutput(description) {
+  return {
+    items: z.array(z.looseObject({})).describe(description),
+    total: z.number().int().describe('Number of items returned')
+  };
+}
+
+/**
+ * Build the structuredContent payload matching listOutput().
+ * @param {Array} items
+ */
+function listResult(items) {
+  const array = Array.isArray(items) ? items : [];
+  return { items: array, total: array.length };
+}
+
+module.exports = { listOutput, listResult };