aiquila-mcp 0.3.9 → 0.3.11

package/dist/auth/store.js

@@ -14,7 +14,9 @@ function ensureDir(dir) {
         mkdirSync(dir, { recursive: true });
     }
     catch (err) {
-        logger.warn({ dir, err }, '[state] Failed to create state directory');
+        // Best-effort: probeStateDir() (called from startup) is the authoritative
+        // check. Logging here would spam non-HTTP transports that never persist.
+        logger.debug({ dir, err }, '[state] mkdir failed (probe will report fatal if writes break)');
     }
 }
 function loadJson(filePath) {
@@ -41,13 +43,50 @@ function saveJson(filePath, data) {
         renameSync(tmp, filePath);
     }
     catch (err) {
-        logger.warn({ file: filePath, err }, '[state] Failed to save state file');
         try {
             unlinkSync(tmp);
         }
         catch {
             // ignore cleanup failure
         }
+        throw err;
+    }
+}
+export class StateDirNotWritableError extends Error {
+    dir;
+    cause;
+    constructor(dir, cause) {
+        super(`State directory ${dir} is not writable (${cause.code}). ` +
+            `Fix volume ownership, then restart. For Docker named volumes:\n` +
+            `  docker compose exec -u 0 mcp chown -R node:node ${dir}\n` +
+            `  docker compose restart mcp`);
+        this.dir = dir;
+        this.cause = cause;
+        this.name = 'StateDirNotWritableError';
+    }
+}
+/**
+ * Verifies the state directory is usable before the server starts accepting
+ * requests. Writes and removes a sentinel file. Throws StateDirNotWritableError
+ * on any filesystem permission / read-only / out-of-space failure so the
+ * caller can log a fatal-level remediation message and exit.
+ */
+export function probeStateDir(dir = stateDir()) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const probe = join(dir, '.write-probe');
+        writeFileSync(probe, String(process.pid), 'utf8');
+        unlinkSync(probe);
+    }
+    catch (err) {
+        const errno = err;
+        if (errno.code === 'EACCES' ||
+            errno.code === 'EPERM' ||
+            errno.code === 'EROFS' ||
+            errno.code === 'ENOSPC') {
+            throw new StateDirNotWritableError(dir, errno);
+        }
+        throw err;
     }
 }
 export class ClientsStore {

package/dist/tools/apps/calendar.js

@@ -464,6 +464,45 @@ function formatCalendar(cal) {
 // ---------------------------------------------------------------------------
 // CalDAV helpers
 // ---------------------------------------------------------------------------
+/**
+ * Resolve a calendar identifier (display name or URL slug) to its URL slug.
+ * Falls back to the input unchanged when no match is found or PROPFIND fails,
+ * so existing slug-based callers keep working.
+ */
+async function resolveCalendarSlug(nameOrSlug) {
+    const config = getNextcloudConfig();
+    const calDavUrl = `${config.url}/remote.php/dav/calendars/${config.user}/`;
+    const propfindBody = `<?xml version="1.0" encoding="UTF-8"?>
+<d:propfind xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
+  <d:prop><d:resourcetype /><d:displayname /></d:prop>
+</d:propfind>`;
+    try {
+        const response = await fetchCalDAV(calDavUrl, {
+            method: 'PROPFIND',
+            body: propfindBody,
+            headers: { Depth: '1' },
+        });
+        if (!response.ok)
+            return nameOrSlug;
+        const text = await response.text();
+        const calendars = parseCalendars(text);
+        for (const cal of calendars) {
+            const slug = cal.url.split('/').filter(Boolean).pop() ?? '';
+            if (slug === nameOrSlug)
+                return nameOrSlug;
+        }
+        const lower = nameOrSlug.toLowerCase();
+        for (const cal of calendars) {
+            if (cal.displayName.toLowerCase() === lower) {
+                return cal.url.split('/').filter(Boolean).pop() ?? nameOrSlug;
+            }
+        }
+    }
+    catch {
+        /* fall through — keep original input */
+    }
+    return nameOrSlug;
+}
 /**
  * Assert that a calendar supports VEVENT. Throws a descriptive error if not,
  * so create_event fails early with a useful message instead of a 403 from the server.
@@ -481,7 +520,9 @@ async function assertCalendarSupportsEvents(calendarUrl, calendarName) {
         headers: { Depth: '0' },
     });
     if (response.status === 404) {
-        throw new Error(`Calendar "${calendarName}" not found. Use list_calendars to find available calendar names.`);
+        const err = new Error(`Calendar "${calendarName}" not found. Use list_calendars to find available calendar names.`);
+        err.code = 'CALENDAR_NOT_FOUND';
+        throw err;
     }
     if (!response.ok)
         return; // Can't check — let the server reject if needed
@@ -504,7 +545,8 @@ async function assertCalendarSupportsEvents(calendarUrl, calendarName) {
  */
 async function resolveEventByUid(calendarName, uid) {
     const config = getNextcloudConfig();
-    const calDavUrl = `${config.url}/remote.php/dav/calendars/${config.user}/${calendarName}/`;
+    let slug = calendarName;
+    const buildUrl = () => `${config.url}/remote.php/dav/calendars/${config.user}/${slug}/`;
     const reportBody = `<?xml version="1.0" encoding="UTF-8"?>
 <c:calendar-query xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
   <d:prop>
@@ -521,11 +563,22 @@ async function resolveEventByUid(calendarName, uid) {
     </c:comp-filter>
   </c:filter>
 </c:calendar-query>`;
-    const response = await fetchCalDAV(calDavUrl, {
+    let response = await fetchCalDAV(buildUrl(), {
         method: 'REPORT',
         body: reportBody,
         headers: { Depth: '1' },
     });
+    if (response.status === 404) {
+        const resolved = await resolveCalendarSlug(calendarName);
+        if (resolved !== calendarName) {
+            slug = resolved;
+            response = await fetchCalDAV(buildUrl(), {
+                method: 'REPORT',
+                body: reportBody,
+                headers: { Depth: '1' },
+            });
+        }
+    }
     if (!response.ok) {
         const errorText = await response.text();
         throw new Error(`CalDAV REPORT failed for calendar "${calendarName}": ${response.status} - ${errorText}`);
@@ -639,7 +692,8 @@ export const listEventsTool = {
     handler: async (args) => {
         try {
             const config = getNextcloudConfig();
-            const calDavUrl = `${config.url}/remote.php/dav/calendars/${config.user}/${args.calendarName}/`;
+            let slug = args.calendarName;
+            const buildUrl = () => `${config.url}/remote.php/dav/calendars/${config.user}/${slug}/`;
             const limit = args.limit || 50;
             // Default time range: today to 30 days from now
             const now = new Date();
@@ -663,11 +717,22 @@ export const listEventsTool = {
     </c:comp-filter>
   </c:filter>
 </c:calendar-query>`;
-            const response = await fetchCalDAV(calDavUrl, {
+            let response = await fetchCalDAV(buildUrl(), {
                 method: 'REPORT',
                 body: reportBody,
                 headers: { Depth: '1' },
             });
+            if (response.status === 404) {
+                const resolved = await resolveCalendarSlug(args.calendarName);
+                if (resolved !== args.calendarName) {
+                    slug = resolved;
+                    response = await fetchCalDAV(buildUrl(), {
+                        method: 'REPORT',
+                        body: reportBody,
+                        headers: { Depth: '1' },
+                    });
+                }
+            }
             if (!response.ok) {
                 const errorText = await response.text();
                 throw new Error(`CalDAV REPORT failed for calendar "${args.calendarName}": ${response.status} - ${errorText}`);
@@ -824,10 +889,30 @@ export const createEventTool = {
         try {
             const config = getNextcloudConfig();
             const eventUid = `${Date.now()}-${Math.random().toString(36).substring(7)}`;
-            const calendarBaseUrl = `${config.url}/remote.php/dav/calendars/${config.user}/${args.calendarName}/`;
+            let slug = args.calendarName;
+            const baseUrl = () => `${config.url}/remote.php/dav/calendars/${config.user}/${slug}/`;
+            // Validate the calendar supports VEVENT before building and sending the iCal payload.
+            // If the original name is a display name (not a slug), retry once after resolving.
+            try {
+                await assertCalendarSupportsEvents(baseUrl(), args.calendarName);
+            }
+            catch (err) {
+                if (err.code === 'CALENDAR_NOT_FOUND') {
+                    const resolved = await resolveCalendarSlug(args.calendarName);
+                    if (resolved !== args.calendarName) {
+                        slug = resolved;
+                        await assertCalendarSupportsEvents(baseUrl(), args.calendarName);
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+                else {
+                    throw err;
+                }
+            }
+            const calendarBaseUrl = baseUrl();
             const calDavUrl = `${calendarBaseUrl}${eventUid}.ics`;
-            // Validate the calendar supports VEVENT before building and sending the iCal payload
-            await assertCalendarSupportsEvents(calendarBaseUrl, args.calendarName);
             const now = icalNow();
             const isAllDay = args.dtstart.length === 8;
             const tzid = !isAllDay ? args.tzid : undefined;
@@ -930,7 +1015,7 @@ export const createEventTool = {
             }
             // Verify the event was actually persisted
             try {
-                await resolveEventByUid(args.calendarName, eventUid);
+                await resolveEventByUid(slug, eventUid);
             }
             catch {
                 throw new Error(`Event creation appeared to succeed (HTTP ${response.status}) but the event ` +

package/dist/tools/apps/mail.js

@@ -2,13 +2,24 @@
 import { z } from 'zod';
 import { fetchMailAPI } from '../../client/mail.js';
 import { fetchOCS } from '../../client/ocs.js';
+// Invisible padding characters used in newsletter preheaders
+// (U+034F, U+00AD, U+200B–U+200D, U+FEFF)
+const INVISIBLE_CHARS_RE = /[\u034F\u00AD\u200B-\u200D\uFEFF]/g;
 // ── Helpers ──────────────────────────────────────────────────────────
 function stripHtml(html) {
     let text = html;
     // Remove style and script blocks
     text = text.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '');
     text = text.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '');
-    // Convert line-break tags to newlines
+    // Image-based newsletters carry content in alt attributes
+    text = text.replace(/<img[^>]+alt="([^"]{2,})"[^>]*\/?>/gi, (_, alt) => `\n${alt.trim()}\n`);
+    text = text.replace(/<img[^>]+alt='([^']{2,})'[^>]*\/?>/gi, (_, alt) => `\n${alt.trim()}\n`);
+    text = text.replace(/<img[^>]*\/?>/gi, '');
+    // Block-level structure
+    text = text.replace(/<\/h[1-6]>/gi, '\n\n');
+    text = text.replace(/<\/tr>/gi, '\n');
+    text = text.replace(/<td[^>]*>/gi, ' ');
+    text = text.replace(/<th[^>]*>/gi, ' ');
     text = text.replace(/<br\s*\/?>/gi, '\n');
     text = text.replace(/<\/p>/gi, '\n\n');
     text = text.replace(/<\/div>/gi, '\n');
@@ -23,7 +34,15 @@ function stripHtml(html) {
     text = text.replace(/&quot;/g, '"');
     text = text.replace(/&#39;/g, "'");
     text = text.replace(/&nbsp;/g, ' ');
-    // Collapse multiple blank lines
+    text = text.replace(/&#\d+;/g, '');
+    // Strip invisible preheader padding
+    text = text.replace(INVISIBLE_CHARS_RE, '');
+    // Trim per-line and drop blanks before collapsing
+    text = text
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .join('\n');
     text = text.replace(/\n{3,}/g, '\n\n');
     return text.trim();
 }
@@ -80,17 +99,20 @@ const listMailboxesTool = {
     }),
     handler: async (args) => {
         try {
-            const response = await fetchMailAPI(`/accounts/${args.accountId}/mailboxes`);
+            const response = await fetchMailAPI(`/mailboxes?accountId=${args.accountId}`);
             if (!response.ok) {
                 throw new Error(`HTTP ${response.status}: ${await response.text()}`);
             }
-            const mailboxes = (await response.json());
+            const data = (await response.json());
+            const mailboxes = Array.isArray(data) ? data : (data.mailboxes ?? []);
             if (mailboxes.length === 0) {
                 return { content: [{ type: 'text', text: 'No mailboxes found.' }] };
             }
             const lines = mailboxes.map((m) => {
+                const id = m.databaseId ?? m.id;
+                const name = m.displayName ?? m.name;
                 const unread = m.unread > 0 ? ` (${m.unread} unread)` : '';
-                return `• ${m.name}${unread} — ID: ${m.id}`;
+                return `• ${name}${unread} — ID: ${id}`;
             });
             return {
                 content: [{ type: 'text', text: `Mailboxes:\n${lines.join('\n')}` }],
@@ -128,19 +150,24 @@ const listMessagesTool = {
     }),
     handler: async (args) => {
         try {
-            const queryParams = {};
+            const queryParts = [`mailboxId=${args.mailboxId}`];
             if (args.limit)
-                queryParams.limit = String(args.limit);
+                queryParts.push(`limit=${args.limit}`);
             if (args.cursor)
-                queryParams.cursor = String(args.cursor);
+                queryParts.push(`cursor=${args.cursor}`);
             if (args.filter && args.filter !== 'all')
-                queryParams.filter = args.filter;
-            const response = await fetchOCS(`/ocs/v2.php/apps/mail/api/v1/mailboxes/${args.mailboxId}/messages`, { queryParams });
-            const messages = response.ocs.data;
+                queryParts.push(`filter=${args.filter}`);
+            const response = await fetchMailAPI(`/messages?${queryParts.join('&')}`);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+            }
+            const data = (await response.json());
+            const messages = Array.isArray(data) ? data : (data.messages ?? data.data ?? []);
             if (!messages || messages.length === 0) {
                 return { content: [{ type: 'text', text: 'No messages found.' }] };
             }
             const lines = messages.map((msg) => {
+                const id = msg.databaseId ?? msg.id;
                 const flags = [];
                 if (!msg.flags.seen)
                     flags.push('UNREAD');
@@ -148,15 +175,16 @@ const listMessagesTool = {
                     flags.push('starred');
                 if (msg.flags.answered)
                     flags.push('replied');
-                if (msg.hasAttachments)
+                if (msg.flags?.hasAttachments ?? msg.hasAttachments)
                     flags.push('attachment');
                 const flagStr = flags.length > 0 ? ` [${flags.join(', ')}]` : '';
                 const from = formatRecipients(msg.from);
-                return `• ${msg.subject}${flagStr}\n  From: ${from} | ${formatDate(msg.dateInt)} | ID: ${msg.id}`;
+                return `• ${msg.subject}${flagStr}\n  From: ${from} | ${formatDate(msg.dateInt)} | ID: ${id}`;
             });
             let text = `Messages (${messages.length}):\n${lines.join('\n')}`;
             if (messages.length >= (args.limit || 20)) {
-                const lastId = messages[messages.length - 1].id;
+                const last = messages[messages.length - 1];
+                const lastId = last.databaseId ?? last.id;
                 text += `\n\nMore messages available. Use cursor: ${lastId} to load next page.`;
             }
             return { content: [{ type: 'text', text }] };
@@ -182,29 +210,25 @@ const readMessageTool = {
     }),
     handler: async (args) => {
         try {
-            // Fetch metadata via OCS
-            const metaResponse = await fetchOCS(`/ocs/v2.php/apps/mail/api/v1/message/${args.messageId}`);
-            const meta = metaResponse.ocs.data;
-            // Fetch body via Mail REST API
+            // Mail 5.x: /messages/{id}/body returns both metadata and body in one call.
             const bodyResponse = await fetchMailAPI(`/messages/${args.messageId}/body`);
-            let bodyText = '';
-            if (bodyResponse.ok) {
-                const bodyData = (await bodyResponse.json());
-                const rawBody = bodyData.body || bodyData.data || '';
-                bodyText = stripHtml(rawBody);
+            if (!bodyResponse.ok) {
+                throw new Error(`HTTP ${bodyResponse.status}: ${await bodyResponse.text()}`);
             }
-            // Format output
-            const from = formatRecipients(meta.from);
-            const to = formatRecipients(meta.to);
-            const cc = formatRecipients(meta.cc || []);
-            const date = meta.dateInt ? formatDate(meta.dateInt) : 'Unknown';
-            const subject = meta.subject || '(No subject)';
+            const data = (await bodyResponse.json());
+            const rawBody = data.body || '';
+            const bodyText = rawBody ? stripHtml(rawBody) : '(no body)';
+            const from = formatRecipients(data.from);
+            const to = formatRecipients(data.to);
+            const cc = formatRecipients(data.cc || []);
+            const date = data.dateInt ? formatDate(data.dateInt) : 'Unknown';
+            const subject = data.subject || '(No subject)';
             let text = `Subject: ${subject}\nFrom: ${from}\nTo: ${to}`;
             if (cc)
                 text += `\nCc: ${cc}`;
             text += `\nDate: ${date}`;
             text += `\n${'─'.repeat(60)}\n${bodyText}`;
-            const attachments = meta.attachments;
+            const attachments = data.attachments;
             if (attachments && attachments.length > 0) {
                 text += `\n${'─'.repeat(60)}\nAttachments:`;
                 for (const att of attachments) {
@@ -227,6 +251,73 @@ const readMessageTool = {
         }
     },
 };
+const searchMessagesTool = {
+    name: 'mail_search_messages',
+    description: 'Search email messages across all mailboxes by subject or sender. ' +
+        'Returns matches with message IDs usable in mail_read_message. ' +
+        'For threaded conversations all message IDs in the thread are returned.',
+    inputSchema: z.object({
+        query: z.string().describe('Search query (matches subject and sender name)'),
+        limit: z.number().min(1).max(20).optional().describe('Max results (default: 10)'),
+    }),
+    handler: async (args) => {
+        try {
+            const response = await fetchOCS('/ocs/v2.php/search/providers/mail/search', {
+                queryParams: {
+                    term: args.query,
+                    limit: String(args.limit ?? 10),
+                    format: 'json',
+                },
+            });
+            const results = response.ocs.data;
+            if (!results.entries?.length) {
+                return {
+                    content: [{ type: 'text', text: `No messages found for "${args.query}".` }],
+                };
+            }
+            const lines = await Promise.all(results.entries.map(async (entry) => {
+                const match = entry.resourceUrl?.match(/\/box\/(\d+)\/thread\/(\d+)/);
+                if (!match)
+                    return `• ${entry.title}\n  ${entry.subline}`;
+                const msgId = parseInt(match[2], 10);
+                try {
+                    const threadResp = await fetchMailAPI(`/messages/${msgId}/thread`);
+                    if (!threadResp.ok)
+                        throw new Error('thread fetch failed');
+                    const threadData = (await threadResp.json());
+                    const msgs = (Array.isArray(threadData)
+                        ? threadData
+                        : (threadData.messages ?? []));
+                    const sorted = msgs.sort((a, b) => (a.dateInt ?? 0) - (b.dateInt ?? 0));
+                    if (sorted.length <= 1) {
+                        return `• ${entry.title}\n  ${entry.subline} | ID: ${msgId}`;
+                    }
+                    const idList = sorted.map((m) => (m.databaseId ?? m.id)).join(', ');
+                    return `• ${entry.title}\n  ${entry.subline} | Thread (${sorted.length} messages) IDs: ${idList}`;
+                }
+                catch {
+                    return `• ${entry.title}\n  ${entry.subline} | ID: ${msgId}`;
+                }
+            }));
+            let text = `Search results for "${args.query}" (${results.entries.length}):\n${lines.join('\n')}`;
+            if (results.isPaginated && results.cursor) {
+                text += `\n\nMore results available.`;
+            }
+            return { content: [{ type: 'text', text }] };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error searching messages: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    },
+};
 const sendMessageTool = {
     name: 'mail_send_message',
     description: 'Send an email message through Nextcloud Mail. Requires an account ID and recipient addresses.',
@@ -411,6 +502,7 @@ export const mailTools = [
     listMailboxesTool,
     listMessagesTool,
     readMessageTool,
+    searchMessagesTool,
     sendMessageTool,
     deleteMessageTool,
     moveMessageTool,

package/dist/tools/system/search.js

@@ -62,8 +62,15 @@ export const unifiedSearchTool = {
                     content: [{ type: 'text', text: 'No search providers available.' }],
                 };
             }
-            // Sort by order and take top providers (max 5 to avoid flooding)
-            const topProviders = [...providers].sort((a, b) => a.order - b.order).slice(0, 5);
+            // Always include the most useful providers; fill remaining slots by order.
+            // Without this, mail (order 20) and calendar (order 30) fall outside the
+            // top 5 on a typical install and are silently never searched.
+            const PRIORITY_IDS = ['files', 'mail', 'calendar', 'notes'];
+            const prioritized = PRIORITY_IDS.map((id) => providers.find((p) => p.id === id)).filter((p) => p !== undefined);
+            const rest = providers
+                .filter((p) => !PRIORITY_IDS.includes(p.id))
+                .sort((a, b) => a.order - b.order);
+            const topProviders = [...prioritized, ...rest].slice(0, 6);
             const searches = await Promise.allSettled(topProviders.map((p) => searchProvider(p.id, args.query, args.limit)));
             const output = [];
             for (const result of searches) {

package/dist/transports/http.js

@@ -7,6 +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 { loginHandler } from '../auth/login.js';
 import { logger } from '../logger.js';
 import { fetchStatus } from '../client/ocs.js';
@@ -176,6 +177,17 @@ export async function startHttp() {
         if (!registrationEnabled && !hasStaticClient) {
             logger.warn('No clients configured. Set MCP_CLIENT_ID or MCP_REGISTRATION_ENABLED=true');
         }
+        try {
+            probeStateDir();
+        }
+        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);
+            }
+            throw err;
+        }
         const provider = new NextcloudOAuthProvider();
         // When gated dynamic registration is desired, require a bearer token on POST /register.
         if (registrationEnabled && registrationToken) {

package/package.json

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