aiquila-mcp 0.3.11 → 0.3.13

package/dist/auth/store.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 import { randomUUID } from 'node:crypto';
 import { readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { logger } from '../logger.js';
 const CODE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const REFRESH_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
@@ -9,6 +9,39 @@ const DEFAULT_STATE_DIR = '/app/state';
 function stateDir() {
     return (process.env.MCP_AUTH_STATE_DIR ?? DEFAULT_STATE_DIR).replace(/\/+$/, '');
 }
+// True once we've emitted the loud "state dir not writable" warning, so the
+// startup probe and the first failed persist warn at most once between them —
+// subsequent persist failures drop to debug to avoid flooding the logs.
+let warnedUnwritable = false;
+/**
+ * Operator-facing remediation for an unwritable state directory. The fix is to
+ * recreate the (root-owned) Docker named volume so a fresh one inherits the
+ * image's node ownership — `docker compose exec ... chown` cannot be used here
+ * because the container would otherwise be in a crash loop. See discussion #342.
+ */
+export function stateUnwritableMessage(dir, code) {
+    return (`State directory ${dir} is not writable${code ? ` (${code})` : ''} — ` +
+        `OAuth tokens will NOT persist; clients must re-authenticate after every restart. ` +
+        `To restore persistence, recreate the state volume (this clears existing tokens; ` +
+        `clients re-authenticate once):\n` +
+        `  docker compose down mcp && docker volume rm <project>_mcp_state && docker compose up -d mcp\n` +
+        `See https://github.com/elgorro/aiquila/discussions/342`);
+}
+/**
+ * Marks the unwritable-state warning as already emitted (called by the startup
+ * probe in the HTTP transport) so the first failed persist does not warn twice.
+ */
+export function markStateUnwritableWarned() {
+    warnedUnwritable = true;
+}
+function warnPersistFailed(dir, code, err) {
+    if (warnedUnwritable) {
+        logger.debug({ dir, code, err }, '[state] persist failed — state dir not writable');
+        return;
+    }
+    warnedUnwritable = true;
+    logger.warn({ dir, code }, stateUnwritableMessage(dir, code));
+}
 function ensureDir(dir) {
     try {
         mkdirSync(dir, { recursive: true });
@@ -49,7 +82,10 @@ function saveJson(filePath, data) {
         catch {
             // ignore cleanup failure
         }
-        throw err;
+        // Graceful degradation: a persist failure must never crash a request or the
+        // process. The server keeps running with in-memory state (tokens just won't
+        // survive a restart) and warns the operator how to fix it. See discussion #342.
+        warnPersistFailed(dirname(filePath), err.code, err);
     }
 }
 export class StateDirNotWritableError extends Error {

package/dist/tools/apps/calendar.js

@@ -175,6 +175,28 @@ function ensureVTimezone(icalData, tzid) {
     const vtz = buildVTimezone(tzid);
     return icalData.replace(/BEGIN:VEVENT/, `${vtz}\r\nBEGIN:VEVENT`);
 }
+/**
+ * Build a DISPLAY VALARM block firing `minutes` before the event. Returns an
+ * empty string for non-positive values (those are skipped, not emitted).
+ */
+function buildVAlarm(minutes) {
+    if (minutes <= 0)
+        return '';
+    const totalSeconds = minutes * 60;
+    const hours = Math.floor(totalSeconds / 3600);
+    const mins = Math.floor((totalSeconds % 3600) / 60);
+    const durationStr = `-PT${hours > 0 ? hours + 'H' : ''}${mins > 0 ? mins + 'M' : ''}`;
+    return `BEGIN:VALARM\r\nACTION:DISPLAY\r\nDESCRIPTION:Reminder\r\nTRIGGER:${durationStr}\r\nEND:VALARM`;
+}
+/**
+ * Merge the single `alarm` and the `alarms` array into one list of reminder
+ * minutes. `alarms` entries come first, then `alarm` (if a positive number).
+ * The MCP-client-friendly split exists because a union type's anyOf JSON Schema
+ * is not reliably honored, so a dedicated array parameter is needed.
+ */
+function collectAlarmMinutes(alarm, alarms) {
+    return [...(alarms ?? []), ...(alarm !== undefined && alarm !== null ? [alarm] : [])];
+}
 // ---------------------------------------------------------------------------
 // Parsing
 // ---------------------------------------------------------------------------
@@ -879,7 +901,11 @@ export const createEventTool = {
         alarm: z
             .number()
             .optional()
-            .describe('Reminder in minutes before the event (e.g. 15 for 15 min before)'),
+            .describe('Single reminder in minutes before the event (e.g. 15 for 15 min before). For multiple reminders use alarms[].'),
+        alarms: z
+            .array(z.number())
+            .optional()
+            .describe('Multiple reminders in minutes before the event (e.g. [1440, 60] for 1 day and 1 hour before). Combined with alarm if both are set.'),
         tzid: z
             .string()
             .optional()
@@ -990,14 +1016,11 @@ export const createEventTool = {
                     vevent += `\r\n${atLine}`;
                 }
             }
-            // Add alarm
-            if (args.alarm !== undefined && args.alarm > 0) {
-                const sign = '-';
-                const totalSeconds = args.alarm * 60;
-                const hours = Math.floor(totalSeconds / 3600);
-                const minutes = Math.floor((totalSeconds % 3600) / 60);
-                const durationStr = `${sign}PT${hours > 0 ? hours + 'H' : ''}${minutes > 0 ? minutes + 'M' : ''}`;
-                vevent += `\r\nBEGIN:VALARM\r\nACTION:DISPLAY\r\nDESCRIPTION:Reminder\r\nTRIGGER:${durationStr}\r\nEND:VALARM`;
+            // Add alarms — one VALARM block per reminder (alarm + alarms merged)
+            for (const mins of collectAlarmMinutes(args.alarm, args.alarms)) {
+                const valarm = buildVAlarm(mins);
+                if (valarm)
+                    vevent += `\r\n${valarm}`;
             }
             vevent += `\r\nEND:VEVENT\r\nEND:VCALENDAR`;
             const response = await fetchCalDAV(calDavUrl, {
@@ -1075,7 +1098,11 @@ export const updateEventTool = {
             .number()
             .nullable()
             .optional()
-            .describe('Reminder in minutes before the event, or null to remove existing alarm'),
+            .describe('Single reminder in minutes before the event, or null to remove all existing alarms. For multiple reminders use alarms[].'),
+        alarms: z
+            .array(z.number())
+            .optional()
+            .describe('Multiple reminders in minutes before the event (e.g. [1440, 60]). Replaces existing alarms; combined with alarm if both are set.'),
         attendees: z
             .array(z.object({
             email: z.string().describe('Attendee email'),
@@ -1138,17 +1165,17 @@ export const updateEventTool = {
                     modified = modified.replace(/END:VEVENT/, `CATEGORIES:${args.categories.map(escapeICalValue).join(',')}\r\nEND:VEVENT`);
                 }
             }
-            // Handle alarm (VALARM)
-            if (args.alarm !== undefined) {
-                // Remove existing VALARM block
+            // Handle alarms (VALARM). Any alarm/alarms input replaces all existing
+            // VALARM blocks; alarm:null clears them without adding new ones.
+            if (args.alarm !== undefined || args.alarms !== undefined) {
                 modified = modified.replace(/BEGIN:VALARM[\s\S]*?END:VALARM\r?\n?/g, '');
-                if (args.alarm !== null && args.alarm > 0) {
-                    const sign = '-';
-                    const totalSeconds = args.alarm * 60;
-                    const hours = Math.floor(totalSeconds / 3600);
-                    const minutes = Math.floor((totalSeconds % 3600) / 60);
-                    const durationStr = `${sign}PT${hours > 0 ? hours + 'H' : ''}${minutes > 0 ? minutes + 'M' : ''}`;
-                    modified = modified.replace(/END:VEVENT/, `BEGIN:VALARM\r\nACTION:DISPLAY\r\nDESCRIPTION:Reminder\r\nTRIGGER:${durationStr}\r\nEND:VALARM\r\nEND:VEVENT`);
+                if (args.alarm !== null) {
+                    for (const mins of collectAlarmMinutes(args.alarm, args.alarms)) {
+                        const valarm = buildVAlarm(mins);
+                        if (valarm) {
+                            modified = modified.replace(/END:VEVENT/, `${valarm}\r\nEND:VEVENT`);
+                        }
+                    }
                 }
             }
             // Handle attendees

package/dist/tools/apps/mail.js

@@ -1,4 +1,6 @@
 // SPDX-License-Identifier: MIT
+import { spawnSync } from 'node:child_process';
+import { writeFileSync, unlinkSync } from 'node:fs';
 import { z } from 'zod';
 import { fetchMailAPI } from '../../client/mail.js';
 import { fetchOCS } from '../../client/ocs.js';
@@ -232,8 +234,10 @@ const readMessageTool = {
             if (attachments && attachments.length > 0) {
                 text += `\n${'─'.repeat(60)}\nAttachments:`;
                 for (const att of attachments) {
-                    text += `\n  • ${att.fileName} (${att.size} bytes)`;
+                    const idPart = att.id !== undefined ? `[id: ${att.id}] ` : '';
+                    text += `\n  • ${idPart}${att.fileName} (${att.size} bytes)`;
                 }
+                text += `\n(Use mail_get_attachment with the message ID and an attachment id to read one.)`;
             }
             text += `\n\nMessage ID: ${args.messageId}`;
             return { content: [{ type: 'text', text }] };
@@ -251,6 +255,96 @@ const readMessageTool = {
         }
     },
 };
+const getAttachmentTool = {
+    name: 'mail_get_attachment',
+    description: 'Download an email attachment by message ID and attachment ID. ' +
+        'Returns text for text files and calendar invites (ICS), image data for images, ' +
+        'extracted text for PDFs (requires pdftotext). ' +
+        'Attachment IDs are shown in mail_read_message output.',
+    inputSchema: z.object({
+        messageId: z.number().describe('Message ID (from mail_read_message)'),
+        attachmentId: z.string().describe('Attachment ID shown in mail_read_message (e.g. "2")'),
+    }),
+    handler: async (args) => {
+        try {
+            const response = await fetchMailAPI(`/messages/${args.messageId}/attachment/${args.attachmentId}`);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+            }
+            const contentType = response.headers.get('content-type') ?? 'application/octet-stream';
+            const mimeType = contentType.split(';')[0].trim();
+            if (mimeType.startsWith('text/') ||
+                mimeType === 'application/json' ||
+                mimeType === 'application/ics') {
+                const text = await response.text();
+                return { content: [{ type: 'text', text }] };
+            }
+            if (mimeType.startsWith('image/')) {
+                const buffer = await response.arrayBuffer();
+                const base64 = Buffer.from(buffer).toString('base64');
+                return { content: [{ type: 'image', data: base64, mimeType }] };
+            }
+            if (mimeType === 'application/pdf') {
+                const buffer = await response.arrayBuffer();
+                const safeId = String(args.messageId).replace(/[^a-zA-Z0-9_-]/g, '') +
+                    '_' +
+                    String(args.attachmentId).replace(/[^a-zA-Z0-9_-]/g, '');
+                const tmpFile = `/tmp/mcp_att_${safeId}.pdf`;
+                try {
+                    writeFileSync(tmpFile, Buffer.from(buffer));
+                    const result = spawnSync('pdftotext', [tmpFile, '-'], { encoding: 'utf8' });
+                    unlinkSync(tmpFile);
+                    if (result.status === 0 && result.stdout.trim().length > 0) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `[UNTRUSTED EXTERNAL CONTENT - PDF ATTACHMENT]\n${result.stdout}\n[END EXTERNAL CONTENT]`,
+                                },
+                            ],
+                        };
+                    }
+                }
+                catch {
+                    try {
+                        unlinkSync(tmpFile);
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Attachment: ${mimeType}, ${(buffer.byteLength / 1024).toFixed(1)} KB. Could not extract text (pdftotext unavailable or empty).`,
+                        },
+                    ],
+                };
+            }
+            const buffer = await response.arrayBuffer();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Attachment: ${mimeType}, ${(buffer.byteLength / 1024).toFixed(1)} KB. Cannot be read inline.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error downloading attachment: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    },
+};
 const searchMessagesTool = {
     name: 'mail_search_messages',
     description: 'Search email messages across all mailboxes by subject or sender. ' +
@@ -502,6 +596,7 @@ export const mailTools = [
     listMailboxesTool,
     listMessagesTool,
     readMessageTool,
+    getAttachmentTool,
     searchMessagesTool,
     sendMessageTool,
     deleteMessageTool,

package/dist/transports/http.js

@@ -7,7 +7,7 @@ import { mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js';
 import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
 import { createServer, SERVER_VERSION } from '../server.js';
 import { NextcloudOAuthProvider } from '../auth/provider.js';
-import { probeStateDir, StateDirNotWritableError } from '../auth/store.js';
+import { probeStateDir, StateDirNotWritableError, stateUnwritableMessage, markStateUnwritableWarned, } from '../auth/store.js';
 import { loginHandler } from '../auth/login.js';
 import { logger } from '../logger.js';
 import { fetchStatus } from '../client/ocs.js';
@@ -182,11 +182,16 @@ export async function startHttp() {
         }
         catch (err) {
             if (err instanceof StateDirNotWritableError) {
-                logger.fatal({ dir: err.dir, code: err.cause.code }, `[startup] State directory is not writable — refresh tokens cannot be persisted. ` +
-                    `Fix volume ownership and restart:\n  docker compose exec -u 0 mcp chown -R node:node ${err.dir}\n  docker compose restart mcp`);
-                process.exit(1);
+                // Degrade gracefully rather than crash-loop: the server still serves
+                // requests, it just can't persist OAuth tokens until the operator fixes
+                // the volume. Crashing here was un-fixable under `restart: unless-stopped`
+                // because `docker compose exec` needs a running container (discussion #342).
+                logger.warn({ dir: err.dir, code: err.cause.code }, stateUnwritableMessage(err.dir, err.cause.code));
+                markStateUnwritableWarned();
+            }
+            else {
+                throw err;
             }
-            throw err;
         }
         const provider = new NextcloudOAuthProvider();
         // When gated dynamic registration is desired, require a bearer token on POST /register.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiquila-mcp",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "description": "AIquila - MCP server for Nextcloud integration",
   "type": "module",
   "main": "dist/index.js",