dav-mcp 3.0.0

package/src/server-stdio.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * dav-mcp STDIO Server
+ *
+ * Entry point for local MCP clients: Claude Desktop, Cursor, VS Code, npx usage
+ *
+ * CRITICAL: This server uses STDIO transport. All logging MUST go to stderr
+ * to avoid corrupting JSON-RPC messages on stdout.
+ *
+ * Usage:
+ *   MCP_TRANSPORT=stdio node src/server-stdio.js
+ *
+ * Or via npx (after npm publish):
+ *   npx dav-mcp
+ *
+ * Configuration via environment variables:
+ *   - CALDAV_SERVER_URL: CalDAV server URL
+ *   - CALDAV_USERNAME: Username for Basic Auth
+ *   - CALDAV_PASSWORD: Password for Basic Auth
+ *   - AUTH_METHOD: 'Basic' (default) or 'OAuth'
+ *
+ * For OAuth2 (Google Calendar):
+ *   - GOOGLE_SERVER_URL: Google CalDAV URL
+ *   - GOOGLE_USER: Google account email
+ *   - GOOGLE_CLIENT_ID: OAuth2 client ID
+ *   - GOOGLE_CLIENT_SECRET: OAuth2 client secret
+ *   - GOOGLE_REFRESH_TOKEN: OAuth2 refresh token
+ */
+
+// Set STDIO mode BEFORE importing logger
+process.env.MCP_TRANSPORT = 'stdio';
+
+import dotenv from 'dotenv';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+import { tsdavManager } from './tsdav-client.js';
+import { tools } from './tools/index.js';
+import { createToolErrorResponse, MCP_ERROR_CODES } from './error-handler.js';
+import { logger } from './logger.js';
+import { initializeToolCallLogger, getToolCallLogger } from './tool-call-logger.js';
+
+// Load environment variables
+dotenv.config();
+
+/**
+ * Initialize tsdav clients based on auth method
+ */
+async function initializeTsdav() {
+  const authMethod = process.env.AUTH_METHOD || 'Basic';
+
+  if (authMethod === 'OAuth' || authMethod === 'Oauth') {
+    // OAuth2 Configuration (e.g., Google Calendar)
+    logger.info('Initializing with OAuth2 authentication');
+
+    if (!process.env.GOOGLE_CLIENT_ID || !process.env.GOOGLE_CLIENT_SECRET || !process.env.GOOGLE_REFRESH_TOKEN) {
+      throw new Error('OAuth2 requires GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REFRESH_TOKEN');
+    }
+
+    await tsdavManager.initialize({
+      serverUrl: process.env.GOOGLE_SERVER_URL || 'https://apidata.googleusercontent.com/caldav/v2/',
+      authMethod: 'OAuth',
+      username: process.env.GOOGLE_USER,
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+      refreshToken: process.env.GOOGLE_REFRESH_TOKEN,
+      tokenUrl: process.env.GOOGLE_TOKEN_URL || 'https://accounts.google.com/o/oauth2/token',
+    });
+
+    logger.info('OAuth2 clients initialized successfully');
+  } else {
+    // Basic Auth Configuration (standard CalDAV servers)
+    logger.info('Initializing with Basic authentication');
+
+    if (!process.env.CALDAV_SERVER_URL || !process.env.CALDAV_USERNAME || !process.env.CALDAV_PASSWORD) {
+      throw new Error('Basic Auth requires CALDAV_SERVER_URL, CALDAV_USERNAME, and CALDAV_PASSWORD');
+    }
+
+    await tsdavManager.initialize({
+      serverUrl: process.env.CALDAV_SERVER_URL,
+      authMethod: 'Basic',
+      username: process.env.CALDAV_USERNAME,
+      password: process.env.CALDAV_PASSWORD,
+    });
+
+    logger.info('Basic Auth clients initialized successfully');
+  }
+}
+
+/**
+ * Create MCP Server with tool handlers
+ */
+function createMCPServer() {
+  const server = new Server(
+    {
+      name: process.env.MCP_SERVER_NAME || 'dav-mcp',
+      version: process.env.MCP_SERVER_VERSION || '3.0.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // Register tools/list handler
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    logger.debug({ count: tools.length }, 'tools/list request received');
+    return {
+      tools: tools.map(t => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+      })),
+    };
+  });
+
+  // Register tools/call handler
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const toolName = request.params.name;
+    const args = request.params.arguments || {};
+    const toolCallLogger = getToolCallLogger();
+
+    logger.info({ tool: toolName }, 'tools/call request received');
+
+    const tool = tools.find(t => t.name === toolName);
+    if (!tool) {
+      logger.error({ tool: toolName }, 'Tool not found');
+      const error = new Error(`Unknown tool: ${toolName}`);
+      error.code = MCP_ERROR_CODES.METHOD_NOT_FOUND;
+      throw error;
+    }
+
+    const startTime = Date.now();
+    toolCallLogger.logToolCallStart(toolName, args, { transport: 'stdio' });
+
+    try {
+      logger.debug({ tool: toolName }, 'Executing tool');
+      const result = await tool.handler(args);
+      const duration = Date.now() - startTime;
+
+      logger.info({ tool: toolName, duration }, 'Tool executed successfully');
+      toolCallLogger.logToolCallSuccess(toolName, args, result, {
+        transport: 'stdio',
+        duration,
+      });
+
+      return result;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+
+      logger.error({ tool: toolName, error: error.message }, 'Tool execution error');
+      toolCallLogger.logToolCallError(toolName, args, error, {
+        transport: 'stdio',
+        duration,
+      });
+
+      return createToolErrorResponse(error, process.env.NODE_ENV === 'development');
+    }
+  });
+
+  return server;
+}
+
+/**
+ * Main entry point
+ */
+async function main() {
+  try {
+    logger.info('Starting dav-mcp STDIO server...');
+
+    // Initialize tsdav clients
+    await initializeTsdav();
+
+    // Initialize tool call logger
+    initializeToolCallLogger();
+    logger.info('Tool call logger initialized');
+
+    // Create MCP server
+    const server = createMCPServer();
+    logger.debug({ count: tools.length }, 'MCP server created with tools');
+
+    // Create STDIO transport
+    const transport = new StdioServerTransport();
+
+    // Connect server to transport
+    await server.connect(transport);
+
+    logger.info({
+      name: process.env.MCP_SERVER_NAME || 'dav-mcp',
+      version: process.env.MCP_SERVER_VERSION || '3.0.0',
+      tools: tools.length,
+    }, 'dav-mcp STDIO server ready');
+
+  } catch (error) {
+    logger.error({ error: error.message, stack: error.stack }, 'Fatal error starting server');
+    process.exit(1);
+  }
+}
+
+// Graceful shutdown handlers
+process.on('SIGTERM', () => {
+  logger.info('Received SIGTERM, shutting down...');
+  process.exit(0);
+});
+
+process.on('SIGINT', () => {
+  logger.info('Received SIGINT, shutting down...');
+  process.exit(0);
+});
+
+// Handle uncaught errors gracefully
+process.on('uncaughtException', (error) => {
+  logger.error({ error: error.message, stack: error.stack }, 'Uncaught exception');
+  process.exit(1);
+});
+
+process.on('unhandledRejection', (reason) => {
+  logger.error({ reason }, 'Unhandled promise rejection');
+  process.exit(1);
+});
+
+// Start the server
+main();

