aiquila-mcp 0.3.5 → 0.3.7

package/dist/client/text.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MIT
+import { getNextcloudConfig } from '../tools/types.js';
+import { logger } from '../logger.js';
+import { ApiError } from './aiquila.js';
+/**
+ * Make an authenticated request to the Nextcloud Text app OCS API.
+ *
+ * Base path: /ocs/v2.php/apps/text
+ * Unwraps the OCS envelope and returns `ocs.data`.
+ * Throws {@link ApiError} on HTTP errors or non-success OCS status codes.
+ */
+export async function fetchTextAPI(endpoint, options = {}) {
+    const config = getNextcloudConfig();
+    const auth = Buffer.from(`${config.user}:${config.password}`).toString('base64');
+    let url = `${config.url}/ocs/v2.php/apps/text${endpoint}`;
+    if (options.queryParams) {
+        const params = new URLSearchParams(options.queryParams);
+        url += `?${params.toString()}`;
+    }
+    const headers = {
+        Authorization: `Basic ${auth}`,
+        'OCS-APIRequest': 'true',
+        Accept: 'application/json',
+    };
+    let body;
+    if (options.body !== undefined) {
+        body = JSON.stringify(options.body);
+        headers['Content-Type'] = 'application/json';
+    }
+    const method = options.method ?? 'GET';
+    const t0 = Date.now();
+    const response = await fetch(url, { method, headers, body });
+    logger.trace({ method, url, status: response.status, ms: Date.now() - t0 }, '[text] HTTP');
+    if (!response.ok) {
+        const text = await response.text();
+        throw new ApiError(response.status, response.statusText, text);
+    }
+    if (response.status === 204) {
+        return undefined;
+    }
+    const contentType = response.headers.get('content-type') ?? '';
+    if (!contentType.includes('application/json')) {
+        return undefined;
+    }
+    const json = (await response.json());
+    const code = json?.ocs?.meta?.statuscode;
+    if (code !== undefined && code !== 200 && code !== 100) {
+        throw new ApiError(code, json.ocs.meta.status ?? 'error', json.ocs.meta.message ?? '');
+    }
+    return json.ocs.data;
+}

package/dist/tool-registry.js

@@ -36,6 +36,7 @@ import { versionsTools } from './tools/apps/versions.js';
 import { projectsTools } from './tools/apps/projects.js';
 import { pollsTools } from './tools/apps/polls.js';
 import { formsTools } from './tools/apps/forms.js';
