aiquila-mcp 0.3.29 → 0.3.31

package/dist/auth/provider.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 import { createHash, timingSafeEqual } from 'node:crypto';
 import { SignJWT, jwtVerify } from 'jose';
-import { InvalidGrantError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import { InvalidGrantError, InvalidTokenError, } from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import { ClientsStore, CodeStore, RefreshStore } from './store.js';
 import { logger } from '../logger.js';
 // --- JWT helpers (HMAC-SHA256 via jose) ---
@@ -196,7 +196,10 @@ export class NextcloudOAuthProvider {
         const claims = await verifyJwt(token, this.getSecret(), issuer ? { issuer, audience: new URL('/mcp', issuer).toString() } : undefined);
         if (!claims) {
             logger.warn('[auth] Access token verification failed: invalid or expired token');
-            throw new Error('Invalid or expired access token');
+            // InvalidTokenError (not a bare Error) so the SDK answers 401 with a
+            // WWW-Authenticate challenge. A bare Error becomes a 500, and clients
+            // treat that as a server fault rather than a cue to re-authenticate.
+            throw new InvalidTokenError('Invalid or expired access token');
         }
         return {
             token,

package/dist/client/caldav.js

@@ -12,12 +12,20 @@ export function nsTagContent(localName) {
  * Needed because we parse XML responses with regex instead of a DOM parser.
  */
 export function decodeXmlEntities(text) {
-    return text
+    return (text
+        // Numeric character references. SabreDAV serializes calendar-data and
+        // address-data through libxml, which escapes carriage returns as `
`
+        // so they survive XML whitespace normalization. Leaving those undecoded
+        // corrupts every line ending of the iCalendar/vCard payload (GH #396).
+        .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+        .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(parseInt(dec, 10)))
         .replace(/"/g, '"')
         .replace(/'/g, "'")
         .replace(/&lt;/g, '<')
         .replace(/&gt;/g, '>')
-        .replace(/&amp;/g, '&');
+        // `&amp;` last, so an encoded `&amp;#13;` decodes to the literal text
+        // `&#13;` rather than being decoded twice into a carriage return.
+        .replace(/&amp;/g, '&'));
 }
 /**
  * Fetch data from CalDAV endpoint using basic authentication

package/dist/tools/apps/contacts.js

@@ -1,44 +1,38 @@
 // SPDX-License-Identifier: MIT
 import { z } from 'zod';
 import { decodeXmlEntities, fetchCalDAV, nsTagContent } from '../../client/caldav.js';
-import { escapeVCardValue, unescapeVCardValue } from '../dav-utils.js';
+import { escapeVCardValue, sanitizeVCardUriValue, unescapeVCardValue } from '../dav-utils.js';
+import { getParamValues, getProperty, parseVCard, property, replaceAll, serializeVCard, setProperty, } from '../vcard.js';
 import { getNextcloudConfig } from '../types.js';
 // ---------------------------------------------------------------------------
 // vCard helpers
 // ---------------------------------------------------------------------------
-function unfoldVCardLines(text) {
-    return text.replace(/\r?\n[ \t]/g, '');
-}
 /**
- * Extract TYPE parameter from a vCard property line.
- * Handles TYPE=WORK, TYPE="WORK", type=work, etc.
+ * Extract the TYPE parameter of a property, e.g. `WORK` from `TEL;TYPE=WORK:`.
+ * vCard 4.0 may repeat the parameter (`TYPE=voice;TYPE=cell`) or quote a list
+ * (`TYPE="voice,cell"`); both collapse to a single comma-joined string.
  */
-function extractType(params) {
-    const match = params.match(/TYPE="?([^";:]+)"?/i);
-    return match ? match[1].toUpperCase() : undefined;
+function extractType(prop) {
+    const values = getParamValues(prop, 'TYPE');
+    return values.length > 0 ? values.join(',').toUpperCase() : undefined;
 }
-/**
- * Replace, add, or remove a simple vCard property.
- * - value === null  -> remove the property
- * - property exists -> replace its value
- * - property absent -> insert before END:VCARD
- */
-function setVCardProperty(vcardData, propName, value) {
-    const regex = new RegExp(`^${propName}(;[^:]*)?:.*$`, 'mi');
-    if (value === null) {
-        return vcardData.replace(regex, '').replace(/(\r?\n){2,}/g, '\r\n');
-    }
-    if (regex.test(vcardData)) {
-        return vcardData.replace(regex, `${propName}:${value}`);
-    }
-    return vcardData.replace(/END:VCARD/i, `${propName}:${value}\r\nEND:VCARD`);
+/** Build a property with an optional TYPE parameter. */
+function typedProperty(name, value, type) {
+    return property(name, value, type ? [['TYPE', type]] : []);
 }
-/**
- * Remove all instances of a multi-valued property (e.g. EMAIL, TEL, ADR).
- */
-function removeAllVCardProperty(vcardData, propName) {
-    const regex = new RegExp(`^${propName}(;[^:]*)?:.*\\r?\\n?`, 'gmi');
-    return vcardData.replace(regex, '');
+/** Serialize an ADR value from its structured parts, escaping each component. */
+function buildAdrValue(addr) {
+    const part = (v) => (v ? escapeVCardValue(v) : '');
+    // ADR:po-box;extended;street;locality;region;postal-code;country
+    return [
+        '',
+        '',
+        part(addr.street),
+        part(addr.city),
+        part(addr.region),
+        part(addr.postalCode),
+        part(addr.country),
+    ].join(';');
 }
 // ---------------------------------------------------------------------------
 // Parsing
@@ -72,8 +66,7 @@ function parseAddressBooks(responseXml) {
  * Parse a single vCard text block into a ParsedContact.
  */
 function parseVCardBlock(vcardText) {
-    const unfolded = unfoldVCardLines(vcardText);
-    const lines = unfolded.split(/\r?\n/);
+    const doc = parseVCard(vcardText);
     const contact = {
         uid: '',
         fullName: '',
@@ -82,14 +75,8 @@ function parseVCardBlock(vcardText) {
         addresses: [],
         categories: [],
     };
-    for (const line of lines) {
-        const propMatch = line.match(/^([A-Za-z0-9-]+)(;[^:]*)?:(.*)/);
-        if (!propMatch)
-            continue;
-        const [, rawName, params, rawValue] = propMatch;
-        const name = rawName.toUpperCase();
-        const value = rawValue || '';
-        const paramStr = params || '';
+    for (const prop of doc.properties) {
+        const { name, value } = prop;
         switch (name) {
             case 'UID':
                 contact.uid = value;
@@ -111,13 +98,13 @@ function parseVCardBlock(vcardText) {
             case 'EMAIL':
                 contact.emails.push({
                     value: unescapeVCardValue(value),
-                    type: extractType(paramStr),
+                    type: extractType(prop),
                 });
                 break;
             case 'TEL':
                 contact.phones.push({
                     value: unescapeVCardValue(value),
-                    type: extractType(paramStr),
+                    type: extractType(prop),
                 });
                 break;
             case 'ADR': {
@@ -129,7 +116,7 @@ function parseVCardBlock(vcardText) {
                     region: unescapeVCardValue(adrParts[4] || ''),
                     postalCode: unescapeVCardValue(adrParts[5] || ''),
                     country: unescapeVCardValue(adrParts[6] || ''),
-                    type: extractType(paramStr),
+                    type: extractType(prop),
                 });
                 break;
             }
@@ -178,7 +165,7 @@ function parseVCards(responseXml) {
         const cardDataMatch = block.match(/<(?:[a-z0-9]+:)?address-data[^>]*>([\s\S]*?)<\/(?:[a-z0-9]+:)?address-data>/);
         if (!cardDataMatch)
             continue;
-        const vcardText = cardDataMatch[1];
+        const vcardText = decodeXmlEntities(cardDataMatch[1]);
         const vcardBlocks = vcardText.match(/BEGIN:VCARD[\s\S]*?END:VCARD/gi);
         if (!vcardBlocks)
             continue;
@@ -310,7 +297,7 @@ async function resolveContactByUid(addressBookName, uid) {
     return {
         href: hrefMatch[1],
         etag,
-        vcardData: decodeXmlEntities(cardDataMatch[1]),
+        vcardData: decodeXmlEntities(cardDataMatch[1]).trim(),
     };
 }
 // ---------------------------------------------------------------------------
@@ -503,7 +490,7 @@ export const getContactTool = {
     handler: async (args) => {
         try {
             const { vcardData } = await resolveContactByUid(args.addressBookName, args.uid);
-            const contact = parseVCardBlock(unfoldVCardLines(vcardData));
+            const contact = parseVCardBlock(vcardData);
             if (!contact) {
                 throw new Error(`Contact with UID "${args.uid}" could not be parsed`);
             }
@@ -598,49 +585,42 @@ export const createContactTool = {
             const given = args.firstName ? escapeVCardValue(args.firstName) : '';
             const prefix = args.prefix ? escapeVCardValue(args.prefix) : '';
             const suffix = args.suffix ? escapeVCardValue(args.suffix) : '';
-            let vcard = `BEGIN:VCARD\r\nVERSION:3.0\r\nPRODID:-//AIquila//MCP Server//EN\r\nUID:${contactUid}\r\nREV:${now}\r\nFN:${escapeVCardValue(args.fullName)}\r\nN:${family};${given};;${prefix};${suffix}`;
-            if (args.emails) {
-                for (const email of args.emails) {
-                    const typeParam = email.type ? `;TYPE=${email.type}` : '';
-                    vcard += `\r\nEMAIL${typeParam}:${email.value}`;
-                }
-            }
-            if (args.phones) {
-                for (const phone of args.phones) {
-                    const typeParam = phone.type ? `;TYPE=${phone.type}` : '';
-                    vcard += `\r\nTEL${typeParam}:${phone.value}`;
-                }
-            }
-            if (args.addresses) {
-                for (const addr of args.addresses) {
-                    const typeParam = addr.type ? `;TYPE=${addr.type}` : '';
-                    const street = addr.street ? escapeVCardValue(addr.street) : '';
-                    const city = addr.city ? escapeVCardValue(addr.city) : '';
-                    const region = addr.region ? escapeVCardValue(addr.region) : '';
-                    const postalCode = addr.postalCode ? escapeVCardValue(addr.postalCode) : '';
-                    const country = addr.country ? escapeVCardValue(addr.country) : '';
-                    vcard += `\r\nADR${typeParam}:;;${street};${city};${region};${postalCode};${country}`;
-                }
+            const properties = [
+                property('VERSION', '3.0'),
+                property('PRODID', '-//AIquila//MCP Server//EN'),
+                property('UID', contactUid),
+                property('REV', now),
+                property('FN', escapeVCardValue(args.fullName)),
+                property('N', `${family};${given};;${prefix};${suffix}`),
+            ];
+            for (const email of args.emails ?? []) {
+                properties.push(typedProperty('EMAIL', sanitizeVCardUriValue(email.value), email.type));
+            }
+            for (const phone of args.phones ?? []) {
+                properties.push(typedProperty('TEL', sanitizeVCardUriValue(phone.value), phone.type));
+            }
+            for (const addr of args.addresses ?? []) {
+                properties.push(typedProperty('ADR', buildAdrValue(addr), addr.type));
             }
             if (args.org) {
-                vcard += `\r\nORG:${escapeVCardValue(args.org)}`;
+                properties.push(property('ORG', escapeVCardValue(args.org)));
             }
             if (args.title) {
-                vcard += `\r\nTITLE:${escapeVCardValue(args.title)}`;
+                properties.push(property('TITLE', escapeVCardValue(args.title)));
             }
             if (args.note) {
-                vcard += `\r\nNOTE:${escapeVCardValue(args.note)}`;
+                properties.push(property('NOTE', escapeVCardValue(args.note)));
             }
             if (args.birthday) {
-                vcard += `\r\nBDAY:${args.birthday}`;
+                properties.push(property('BDAY', sanitizeVCardUriValue(args.birthday)));
             }
             if (args.url) {
-                vcard += `\r\nURL:${args.url}`;
+                properties.push(property('URL', sanitizeVCardUriValue(args.url)));
             }
             if (args.categories && args.categories.length > 0) {
-                vcard += `\r\nCATEGORIES:${args.categories.map(escapeVCardValue).join(',')}`;
+                properties.push(property('CATEGORIES', args.categories.map(escapeVCardValue).join(',')));
             }
-            vcard += `\r\nEND:VCARD`;
+            const vcard = serializeVCard({ properties });
             const response = await fetchCalDAV(cardDavUrl, {
                 method: 'PUT',
                 body: vcard,
@@ -741,80 +721,58 @@ export const updateContactTool = {
         try {
             const config = getNextcloudConfig();
             const { href, etag, vcardData } = await resolveContactByUid(args.addressBookName, args.uid);
-            let modified = unfoldVCardLines(vcardData);
+            const doc = parseVCard(vcardData);
             // Update FN
             if (args.fullName !== undefined) {
-                modified = setVCardProperty(modified, 'FN', escapeVCardValue(args.fullName));
+                setProperty(doc, 'FN', escapeVCardValue(args.fullName));
             }
-            // Update N (structured name)
+            // Update N (structured name), preserving the components we do not touch
             if (args.firstName !== undefined || args.lastName !== undefined) {
-                // Parse existing N property
-                const nMatch = modified.match(/^N(;[^:]*)?:(.*)/im);
-                const existingParts = nMatch ? nMatch[2].split(';') : ['', '', '', '', ''];
+                const existing = getProperty(doc, 'N');
+                const parts = existing ? existing.value.split(';') : ['', '', '', '', ''];
                 if (args.lastName !== undefined) {
-                    existingParts[0] = args.lastName ? escapeVCardValue(args.lastName) : '';
+                    parts[0] = args.lastName ? escapeVCardValue(args.lastName) : '';
                 }
                 if (args.firstName !== undefined) {
-                    existingParts[1] = args.firstName ? escapeVCardValue(args.firstName) : '';
+                    parts[1] = args.firstName ? escapeVCardValue(args.firstName) : '';
                 }
-                modified = setVCardProperty(modified, 'N', existingParts.slice(0, 5).join(';'));
+                setProperty(doc, 'N', parts.slice(0, 5).join(';'));
             }
             // Update simple properties
             if (args.org !== undefined) {
-                modified = setVCardProperty(modified, 'ORG', args.org ? escapeVCardValue(args.org) : null);
+                setProperty(doc, 'ORG', args.org ? escapeVCardValue(args.org) : null);
             }
             if (args.title !== undefined) {
-                modified = setVCardProperty(modified, 'TITLE', args.title ? escapeVCardValue(args.title) : null);
+                setProperty(doc, 'TITLE', args.title ? escapeVCardValue(args.title) : null);
             }
             if (args.note !== undefined) {
-                modified = setVCardProperty(modified, 'NOTE', args.note ? escapeVCardValue(args.note) : null);
+                setProperty(doc, 'NOTE', args.note ? escapeVCardValue(args.note) : null);
             }
             if (args.birthday !== undefined) {
-                modified = setVCardProperty(modified, 'BDAY', args.birthday);
+                setProperty(doc, 'BDAY', args.birthday ? sanitizeVCardUriValue(args.birthday) : null);
             }
             if (args.url !== undefined) {
-                modified = setVCardProperty(modified, 'URL', args.url);
+                setProperty(doc, 'URL', args.url ? sanitizeVCardUriValue(args.url) : null);
             }
             // Update multi-valued properties (replace all)
             if (args.emails !== undefined) {
-                modified = removeAllVCardProperty(modified, 'EMAIL');
-                for (const email of args.emails) {
-                    const typeParam = email.type ? `;TYPE=${email.type}` : '';
-                    const line = `EMAIL${typeParam}:${email.value}`;
-                    modified = modified.replace(/END:VCARD/i, `${line}\r\nEND:VCARD`);
-                }
+                replaceAll(doc, 'EMAIL', args.emails.map((e) => typedProperty('EMAIL', sanitizeVCardUriValue(e.value), e.type)));
             }
             if (args.phones !== undefined) {
-                modified = removeAllVCardProperty(modified, 'TEL');
-                for (const phone of args.phones) {
-                    const typeParam = phone.type ? `;TYPE=${phone.type}` : '';
-                    const line = `TEL${typeParam}:${phone.value}`;
-                    modified = modified.replace(/END:VCARD/i, `${line}\r\nEND:VCARD`);
-                }
+                replaceAll(doc, 'TEL', args.phones.map((p) => typedProperty('TEL', sanitizeVCardUriValue(p.value), p.type)));
             }
             if (args.addresses !== undefined) {
-                modified = removeAllVCardProperty(modified, 'ADR');
-                for (const addr of args.addresses) {
-                    const typeParam = addr.type ? `;TYPE=${addr.type}` : '';
-                    const street = addr.street ? escapeVCardValue(addr.street) : '';
-                    const city = addr.city ? escapeVCardValue(addr.city) : '';
-                    const region = addr.region ? escapeVCardValue(addr.region) : '';
-                    const postalCode = addr.postalCode ? escapeVCardValue(addr.postalCode) : '';
-                    const country = addr.country ? escapeVCardValue(addr.country) : '';
-                    const line = `ADR${typeParam}:;;${street};${city};${region};${postalCode};${country}`;
-                    modified = modified.replace(/END:VCARD/i, `${line}\r\nEND:VCARD`);
-                }
+                replaceAll(doc, 'ADR', args.addresses.map((a) => typedProperty('ADR', buildAdrValue(a), a.type)));
             }
             if (args.categories !== undefined) {
-                modified = removeAllVCardProperty(modified, 'CATEGORIES');
-                if (args.categories.length > 0) {
-                    const line = `CATEGORIES:${args.categories.map(escapeVCardValue).join(',')}`;
-                    modified = modified.replace(/END:VCARD/i, `${line}\r\nEND:VCARD`);
-                }
+                replaceAll(doc, 'CATEGORIES', args.categories.length > 0
+                    ? [property('CATEGORIES', args.categories.map(escapeVCardValue).join(','))]
+                    : []);
             }
             // Update REV timestamp
             const now = new Date().toISOString().replace(/[-:]/g, '').split('.')[0] + 'Z';
-            modified = setVCardProperty(modified, 'REV', now);
+            setProperty(doc, 'REV', now);
+            const modified = serializeVCard(doc);
             const putUrl = `${config.url}${href}`;
             const putResponse = await fetchCalDAV(putUrl, {
                 method: 'PUT',

package/dist/tools/dav-utils.js

@@ -7,24 +7,46 @@
  * case-insensitive for that sequence.
  */
 export function escapeDavValue(value) {
-    return value
+    return (value
         .replace(/\\/g, '\\\\')
         .replace(/;/g, '\\;')
         .replace(/,/g, '\\,')
-        .replace(/\n/g, '\\n');
+        // A raw CR would terminate the content line and make the payload
+        // unparseable, so CRLF and lone CR both collapse to an escaped newline.
+        .replace(/\r\n|\r|\n/g, '\\n'));
+}
+/**
+ * Sanitize a value for a URI- or date-valued property (URL, TEL, EMAIL, BDAY).
+ *
+ * Text escaping must NOT be applied to these: `;` and `,` carry no special
+ * meaning in their values, and escaping them leaves a literal backslash in the
+ * URI once a strict parser reads it back. All that is actually required is that
+ * the value cannot terminate the content line.
+ */
+export function sanitizeDavUriValue(value) {
+    // eslint-disable-next-line no-control-regex
+    return value.replace(/[\x00-\x1f\x7f]/g, '');
 }
 export function unescapeDavValue(value, options) {
-    return value
-        .replace(options?.caseInsensitiveNewline ? /\\n/gi : /\\n/g, '\n')
-        .replace(/\\,/g, ',')
-        .replace(/\\;/g, ';')
-        .replace(/\\\\/g, '\\');
+    // Single pass: a chained replace would rewrite the `\n` inside an escaped
+    // backslash sequence (`\\n` — a literal backslash followed by `n`) into a
+    // newline before the backslash itself was unescaped.
+    const newlinePattern = options?.caseInsensitiveNewline ? /n/i : /n/;
+    return value.replace(/\\(.)/g, (match, char) => {
+        if (newlinePattern.test(char))
+            return '\n';
+        if (char === ',' || char === ';' || char === '\\')
+            return char;
+        return match;
+    });
 }
 /** Escape for iCalendar (VEVENT, VTODO) properties. */
 export const escapeICalValue = escapeDavValue;
 /** Unescape iCalendar property values (case-sensitive \\n). */
 export const unescapeICalValue = (value) => unescapeDavValue(value);
-/** Escape for vCard properties. */
+/** Escape for vCard text properties (FN, N, ADR, ORG, NOTE, CATEGORIES, ...). */
 export const escapeVCardValue = escapeDavValue;
+/** Sanitize vCard URI/date properties (URL, TEL, EMAIL, BDAY) — no escaping. */
+export const sanitizeVCardUriValue = sanitizeDavUriValue;
 /** Unescape vCard property values (case-insensitive \\n per RFC 6350). */
 export const unescapeVCardValue = (value) => unescapeDavValue(value, { caseInsensitiveNewline: true });

package/dist/tools/vcard.js

@@ -0,0 +1,242 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Minimal vCard (RFC 6350 / RFC 2426) parser and serializer.
+ *
+ * Replaces the regex string-surgery that used to mutate vCard text in place.
+ * That approach produced bodies SabreDAV rejected with `415 Unsupported Media
+ * Type` (GH #396): it mixed line endings, never re-folded long lines, dropped
+ * property parameters, and could not see grouped properties (`item1.TEL`).
+ *
+ * The model is deliberately flat: a vCard is an ordered list of properties,
+ * including the `BEGIN`, `VERSION` and `END` lines. That keeps round-tripping a
+ * card we did not author byte-stable apart from re-folding, which matters
+ * because we PUT back whatever the server gave us.
+ */
+/** Maximum octets per line before folding (RFC 6350 §3.2). */
+const MAX_LINE_OCTETS = 75;
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+/**
+ * Split a content line at the first colon that is not inside a quoted
+ * parameter value. `TEL;TYPE="voice:work";VALUE=uri:tel:+41...` must split at
+ * the colon before `tel:`, not at either of the earlier ones.
+ */
+function splitAtValueColon(line) {
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === '"') {
+            inQuotes = !inQuotes;
+        }
+        else if (ch === ':' && !inQuotes) {
+            return [line.slice(0, i), line.slice(i + 1)];
+        }
+    }
+    return null;
+}
+/** Split the part before the value colon on unquoted semicolons. */
+function splitParams(head) {
+    const segments = [];
+    let current = '';
+    let inQuotes = false;
+    for (const ch of head) {
+        if (ch === '"') {
+            inQuotes = !inQuotes;
+            current += ch;
+        }
+        else if (ch === ';' && !inQuotes) {
+            segments.push(current);
+            current = '';
+        }
+        else {
+            current += ch;
+        }
+    }
+    segments.push(current);
+    return segments;
+}
+function parseLine(line) {
+    const split = splitAtValueColon(line);
+    if (!split)
+        return null;
+    const [head, value] = split;
+    const segments = splitParams(head);
+    const nameToken = segments[0];
+    if (!nameToken)
+        return null;
+    let group;
+    let name = nameToken;
+    const dot = nameToken.indexOf('.');
+    if (dot > 0) {
+        group = nameToken.slice(0, dot);
+        name = nameToken.slice(dot + 1);
+    }
+    if (!name)
+        return null;
+    const params = [];
+    for (const segment of segments.slice(1)) {
+        if (!segment)
+            continue;
+        const eq = segment.indexOf('=');
+        if (eq === -1) {
+            params.push([segment, '']);
+        }
+        else {
+            params.push([segment.slice(0, eq), segment.slice(eq + 1)]);
+        }
+    }
+    const upper = name.toUpperCase();
+    return {
+        group,
+        name: upper,
+        ...(name === upper ? {} : { rawName: name }),
+        params,
+        value,
+    };
+}
+/**
+ * Parse vCard text into a document.
+ *
+ * Normalizes all line-ending flavours, unfolds continuation lines, and skips
+ * blank lines. Unparseable lines are dropped rather than throwing: we are
+ * usually handling a card written by some other client and would rather
+ * preserve the rest than fail the whole update.
+ */
+export function parseVCard(text) {
+    const unfolded = text
+        .replace(/\r\n|\r/g, '\n')
+        .replace(/\n[ \t]/g, '')
+        .trim();
+    const properties = [];
+    for (const line of unfolded.split('\n')) {
+        if (!line.trim())
+            continue;
+        const property = parseLine(line);
+        if (property)
+            properties.push(property);
+    }
+    return { properties };
+}
+// ---------------------------------------------------------------------------
+// Serialization
+// ---------------------------------------------------------------------------
+/**
+ * Fold a content line to {@link MAX_LINE_OCTETS} octets, splitting only on
+ * whole code points so multi-byte UTF-8 sequences are never cut in half.
+ * Continuation lines carry a single leading space, which counts toward the
+ * limit.
+ */
+function foldLine(line) {
+    if (Buffer.byteLength(line, 'utf8') <= MAX_LINE_OCTETS)
+        return line;
+    const chunks = [];
+    let current = '';
+    let currentOctets = 0;
+    // First line has the full budget; continuation lines lose one octet to the
+    // leading space.
+    let limit = MAX_LINE_OCTETS;
+    for (const char of line) {
+        const octets = Buffer.byteLength(char, 'utf8');
+        if (currentOctets + octets > limit) {
+            chunks.push(current);
+            current = '';
+            currentOctets = 0;
+            limit = MAX_LINE_OCTETS - 1;
+        }
+        current += char;
+        currentOctets += octets;
+    }
+    chunks.push(current);
+    return chunks.join('\r\n ');
+}
+function serializeProperty(property) {
+    const bare = property.rawName ?? property.name;
+    const name = property.group ? `${property.group}.${bare}` : bare;
+    const params = property.params
+        .map(([key, value]) => (value === '' ? `;${key}` : `;${key}=${value}`))
+        .join('');
+    return foldLine(`${name}${params}:${property.value}`);
+}
+/**
+ * Serialize a document to wire format: CRLF throughout, folded, and with the
+ * structural properties forced into the order SabreDAV's strict MimeDir parser
+ * expects (`BEGIN` first, `VERSION` second, `END` last).
+ */
+export function serializeVCard(doc) {
+    const body = doc.properties.filter((p) => p.name !== 'BEGIN' && p.name !== 'END' && p.name !== 'VERSION');
+    const version = doc.properties.find((p) => p.name === 'VERSION');
+    const ordered = [
+        { name: 'BEGIN', params: [], value: 'VCARD' },
+        version ?? { name: 'VERSION', params: [], value: '3.0' },
+        ...body,
+        { name: 'END', params: [], value: 'VCARD' },
+    ];
+    return ordered.map(serializeProperty).join('\r\n') + '\r\n';
+}
+// ---------------------------------------------------------------------------
+// Mutation helpers
+// ---------------------------------------------------------------------------
+/** Build a property, defaulting the parameter list. */
+export function property(name, value, params = []) {
+    return { name: name.toUpperCase(), params, value };
+}
+/** First property with the given name, in any group. */
+export function getProperty(doc, name) {
+    const upper = name.toUpperCase();
+    return doc.properties.find((p) => p.name === upper);
+}
+/** All values of a parameter across a property's (possibly repeated) entries. */
+export function getParamValues(prop, paramName) {
+    const upper = paramName.toUpperCase();
+    return prop.params
+        .filter(([key]) => key.toUpperCase() === upper)
+        .flatMap(([, value]) => value.replace(/^"|"$/g, '').split(','))
+        .map((v) => v.trim())
+        .filter(Boolean);
+}
+/** Index just before the terminating `END:VCARD`, or the end of the list. */
+function insertionIndex(doc) {
+    const end = doc.properties.findIndex((p) => p.name === 'END');
+    return end === -1 ? doc.properties.length : end;
+}
+/**
+ * Replace the value of a single-valued property, or remove it when `value` is
+ * null. Existing parameters and the group prefix are preserved — replacing
+ * `NOTE;CHARSET=UTF-8:old` must not silently produce `NOTE:new`.
+ */
+export function setProperty(doc, name, value) {
+    const upper = name.toUpperCase();
+    if (value === null) {
+        doc.properties = doc.properties.filter((p) => p.name !== upper);
+        removeOrphanedLabels(doc);
+        return;
+    }
+    const existing = doc.properties.find((p) => p.name === upper);
+    if (existing) {
+        existing.value = value;
+        return;
+    }
+    doc.properties.splice(insertionIndex(doc), 0, property(upper, value));
+}
+/**
+ * Replace every instance of a multi-valued property (EMAIL, TEL, ADR, ...)
+ * with a new set. Grouped instances are removed too, so re-setting phones does
+ * not leave the Contacts app's `item1.TEL` entries behind alongside the new
+ * ones.
+ */
+export function replaceAll(doc, name, replacements) {
+    const upper = name.toUpperCase();
+    doc.properties = doc.properties.filter((p) => p.name !== upper);
+    removeOrphanedLabels(doc);
+    doc.properties.splice(insertionIndex(doc), 0, ...replacements);
+}
+/**
+ * Drop `X-ABLabel` properties whose group no longer has anything to label.
+ * Removing `item1.TEL` without this leaves a dangling `item1.X-ABLabel`, which
+ * the Contacts app renders as an empty labelled field.
+ */
+function removeOrphanedLabels(doc) {
+    const groupsInUse = new Set(doc.properties.filter((p) => p.group && p.name !== 'X-ABLABEL').map((p) => p.group));
+    doc.properties = doc.properties.filter((p) => p.name !== 'X-ABLABEL' || !p.group || groupsInUse.has(p.group));
+}

package/dist/transports/http.js

@@ -9,10 +9,16 @@ import { createServer, SERVER_VERSION } from '../server.js';
 import { NextcloudOAuthProvider } from '../auth/provider.js';
 import { probeStateDir, StateDirNotWritableError, stateUnwritableMessage, markStateUnwritableWarned, } from '../auth/store.js';
 import { loginHandler } from '../auth/login.js';
+import { isPublicRequest } from './lazy-auth.js';
 import { logger } from '../logger.js';
 import { fetchStatus } from '../client/ocs.js';
 const DEFAULT_PORT = 3339;
 const MCP_PATH = '/mcp';
+const SCOPES_SUPPORTED = ['mcp:tools', 'mcp:resources', 'mcp:prompts'];
+// Scope advertised in the WWW-Authenticate challenge. Clients request exactly
+// this on authorisation; omitting it makes them fall back to the full
+// `scopes_supported` union, which produces an over-broad consent prompt.
+const CHALLENGE_SCOPE = 'mcp:tools';
 // TLS error codes that indicate a self-signed or untrusted certificate.
 // Network errors (ECONNREFUSED, ETIMEDOUT) are not included — they mean the
 // proxy is not yet reachable, which is transient and should not log a warning.
@@ -81,6 +87,10 @@ export async function startHttp() {
     const port = parseInt(process.env.MCP_PORT || String(DEFAULT_PORT), 10);
     const host = process.env.MCP_HOST || '0.0.0.0';
     const authEnabled = process.env.MCP_AUTH_ENABLED === 'true';
+    // Lazy authentication is on by default: clients need to inspect a connector
+    // before signing in. Operators who treat /mcp as a fully closed endpoint can
+    // set MCP_LAZY_AUTH=false to require a bearer token on every JSON-RPC method.
+    const lazyAuthEnabled = process.env.MCP_LAZY_AUTH !== 'false';
     if (!authEnabled) {
         if (process.env.MCP_ALLOW_UNAUTHENTICATED !== 'true') {
             throw new Error('HTTP transport requires MCP_AUTH_ENABLED=true. ' +
@@ -220,7 +230,7 @@ export async function startHttp() {
             issuerUrl: new URL(issuerUrl),
             resourceServerUrl: new URL(MCP_PATH, issuerUrl),
             serviceDocumentationUrl: new URL('https://github.com/elgorro/aiquila'),
-            scopesSupported: ['mcp:tools', 'mcp:resources', 'mcp:prompts'],
+            scopesSupported: SCOPES_SUPPORTED,
         }));
         // Fallback: serve protected resource metadata at the root well-known path too,
         // so clients that use the server root URL (without /mcp) can discover the resource.
@@ -229,7 +239,7 @@ export async function startHttp() {
             res.json({
                 resource: new URL(MCP_PATH, issuerUrl).href,
                 authorization_servers: [issuerUrl],
-                scopes_supported: ['mcp:tools', 'mcp:resources', 'mcp:prompts'],
+                scopes_supported: SCOPES_SUPPORTED,
                 resource_documentation: 'https://github.com/elgorro/aiquila',
             });
         });
@@ -265,9 +275,44 @@ export async function startHttp() {
                         logger.warn({ status: res.statusCode, rpcMethod: req.body?.method }, '[mcp] Request rejected');
                     }
                 });
+                // The SDK appends `scope="..."` to the challenge only when
+                // `requiredScopes` is set — but setting that would also *enforce* the
+                // scope, and 403 every token issued before scopes were requested (plus
+                // the internal service token, which carries none). Advertise the scope
+                // without enforcing it by decorating the header on its way out.
+                const setHeader = res.setHeader.bind(res);
+                res.setHeader = (name, value) => {
+                    if (typeof name === 'string' &&
+                        name.toLowerCase() === 'www-authenticate' &&
+                        typeof value === 'string' &&
+                        !value.includes('scope=')) {
+                        value = `${value}, scope="${CHALLENGE_SCOPE}"`;
+                    }
+                    return setHeader(name, value);
+                };
                 next();
             },
-            requireBearerAuth({ verifier: provider }),
+            // Lazy-auth gate: the handshake, capability listings, and public tools are
+            // served anonymously so clients can inspect the connector before sign-in.
+            // Everything else falls through to requireBearerAuth below.
+            // Omitted entirely when MCP_LAZY_AUTH=false, restoring a chain in which
+            // every JSON-RPC method requires a bearer token.
+            ...(lazyAuthEnabled
+                ? [
+                    async (req, res, next) => {
+                        if (!req.headers.authorization && isPublicRequest(req.body)) {
+                            logger.debug({ rpcMethod: req.body?.method }, '[mcp] Public request (unauthenticated)');
+                            await handleMcpRequest(req, res);
+                            return;
+                        }
+                        next();
+                    },
+                ]
+                : []),
+            requireBearerAuth({
+                verifier: provider,
+                resourceMetadataUrl: new URL('/.well-known/oauth-protected-resource/mcp', issuerUrl).href,
+            }),
             async (req, res) => {
                 logger.debug({ method: req.method, rpcMethod: req.body?.method }, '[mcp] Request received');
                 await handleMcpRequest(req, res);
@@ -288,6 +333,9 @@ export async function startHttp() {
         if (authEnabled) {
             const tp = process.env.MCP_TRUST_PROXY;
             logger.info({ issuer: process.env.MCP_AUTH_ISSUER }, 'OAuth 2.0 authentication enabled');
+            logger.info({ lazyAuth: lazyAuthEnabled }, lazyAuthEnabled
+                ? 'Lazy auth enabled — tools/list and public tools are readable without a token (set MCP_LAZY_AUTH=false to require one)'
+                : 'Lazy auth disabled — every JSON-RPC method requires a bearer token');
             logger.info({ trustProxy: tp && tp !== 'false' ? tp : 'disabled' }, 'Trust proxy setting (set MCP_TRUST_PROXY=1 if behind a reverse proxy)');
             if (hasStaticClient) {
                 logger.info({ clientId: process.env.MCP_CLIENT_ID }, 'Static OAuth client configured');

package/dist/transports/lazy-auth.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Lazy authentication (mixed auth) for the Streamable HTTP transport.
+ *
+ * Unauthenticated clients may complete the MCP handshake, enumerate the server's
+ * capabilities, and call the tools listed in PUBLIC_TOOLS.  Anything else is
+ * refused at the HTTP layer with a 401 + WWW-Authenticate challenge, which is
+ * what makes clients render an inline "Connect" card and retry the same call
+ * once the user has authorised.
+ *
+ * The refusal has to be an HTTP status, so the check must run *before* the
+ * JSON-RPC message reaches the MCP SDK: once a tool handler is executing, its
+ * return value is already destined to be wrapped in a 200 response, and a 200
+ * carrying `isError: true` reads as an application-level failure, not an auth
+ * challenge.
+ *
+ * @see https://claude.com/docs/connectors/building/lazy-authentication
+ */
+/**
+ * JSON-RPC methods reachable without a token.  These describe the server rather
+ * than touching the Nextcloud instance behind it, so they leak nothing.
+ */
+const PUBLIC_METHODS = new Set([
+    'initialize',
+    'notifications/initialized',
+    'notifications/cancelled',
+    'ping',
+    'tools/list',
+    'resources/list',
+    'resources/templates/list',
+    'prompts/list',
+]);
+/**
+ * Tools reachable without a token.  Every other AIquila tool proxies to
+ * Nextcloud, so this set is deliberately tiny.
+ */
+const PUBLIC_TOOLS = new Set(['get_local_time']);
+function isPublicMessage(msg) {
+    if (!msg || typeof msg !== 'object')
+        return false;
+    const method = msg.method;
+    if (typeof method !== 'string')
+        return false;
+    if (method === 'tools/call') {
+        const name = msg.params?.name;
+        return typeof name === 'string' && PUBLIC_TOOLS.has(name);
+    }
+    return PUBLIC_METHODS.has(method);
+}
+/**
+ * True when every message in the request body is safe to serve anonymously.
+ *
+ * A JSON-RPC batch is a single HTTP request and therefore gets a single status
+ * code, so one protected message taints the whole batch.  An empty or
+ * non-JSON-RPC body (a GET for the SSE stream, a DELETE to end a session) is
+ * never public — those still require a bearer token.
+ */
+export function isPublicRequest(body) {
+    const messages = Array.isArray(body) ? body : [body];
+    if (messages.length === 0)
+        return false;
+    return messages.every(isPublicMessage);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiquila-mcp",
-  "version": "0.3.29",
+  "version": "0.3.31",
   "description": "Nextcloud MCP server — files, calendar, contacts, mail, maps, notes, tasks & 120+ more tools",
   "type": "module",
   "main": "dist/index.js",