package/src/tool-call-logger.js

@@ -0,0 +1,148 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Tool Call Logger - Logs all MCP tool calls to JSON Lines format
+ * Enables real-time monitoring of LLM tool selection behavior
+ */
+
+class ToolCallLogger {
+  constructor(options = {}) {
+    this.enabled = options.enabled !== false;
+    this.outputMode = options.outputMode || 'file'; // 'file' | 'console' | 'both'
+    this.logFile = options.logFile || '/tmp/mcp-tool-calls.jsonl';
+
+    if (this.enabled && this.outputMode.includes('file')) {
+      this.ensureLogFileExists();
+    }
+  }
+
+  ensureLogFileExists() {
+    const dir = path.dirname(this.logFile);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  log(entry) {
+    if (!this.enabled) return;
+
+    const line = JSON.stringify(entry) + '\n';
+
+    if (this.outputMode === 'console' || this.outputMode === 'both') {
+      console.log(line.trim());
+    }
+
+    if (this.outputMode === 'file' || this.outputMode === 'both') {
+      try {
+        fs.appendFileSync(this.logFile, line);
+      } catch (error) {
+        console.error('Failed to write to tool call log:', error.message);
+      }
+    }
+  }
+
+  logToolCallStart(toolName, args, metadata = {}) {
+    this.log({
+      type: 'tool_call_start',
+      timestamp: new Date().toISOString(),
+      tool: toolName,
+      args: args,
+      ...metadata
+    });
+  }
+
+  logToolCallSuccess(toolName, args, result, metadata = {}) {
+    // Summarize result to avoid huge logs
+    const resultSummary = this.summarizeResult(result);
+
+    this.log({
+      type: 'tool_call_success',
+      timestamp: new Date().toISOString(),
+      tool: toolName,
+      args: args,
+      result_summary: resultSummary,
+      duration_ms: metadata.duration,
+      ...metadata
+    });
+  }
+
+  logToolCallError(toolName, args, error, metadata = {}) {
+    this.log({
+      type: 'tool_call_error',
+      timestamp: new Date().toISOString(),
+      tool: toolName,
+      args: args,
+      error: {
+        message: error.message,
+        code: error.code,
+        stack: process.env.NODE_ENV === 'development' ? error.stack : undefined
+      },
+      duration_ms: metadata.duration,
+      ...metadata
+    });
+  }
+
+  summarizeResult(result) {
+    if (!result) return null;
+
+    // Handle MCP result format
+    if (result.content && Array.isArray(result.content)) {
+      return {
+        type: 'mcp_result',
+        content_count: result.content.length,
+        content_types: result.content.map(c => c.type),
+        has_text: result.content.some(c => c.type === 'text'),
+        text_length: result.content
+          .filter(c => c.type === 'text')
+          .reduce((sum, c) => sum + (c.text?.length || 0), 0)
+      };
+    }
+
+    // Handle plain objects/strings
+    if (typeof result === 'string') {
+      return { type: 'string', length: result.length };
+    }
+
+    if (typeof result === 'object') {
+      return {
+        type: 'object',
+        keys: Object.keys(result).slice(0, 5),
+        key_count: Object.keys(result).length
+      };
+    }
+
+    return { type: typeof result };
+  }
+
+  clearLog() {
+    if (this.enabled && fs.existsSync(this.logFile)) {
+      fs.unlinkSync(this.logFile);
+    }
+  }
+}
+
+// Singleton instance
+let instance = null;
+
+export function initializeToolCallLogger(options = {}) {
+  const enabled = process.env.LOG_TOOL_CALLS !== 'false';
+  const outputMode = process.env.TOOL_CALL_LOG_MODE || 'file';
+  const logFile = process.env.TOOL_CALL_LOG_FILE || '/tmp/mcp-tool-calls.jsonl';
+
+  instance = new ToolCallLogger({
+    enabled,
+    outputMode,
+    logFile,
+    ...options
+  });
+
+  return instance;
+}
+
+export function getToolCallLogger() {
+  if (!instance) {
+    instance = initializeToolCallLogger();
+  }
+  return instance;
+}

package/src/tools/calendar/calendar-multi-get.js

@@ -0,0 +1,38 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput, calendarMultiGetSchema } from '../../validation.js';
+import { formatEventList } from '../../formatters.js';
+
+/**
+ * Batch fetch multiple specific calendar events by their URLs
+ */
+export const calendarMultiGet = {
+  name: 'calendar_multi_get',
+  description: 'Batch fetch multiple specific calendar events by their URLs. Use when you have exact event URLs and want to retrieve their details',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      calendar_url: {
+        type: 'string',
+        description: 'The URL of the calendar',
+      },
+      event_urls: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Array of event URLs to fetch',
+      },
+    },
+    required: ['calendar_url', 'event_urls'],
+  },
+  handler: async (args) => {
+    const validated = validateInput(calendarMultiGetSchema, args);
+    const client = tsdavManager.getCalDavClient();
+
+    const events = await client.calendarMultiGet({
+      url: validated.calendar_url,
+      props: [{ name: 'getetag', namespace: 'DAV:' }, 'calendar-data'],
+      objectUrls: validated.event_urls,
+    });
+
+    return formatEventList(events, { url: validated.calendar_url });
+  },
+};