+import { textTools } from './tools/apps/text.js';
 /**
  * Single source of truth for tool-to-Nextcloud-app mapping.
  *
@@ -76,6 +77,7 @@ export const TOOL_REGISTRY = [
     { category: 'bookmarks', appIds: ['bookmarks'], tools: bookmarksTools },
     { category: 'polls', appIds: ['polls'], tools: pollsTools },
     { category: 'forms', appIds: ['forms'], tools: formsTools },
+    { category: 'text', appIds: ['text'], tools: textTools },
     { category: 'assistant', appIds: ['assistant'], tools: assistantTools },
     { category: 'translate', appIds: ['text_translate', 'translate'], tools: translateTools },
     { category: 'user_status', appIds: ['user_status'], tools: userStatusTools },

package/dist/tools/apps/calendar.js

@@ -52,17 +52,129 @@ function setICalProperty(icalData, propName, value) {
     }
     return icalData.replace(/END:VEVENT/, `${propName}:${value}\r\nEND:VEVENT`);
 }
-function setICalDateProperty(icalData, propName, value) {
+function setICalDateProperty(icalData, propName, value, tzid) {
     const regex = new RegExp(`^${propName}(;[^:]*)?:.*$`, 'm');
     if (value === null) {
         return icalData.replace(regex, '').replace(/(\r?\n){2,}/g, '\r\n');
     }
-    const formatted = value.length === 8 ? `${propName};VALUE=DATE:${value}` : `${propName}:${value}`;
+    let formatted;
+    if (value.length === 8) {
+        formatted = `${propName};VALUE=DATE:${value}`;
+    }
+    else if (tzid) {
+        formatted = `${propName};TZID=${tzid}:${normalizeLocalICal(value, tzid)}`;
+    }
+    else {
+        formatted = `${propName}:${value}`;
+    }
     if (regex.test(icalData)) {
         return icalData.replace(regex, formatted);
     }
     return icalData.replace(/END:VEVENT/, `${formatted}\r\nEND:VEVENT`);
 }
+/**
+ * Format the UTC offset for a given IANA zone at a specific instant.
+ * Returns "+HHMM" or "-HHMM" (e.g. "+0200", "-0500", "+0000").
+ */
+function getTimezoneOffset(tzid, date) {
+    const fmt = new Intl.DateTimeFormat('en-US', {
+        timeZone: tzid,
+        timeZoneName: 'longOffset',
+    });
+    const tzPart = fmt.formatToParts(date).find((p) => p.type === 'timeZoneName')?.value || 'GMT';
+    // tzPart is "GMT", "GMT+02:00", "GMT-05:30", or "GMT+5:45" depending on engine
+    const m = tzPart.match(/GMT([+-])(\d{1,2})(?::(\d{2}))?/);
+    if (!m)
+        return '+0000';
+    const sign = m[1];
+    const hh = m[2].padStart(2, '0');
+    const mm = m[3] ?? '00';
+    return `${sign}${hh}${mm}`;
+}
+/**
+ * Build a minimal but RFC 5545-conformant VTIMEZONE component for the given
+ * IANA zone. Uses two reference instants in the current year to detect DST.
+ * No external tzdata required — sufficient for iOS / Thunderbird to accept
+ * the event and apply the TZID correctly to upcoming occurrences.
+ */
+export function buildVTimezone(tzid) {
+    const year = new Date().getUTCFullYear();
+    const janOffset = getTimezoneOffset(tzid, new Date(Date.UTC(year, 0, 15)));
+    const julOffset = getTimezoneOffset(tzid, new Date(Date.UTC(year, 6, 15)));
+    const lines = ['BEGIN:VTIMEZONE', `TZID:${tzid}`];
+    if (janOffset === julOffset) {
+        lines.push('BEGIN:STANDARD', 'DTSTART:19700101T000000', `TZOFFSETFROM:${janOffset}`, `TZOFFSETTO:${janOffset}`, `TZNAME:${tzid}`, 'END:STANDARD');
+    }
+    else {
+        // Higher numeric offset = daylight, lower = standard (works for both hemispheres)
+        const standardOffset = janOffset < julOffset ? janOffset : julOffset;
+        const daylightOffset = janOffset < julOffset ? julOffset : janOffset;
+        lines.push('BEGIN:STANDARD', 'DTSTART:19701101T000000', `TZOFFSETFROM:${daylightOffset}`, `TZOFFSETTO:${standardOffset}`, `TZNAME:${tzid}`, 'END:STANDARD', 'BEGIN:DAYLIGHT', 'DTSTART:19700301T000000', `TZOFFSETFROM:${standardOffset}`, `TZOFFSETTO:${daylightOffset}`, `TZNAME:${tzid}`, 'END:DAYLIGHT');
+    }
+    lines.push('END:VTIMEZONE');
+    return lines.join('\r\n');
+}
+/**
+ * Convert a UTC iCal datetime ("YYYYMMDDTHHmmssZ") to wall-clock time in the
+ * given IANA zone, returning "YYYYMMDDTHHmmss" (no Z).
+ */
+function convertUtcICalToLocalICal(utcICal, tzid) {
+    const m = utcICal.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/);
+    if (!m)
+        return utcICal.replace(/Z$/, '');
+    const [, y, mo, d, h, mi, s] = m;
+    const instant = new Date(Date.UTC(+y, +mo - 1, +d, +h, +mi, +s));
+    const fmt = new Intl.DateTimeFormat('en-CA', {
+        timeZone: tzid,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    });
+    const parts = fmt.formatToParts(instant);
+    const get = (t) => parts.find((p) => p.type === t)?.value ?? '00';
+    let hour = get('hour');
+    if (hour === '24')
+        hour = '00';
+    return `${get('year')}${get('month')}${get('day')}T${hour}${get('minute')}${get('second')}`;
+}
+/**
+ * If `value` ends in Z, convert it to wall-clock time in `tzid`. Otherwise
+ * assume it is already a floating local datetime in that zone.
+ */
+function normalizeLocalICal(value, tzid) {
+    if (/Z$/.test(value))
+        return convertUtcICalToLocalICal(value, tzid);
+    return value;
+}
+/**
+ * Add `hours` to a floating "YYYYMMDDTHHmmss" string, returning the same form.
+ */
+function addHoursToLocalICal(local, hours) {
+    const m = local.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})$/);
+    if (!m)
+        return local;
+    const [, y, mo, d, h, mi, s] = m;
+    const dt = new Date(Date.UTC(+y, +mo - 1, +d, +h + hours, +mi, +s));
+    const pad = (n) => String(n).padStart(2, '0');
+    return (`${dt.getUTCFullYear()}${pad(dt.getUTCMonth() + 1)}${pad(dt.getUTCDate())}` +
+        `T${pad(dt.getUTCHours())}${pad(dt.getUTCMinutes())}${pad(dt.getUTCSeconds())}`);
+}
+/**
+ * Ensure the VCALENDAR contains a VTIMEZONE with the requested TZID. Insert
+ * one before the first VEVENT if not already present.
+ */
+function ensureVTimezone(icalData, tzid) {
+    const escaped = tzid.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const existing = new RegExp(`BEGIN:VTIMEZONE[\\s\\S]*?TZID:${escaped}[\\s\\S]*?END:VTIMEZONE`);
+    if (existing.test(icalData))
+        return icalData;
+    const vtz = buildVTimezone(tzid);
+    return icalData.replace(/BEGIN:VEVENT/, `${vtz}\r\nBEGIN:VEVENT`);
+}
 // ---------------------------------------------------------------------------
 // Parsing
 // ---------------------------------------------------------------------------