package/src/tools/calendar/calendar-query.js

@@ -0,0 +1,98 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput, calendarQuerySchema } from '../../validation.js';
+import { formatEventList } from '../../formatters.js';
+import { buildTimeRangeOptions } from '../shared/helpers.js';
+
+/**
+ * Search and filter calendar events efficiently
+ */
+export const calendarQuery = {
+  name: 'calendar_query',
+  description: '⭐ PREFERRED: Search and filter calendar events efficiently. Use instead of list_events to avoid loading thousands of entries. Omit calendar_url to search across ALL calendars automatically.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      calendar_url: {
+        type: 'string',
+        description: 'Optional: Specific calendar URL. Omit to search ALL calendars (recommended for "find events with X" queries). Only provide if user explicitly names a calendar. DO NOT use list_calendars first - that defeats cross-calendar search.',
+      },
+      time_range_start: {
+        type: 'string',
+        description: 'Start datetime (ISO 8601, e.g., 2025-10-30T00:00:00Z). If provided, time_range_end is REQUIRED. Calculate dates for "today", "this week", etc. Can be used alone (with end date) as sufficient filter.',
+      },
+      time_range_end: {
+        type: 'string',
+        description: 'End datetime (ISO 8601). If provided, time_range_start is REQUIRED. Both dates together form a complete filter. Do not omit if start is provided.',
+      },
+      summary_filter: {
+        type: 'string',
+        description: 'Search event titles/summaries containing this text (case-insensitive). Example: "meeting with Elena" or "standup". Can be used alone as sufficient filter.',
+      },
+      location_filter: {
+        type: 'string',
+        description: 'Search event locations containing this text. Example: "Berlin", "Office", "Zoom". Can be used alone as sufficient filter.',
+      },
+    },
+    required: [],
+  },
+  handler: async (args) => {
+    const validated = validateInput(calendarQuerySchema, args);
+    const client = tsdavManager.getCalDavClient();
+    const calendars = await client.fetchCalendars();
+
+    // If specific calendar requested, use it
+    let calendarsToSearch = calendars;
+    if (validated.calendar_url) {
+      const calendar = calendars.find(c => c.url === validated.calendar_url);
+      if (!calendar) {
+        const availableUrls = calendars.map(c => c.url).join('\n- ');
+        throw new Error(
+          `Calendar not found: ${validated.calendar_url}\n\n` +
+          `Available calendar URLs:\n- ${availableUrls}\n\n` +
+          `Tip: Omit calendar_url to search across all calendars automatically.`
+        );
+      }
+      calendarsToSearch = [calendar];
+    }
+
+    // Build timeRange options
+    const timeRangeOptions = buildTimeRangeOptions(validated.time_range_start, validated.time_range_end);
+
+    // Search across all selected calendars
+    let allEvents = [];
+    for (const calendar of calendarsToSearch) {
+      const options = { calendar, ...timeRangeOptions };
+      const events = await client.fetchCalendarObjects(options);
+      // Add calendar info to each event
+      events.forEach(event => {
+        event._calendarName = calendar.displayName || calendar.url;
+      });
+      allEvents = allEvents.concat(events);
+    }
+
+    let filteredEvents = allEvents;
+
+    if (validated.summary_filter) {
+      const summaryLower = validated.summary_filter.toLowerCase();
+      filteredEvents = filteredEvents.filter(event => {
+        const summary = event.data?.match(/SUMMARY:(.+)/)?.[1] || '';
+        return summary.toLowerCase().includes(summaryLower);
+      });
+    }
+
+    if (validated.location_filter) {
+      const locationLower = validated.location_filter.toLowerCase();
+      filteredEvents = filteredEvents.filter(event => {
+        const location = event.data?.match(/LOCATION:(.+)/)?.[1] || '';
+        return location.toLowerCase().includes(locationLower);
+      });
+    }
+
+    // Determine calendar name for display
+    const calendarName = calendarsToSearch.length === 1
+      ? (calendarsToSearch[0].displayName || calendarsToSearch[0].url)
+      : `All Calendars (${calendarsToSearch.length})`;
+
+    return formatEventList(filteredEvents, calendarName);
+  },
+};

package/src/tools/calendar/create-event.js

@@ -0,0 +1,79 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput, createEventSchema, sanitizeICalString } from '../../validation.js';
+import { formatSuccess } from '../../formatters.js';
+import { formatICalDate, generateUID, findCalendarOrThrow } from '../shared/helpers.js';
+
+/**
+ * Create a new calendar event
+ */
+export const createEvent = {
+  name: 'create_event',
+  description: 'Create a new calendar event with title, date, time, optional description and location',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      calendar_url: {
+        type: 'string',
+        description: 'The URL of the calendar to create the event in',
+      },
+      summary: {
+        type: 'string',
+        description: 'Event title/summary',
+      },
+      start_date: {
+        type: 'string',
+        description: 'Start date in ISO 8601 format',
+      },
+      end_date: {
+        type: 'string',
+        description: 'End date in ISO 8601 format',
+      },
+      description: {
+        type: 'string',
+        description: 'Event description (optional)',
+      },
+      location: {
+        type: 'string',
+        description: 'Event location (optional)',
+      },
+    },
+    required: ['calendar_url', 'summary', 'start_date', 'end_date'],
+  },
+  handler: async (args) => {
+    const validated = validateInput(createEventSchema, args);
+    const client = tsdavManager.getCalDavClient();
+    const calendars = await client.fetchCalendars();
+    const calendar = findCalendarOrThrow(calendars, validated.calendar_url);
+
+    const now = new Date();
+    const uid = generateUID('event');
+
+    const summary = sanitizeICalString(validated.summary);
+    const description = validated.description ? sanitizeICalString(validated.description) : '';
+    const location = validated.location ? sanitizeICalString(validated.location) : '';
+
+    const iCalString = `BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//tsdav-mcp-server//EN
+BEGIN:VEVENT
+UID:${uid}
+DTSTAMP:${formatICalDate(now)}
+DTSTART:${formatICalDate(new Date(validated.start_date))}
+DTEND:${formatICalDate(new Date(validated.end_date))}
+SUMMARY:${summary}${description ? `\nDESCRIPTION:${description}` : ''}${location ? `\nLOCATION:${location}` : ''}
+END:VEVENT
+END:VCALENDAR`;
+
+    const response = await client.createCalendarObject({
+      calendar,
+      filename: `${uid}.ics`,
+      iCalString,
+    });
+
+    return formatSuccess('Event created successfully', {
+      url: response.url,
+      etag: response.etag,
+      summary: validated.summary,
+    });
+  },
+};