@@ -703,6 +815,10 @@ export const createEventTool = {
             .number()
             .optional()
             .describe('Reminder in minutes before the event (e.g. 15 for 15 min before)'),
+        tzid: z
+            .string()
+            .optional()
+            .describe('IANA time zone (e.g. "Europe/Berlin"). When set, a VTIMEZONE block is emitted and dtstart/dtend use TZID instead of UTC. Required for reliable iOS Calendar and Thunderbird CalDAV sync of timed events. UTC inputs (trailing Z) are converted to wall-clock time in this zone.'),
     }),
     handler: async (args) => {
         try {
@@ -714,6 +830,8 @@ export const createEventTool = {
             await assertCalendarSupportsEvents(calendarBaseUrl, args.calendarName);
             const now = icalNow();
             const isAllDay = args.dtstart.length === 8;
+            const tzid = !isAllDay ? args.tzid : undefined;
+            const localDtstart = tzid ? normalizeLocalICal(args.dtstart, tzid) : args.dtstart;
             // Calculate default end
             let dtend = args.dtend;
             if (!dtend) {
@@ -722,18 +840,34 @@ export const createEventTool = {
                     const d = new Date(parseInt(args.dtstart.slice(0, 4)), parseInt(args.dtstart.slice(4, 6)) - 1, parseInt(args.dtstart.slice(6, 8)) + 1);
                     dtend = `${d.getFullYear()}${String(d.getMonth() + 1).padStart(2, '0')}${String(d.getDate()).padStart(2, '0')}`;
                 }
+                else if (tzid) {
+                    // Timed with TZID: 1 hour after local wall time
+                    dtend = addHoursToLocalICal(localDtstart, 1);
+                }
                 else {
-                    // Timed: 1 hour later
+                    // Timed: 1 hour later (UTC)
                     const startDate = new Date(parseInt(args.dtstart.slice(0, 4)), parseInt(args.dtstart.slice(4, 6)) - 1, parseInt(args.dtstart.slice(6, 8)), parseInt(args.dtstart.slice(9, 11)), parseInt(args.dtstart.slice(11, 13)), parseInt(args.dtstart.slice(13, 15)));
                     startDate.setHours(startDate.getHours() + 1);
                     dtend = startDate.toISOString().replace(/[-:]/g, '').split('.')[0] + 'Z';
                 }
             }
-            const dtstartProp = isAllDay
-                ? `DTSTART;VALUE=DATE:${args.dtstart}`
-                : `DTSTART:${args.dtstart}`;
-            const dtendProp = isAllDay ? `DTEND;VALUE=DATE:${dtend}` : `DTEND:${dtend}`;
-            let vevent = `BEGIN:VCALENDAR\r\nVERSION:2.0\r\nPRODID:-//AIquila//MCP Server//EN\r\nBEGIN:VEVENT\r\nUID:${eventUid}\r\nDTSTAMP:${now}\r\nCREATED:${now}\r\nLAST-MODIFIED:${now}\r\n${dtstartProp}\r\n${dtendProp}\r\nSUMMARY:${escapeICalValue(args.summary)}`;
+            const localDtend = tzid ? normalizeLocalICal(dtend, tzid) : dtend;
+            let dtstartProp;
+            let dtendProp;
+            if (isAllDay) {
+                dtstartProp = `DTSTART;VALUE=DATE:${args.dtstart}`;
+                dtendProp = `DTEND;VALUE=DATE:${dtend}`;
+            }
+            else if (tzid) {
+                dtstartProp = `DTSTART;TZID=${tzid}:${localDtstart}`;
+                dtendProp = `DTEND;TZID=${tzid}:${localDtend}`;
+            }
+            else {
+                dtstartProp = `DTSTART:${args.dtstart}`;
+                dtendProp = `DTEND:${dtend}`;
+            }
+            const vtimezoneBlock = tzid ? `${buildVTimezone(tzid)}\r\n` : '';
+            let vevent = `BEGIN:VCALENDAR\r\nVERSION:2.0\r\nPRODID:-//AIquila//MCP Server//EN\r\n${vtimezoneBlock}BEGIN:VEVENT\r\nUID:${eventUid}\r\nDTSTAMP:${now}\r\nCREATED:${now}\r\nLAST-MODIFIED:${now}\r\n${dtstartProp}\r\n${dtendProp}\r\nSUMMARY:${escapeICalValue(args.summary)}`;
             if (args.location) {
                 vevent += `\r\nLOCATION:${escapeICalValue(args.location)}`;
             }
@@ -870,6 +1004,10 @@ export const updateEventTool = {
             .nullable()
             .optional()
             .describe('Replace attendees list, or null to remove all attendees'),
+        tzid: z
+            .string()
+            .optional()
+            .describe('IANA time zone (e.g. "Europe/Berlin") for the updated dtstart/dtend. When set, a VTIMEZONE block is added (if missing) and DTSTART/DTEND use TZID instead of UTC. Required for iOS/Thunderbird CalDAV sync.'),
     }),
     handler: async (args) => {
         try {
@@ -879,11 +1017,17 @@ export const updateEventTool = {
             if (args.summary !== undefined) {
                 modified = setICalProperty(modified, 'SUMMARY', escapeICalValue(args.summary));
             }
+            // Only timed datetimes carry a TZID; all-day (length 8) values are dates.
+            const dtstartTz = args.tzid && args.dtstart && args.dtstart.length > 8 ? args.tzid : undefined;
+            const dtendTz = args.tzid && args.dtend && args.dtend.length > 8 ? args.tzid : undefined;
             if (args.dtstart !== undefined) {
-                modified = setICalDateProperty(modified, 'DTSTART', args.dtstart);
+                modified = setICalDateProperty(modified, 'DTSTART', args.dtstart, dtstartTz);
             }
             if (args.dtend !== undefined) {
-                modified = setICalDateProperty(modified, 'DTEND', args.dtend);
+                modified = setICalDateProperty(modified, 'DTEND', args.dtend, dtendTz);
+            }
+            if (args.tzid && (dtstartTz || dtendTz)) {
+                modified = ensureVTimezone(modified, args.tzid);
             }
             if (args.location !== undefined) {
                 modified = setICalProperty(modified, 'LOCATION', args.location ? escapeICalValue(args.location) : null);

package/dist/tools/apps/text.js

@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: MIT
+import { z } from 'zod';
+import { fetchTextAPI, } from '../../client/text.js';
+import { ApiError } from '../../client/aiquila.js';
+import { getWebDAVClient } from '../../client/webdav.js';
+import { handleAppError } from '../error-utils.js';
+/**
+ * Nextcloud Text App Tools — workspaces (per-folder Readme.md) and direct-edit URLs.
+ *
+ * Uses the Text OCS API (/ocs/v2.php/apps/text/workspace) plus WebDAV for content I/O.
+ * Collaborative editing sessions are intentionally out of scope: the live editor runs
+ * in the user's browser via the direct-edit URL.
+ */
+const textStatusMap = {
+    400: 'Bad request — check the folder path.',
+    403: 'Access denied to this folder.',
+    404: 'No workspace exists for this folder.',
+};
+const FolderPathArg = z
+    .string()
+    .describe("Folder path relative to the user's root (e.g. '/Projects/Acme')");
+function normaliseFolder(path) {
+    if (!path || path === '/')
+        return '/';
+    return path.replace(/\/+$/, '');
+}
+function joinPath(folder, name) {
+    const f = normaliseFolder(folder);
+    return f === '/' ? `/${name}` : `${f}/${name}`;
+}
+function formatWorkspace(file) {
+    return `[${file.id}] ${file.name} (${file.mimetype}) at ${file.path}`;
+}
+async function resolveWorkspaceFile(folder) {
+    try {
+        const data = await fetchTextAPI('/workspace', {
+            queryParams: { path: folder },
+        });
+        return data?.file ?? null;
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.statusCode === 404) {
+            return null;
+        }
+        throw error;
+    }
+}
+export const getTextWorkspaceTool = {
+    name: 'get_text_workspace',
+    description: "Get metadata of the Text workspace file (Readme.md) for a folder. Returns the file's id, name, mimetype and path, or reports that no workspace exists yet.",
+    inputSchema: z.object({ path: FolderPathArg }),
+    handler: async (args) => {
+        try {
+            const file = await resolveWorkspaceFile(args.path);
+            if (!file) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No workspace file in ${normaliseFolder(args.path) || '/'}.`,
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [{ type: 'text', text: `Workspace: ${formatWorkspace(file)}` }],
+            };
+        }
+        catch (error) {
+            return handleAppError(error, 'Error getting workspace', textStatusMap);
+        }
+    },
+};
+export const readTextWorkspaceTool = {
+    name: 'read_text_workspace',
+    description: "Read the content of a folder's Text workspace file (Readme.md). Returns markdown text, or a 'no workspace' message if none exists.",
+    inputSchema: z.object({ path: FolderPathArg }),
+    handler: async (args) => {
+        try {
+            const file = await resolveWorkspaceFile(args.path);
+            if (!file) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No workspace file in ${normaliseFolder(args.path) || '/'}.`,
+                        },
+                    ],
+                };
+            }
+            const client = getWebDAVClient();
+            const content = (await client.getFileContents(file.path, { format: 'text' }));
+            return { content: [{ type: 'text', text: content }] };
+        }
+        catch (error) {
+            return handleAppError(error, 'Error reading workspace', textStatusMap);
+        }
+    },
+};
+export const writeTextWorkspaceTool = {
+    name: 'write_text_workspace',
+    description: "Create or overwrite a folder's Text workspace file. If a workspace already exists, its existing filename is reused; otherwise Readme.md is created at the folder root.",
+    inputSchema: z.object({
+        path: FolderPathArg,
+        content: z.string().describe('Markdown content to write'),
+    }),
+    handler: async (args) => {
+        try {
+            const existing = await resolveWorkspaceFile(args.path);
+            const targetPath = existing?.path ?? joinPath(args.path, 'Readme.md');
+            const client = getWebDAVClient();
+            await client.putFileContents(targetPath, args.content, { overwrite: true });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: existing
+                            ? `Workspace updated at ${targetPath}.`
+                            : `Workspace created at ${targetPath}.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return handleAppError(error, 'Error writing workspace', textStatusMap);
+        }
+    },
+};
+export const deleteTextWorkspaceTool = {
+    name: 'delete_text_workspace',
+    description: 'Delete the Text workspace file (Readme.md) for a folder. The folder itself is kept. No-op if the folder has no workspace.',
+    inputSchema: z.object({ path: FolderPathArg }),
+    handler: async (args) => {
+        try {
+            const existing = await resolveWorkspaceFile(args.path);
+            if (!existing) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No workspace file in ${normaliseFolder(args.path) || '/'}.`,
+                        },
+                    ],
+                };
+            }
+            const client = getWebDAVClient();
+            await client.deleteFile(existing.path);
+            return {
+                content: [{ type: 'text', text: `Workspace deleted at ${existing.path}.` }],
+            };
+        }
+        catch (error) {
+            return handleAppError(error, 'Error deleting workspace', textStatusMap);
+        }
+    },
+};
+export const getTextWorkspaceEditUrlTool = {
+    name: 'get_text_workspace_edit_url',
+    description: "Get a one-shot direct-edit URL for a folder's Text workspace. Opens the live collaborative editor in a browser. The Readme.md is created automatically if it does not exist yet. Hand the URL to a human collaborator — the MCP server does not participate in the editing session.",
+    inputSchema: z.object({ path: FolderPathArg }),
+    handler: async (args) => {
+        try {
+            const data = await fetchTextAPI('/workspace/direct', {
+                method: 'POST',
+                body: { path: args.path },
+            });
+            return { content: [{ type: 'text', text: data.url }] };
+        }
+        catch (error) {
+            return handleAppError(error, 'Error getting workspace edit URL', textStatusMap);
+        }
+    },
+};
+export const textTools = [
+    getTextWorkspaceTool,
+    readTextWorkspaceTool,
+    writeTextWorkspaceTool,
+    deleteTextWorkspaceTool,
+    getTextWorkspaceEditUrlTool,
+];

package/package.json

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