package/src/tools/calendar/delete-calendar.js

@@ -0,0 +1,36 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput, deleteCalendarSchema } from '../../validation.js';
+import { formatCalendarDeleteSuccess } from '../../formatters.js';
+
+/**
+ * Permanently delete a calendar and all its events
+ */
+export const deleteCalendar = {
+  name: 'delete_calendar',
+  description: 'Permanently delete a calendar and all its events. WARNING: This action cannot be undone! Use this when user explicitly asks to "delete calendar" or "remove calendar"',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      calendar_url: {
+        type: 'string',
+        description: 'The URL of the calendar to delete (get from list_calendars)',
+      },
+    },
+    required: ['calendar_url'],
+  },
+  handler: async (args) => {
+    const validated = validateInput(deleteCalendarSchema, args);
+    const client = tsdavManager.getCalDavClient();
+
+    // Use deleteObject to send DELETE request
+    await client.deleteObject({
+      url: validated.calendar_url,
+      headers: {
+        'Content-Type': 'text/calendar; charset=utf-8',
+      },
+    });
+
+    // Return formatted success with warning
+    return formatCalendarDeleteSuccess(validated.calendar_url);
+  },
+};

package/src/tools/calendar/delete-event.js

@@ -0,0 +1,38 @@
+import { tsdavManager } from '../../tsdav-client.js';
+import { validateInput, deleteEventSchema } from '../../validation.js';
+import { formatSuccess } from '../../formatters.js';
+
+/**
+ * Delete a calendar event permanently
+ */
+export const deleteEvent = {
+  name: 'delete_event',
+  description: 'Delete a calendar event permanently. Requires event URL and etag',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      event_url: {
+        type: 'string',
+        description: 'The URL of the event to delete',
+      },
+      event_etag: {
+        type: 'string',
+        description: 'The etag of the event',
+      },
+    },
+    required: ['event_url', 'event_etag'],
+  },
+  handler: async (args) => {
+    const validated = validateInput(deleteEventSchema, args);
+    const client = tsdavManager.getCalDavClient();
+
+    await client.deleteCalendarObject({
+      calendarObject: {
+        url: validated.event_url,
+        etag: validated.event_etag,
+      },
+    });
+
+    return formatSuccess('Event deleted successfully');
+  },
+};

package/src/tools/calendar/index.js

@@ -0,0 +1,16 @@
+/**
+ * Calendar Tools - CalDAV operations
+ * Exports all calendar-related tools
+ */
+
+export { listCalendars } from './list-calendars.js';
+export { listEvents } from './list-events.js';
+export { createEvent } from './create-event.js';
+export { updateEventFields } from './update-event-fields.js';
+export { updateEventRaw } from './update-event-raw.js';
+export { deleteEvent } from './delete-event.js';
+export { calendarQuery } from './calendar-query.js';
+export { makeCalendar } from './make-calendar.js';
+export { updateCalendar } from './update-calendar.js';
+export { deleteCalendar } from './delete-calendar.js';
+export { calendarMultiGet } from './calendar-multi-get.js';