ofw-mcp 2.0.10 → 2.0.12

package/dist/cache.js

@@ -131,9 +131,9 @@ export function getMessage(id) {
     const r = db.prepare('SELECT * FROM messages WHERE id = ?').get(id);
     return r ? rowFromDb(r) : null;
 }
-export function listMessages(opts) {
-    const { db } = openCache();
-    const offset = (opts.page - 1) * opts.size;
+// Build the WHERE clause + bound params for message queries. listMessages and
+// countMessages share this so the filter semantics can't drift.
+function buildMessageFilter(opts) {
     const wheres = [];
     const params = [];
     if (opts.folder !== undefined) {
@@ -153,35 +153,23 @@ export function listMessages(opts) {
         wheres.push('(subject LIKE ? OR body LIKE ?)');
         params.push(pattern, pattern);
     }
-    const where = wheres.length > 0 ? `WHERE ${wheres.join(' AND ')}` : '';
-    params.push(opts.size, offset);
+    return {
+        where: wheres.length > 0 ? `WHERE ${wheres.join(' AND ')}` : '',
+        params,
+    };
+}
+export function listMessages(opts) {
+    const { db } = openCache();
+    const { where, params } = buildMessageFilter(opts);
+    const offset = (opts.page - 1) * opts.size;
     const rows = db.prepare(`SELECT * FROM messages ${where}
      ORDER BY sent_at DESC, id DESC
-     LIMIT ? OFFSET ?`).all(...params);
+     LIMIT ? OFFSET ?`).all(...params, opts.size, offset);
     return rows.map(rowFromDb);
 }
 export function countMessages(opts) {
     const { db } = openCache();
-    const wheres = [];
-    const params = [];
-    if (opts.folder !== undefined) {
-        wheres.push('folder = ?');
-        params.push(opts.folder);
-    }
-    if (opts.since !== undefined) {
-        wheres.push('sent_at >= ?');
-        params.push(opts.since);
-    }
-    if (opts.until !== undefined) {
-        wheres.push('sent_at < ?');
-        params.push(opts.until);
-    }
-    if (opts.q !== undefined && opts.q.length > 0) {
-        const pattern = `%${opts.q}%`;
-        wheres.push('(subject LIKE ? OR body LIKE ?)');
-        params.push(pattern, pattern);
-    }
-    const where = wheres.length > 0 ? `WHERE ${wheres.join(' AND ')}` : '';
+    const { where, params } = buildMessageFilter(opts);
     const r = db.prepare(`SELECT COUNT(*) as n FROM messages ${where}`)
         .get(...params);
     return r?.n ?? 0;
@@ -295,13 +283,19 @@ export function upsertAttachmentForMessage(input) {
     const { db } = openCache();
     const existing = db.prepare('SELECT message_ids_json FROM attachments WHERE file_id = ?')
         .get(input.fileId);
+    // messageId === 0 is the "metadata-only, not yet linked to a message"
+    // sentinel used by upload-without-send and download-by-id. Don't
+    // pollute the array with it — leave the list empty / unchanged.
+    const prior = existing ? JSON.parse(existing.message_ids_json) : [];
     let messageIds;
-    if (existing) {
-        const arr = JSON.parse(existing.message_ids_json);
-        messageIds = arr.includes(input.messageId) ? arr : [...arr, input.messageId];
+    if (input.messageId === 0) {
+        messageIds = prior;
+    }
+    else if (prior.includes(input.messageId)) {
+        messageIds = prior;
     }
     else {
-        messageIds = [input.messageId];
+        messageIds = [...prior, input.messageId];
     }
     db.prepare(`INSERT INTO attachments (
        file_id, file_name, label, mime_type, size_bytes,

package/dist/client.js

@@ -28,78 +28,56 @@ function readVar(key) {
     return trimmed;
 }
 const BASE_URL = 'https://ofw.ourfamilywizard.com';
-const STATIC_HEADERS = {
+const OFW_PROTOCOL_HEADERS = {
     'ofw-client': 'WebApplication',
     'ofw-version': '1.0.0',
-    Accept: 'application/json',
-    'Content-Type': 'application/json',
 };
+// Parse a Content-Disposition header for a filename. Prefers RFC 6266
+// `filename*=UTF-8''…` (percent-decoded) and falls back to `filename="…"`.
+function parseContentDispositionFilename(cd) {
+    const extMatch = /filename\*=(?:UTF-8'')?([^;]+)/i.exec(cd);
+    if (extMatch) {
+        const raw = extMatch[1].trim().replace(/^"|"$/g, '');
+        try {
+            return decodeURIComponent(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    const m = /filename="?([^";]+)"?/i.exec(cd);
+    return m ? m[1] : null;
+}
 export class OFWClient {
     token = null;
     tokenExpiry = null;
     async request(method, path, body) {
         await this.ensureAuthenticated();
-        return this.doRequest(method, path, body, false);
+        const response = await this.fetchWithRetry(method, path, body, 'application/json', false);
+        const text = await response.text();
+        return (text ? JSON.parse(text) : null);
     }
     /** Like `request`, but returns the raw bytes plus Content-Type/-Disposition metadata. */
     async requestBinary(method, path) {
         await this.ensureAuthenticated();
-        return this.doRequestBinary(method, path, false);
-    }
-    async doRequestBinary(method, path, isRetry) {
-        const headers = {
-            'ofw-client': 'WebApplication',
-            'ofw-version': '1.0.0',
-            Accept: 'application/octet-stream',
-            Authorization: `Bearer ${this.token}`,
-        };
-        const response = await fetch(`${BASE_URL}${path}`, { method, headers });
-        if (response.status === 401 && !isRetry) {
-            this.token = null;
-            this.tokenExpiry = null;
-            await this.ensureAuthenticated();
-            return this.doRequestBinary(method, path, true);
-        }
-        if (response.status === 429 && !isRetry) {
-            await new Promise((r) => setTimeout(r, 2000));
-            return this.doRequestBinary(method, path, true);
-        }
-        if (!response.ok) {
-            throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}`);
-        }
-        const buf = Buffer.from(await response.arrayBuffer());
-        const cd = response.headers.get('content-disposition') ?? '';
-        // RFC 6266: filename*=UTF-8''… takes priority; fall back to filename="…"
-        let suggestedFileName = null;
-        const extMatch = /filename\*=(?:UTF-8'')?([^;]+)/i.exec(cd);
-        if (extMatch) {
-            try {
-                suggestedFileName = decodeURIComponent(extMatch[1].trim().replace(/^"|"$/g, ''));
-            }
-            catch {
-                suggestedFileName = extMatch[1];
-            }
-        }
-        else {
-            const m = /filename="?([^";]+)"?/i.exec(cd);
-            if (m)
-                suggestedFileName = m[1];
-        }
+        const response = await this.fetchWithRetry(method, path, undefined, 'application/octet-stream', false);
         return {
-            body: buf,
+            body: Buffer.from(await response.arrayBuffer()),
             contentType: response.headers.get('content-type'),
-            suggestedFileName,
+            suggestedFileName: parseContentDispositionFilename(response.headers.get('content-disposition') ?? ''),
         };
     }
-    async doRequest(method, path, body, isRetry) {
+    // Single fetch+retry scaffold for both JSON and binary callers. Handles
+    // 401 (re-auth and replay once), 429 (wait 2s and replay once), and
+    // turns any other non-2xx into a thrown Error.
+    async fetchWithRetry(method, path, body, accept, isRetry) {
         const isFormData = body instanceof FormData;
         const headers = {
-            'ofw-client': 'WebApplication',
-            'ofw-version': '1.0.0',
-            Accept: 'application/json',
+            ...OFW_PROTOCOL_HEADERS,
+            Accept: accept,
             Authorization: `Bearer ${this.token}`,
         };
-        if (!isFormData)
+        if (body !== undefined && !isFormData)
             headers['Content-Type'] = 'application/json';
         const response = await fetch(`${BASE_URL}${path}`, {
             method,
@@ -110,20 +88,19 @@ export class OFWClient {
             this.token = null;
             this.tokenExpiry = null;
             await this.ensureAuthenticated();
-            return this.doRequest(method, path, body, true);
+            return this.fetchWithRetry(method, path, body, accept, true);
         }
         if (response.status === 429) {
             if (!isRetry) {
                 await new Promise((r) => setTimeout(r, 2000));
-                return this.doRequest(method, path, body, true);
+                return this.fetchWithRetry(method, path, body, accept, true);
             }
             throw new Error('Rate limited by OFW API');
         }
         if (!response.ok) {
             throw new Error(`OFW API error: ${response.status} ${response.statusText} for ${method} ${path}`);
         }
-        const text = await response.text();
-        return (text ? JSON.parse(text) : null);
+        return response;
     }
     async ensureAuthenticated() {
         if (!this.isTokenExpiredSoon())
@@ -139,23 +116,24 @@ export class OFWClient {
         // Spring Security requires a SESSION cookie before accepting the login POST.
         // GET /ofw/login.form with redirect:manual to capture the Set-Cookie from the 303 response.
         const initResponse = await fetch(`${BASE_URL}/ofw/login.form`, {
-            headers: { 'ofw-client': 'WebApplication', 'ofw-version': '1.0.0' },
+            headers: { ...OFW_PROTOCOL_HEADERS },
             redirect: 'manual',
         });
         // Extract just the SESSION=value part (strip attributes like Path, Secure, etc.)
         const setCookie = initResponse.headers.get('set-cookie') ?? '';
-        const sessionCookie = setCookie.split(';')[0]; // split always returns a string; empty string is falsy
+        const sessionCookie = setCookie.split(';')[0];
         const response = await fetch(`${BASE_URL}/ofw/login`, {
             method: 'POST',
             headers: {
-                ...STATIC_HEADERS,
+                ...OFW_PROTOCOL_HEADERS,
+                Accept: 'application/json',
                 'Content-Type': 'application/x-www-form-urlencoded',
                 ...(sessionCookie ? { Cookie: sessionCookie } : {}),
             },
             body: new URLSearchParams({
                 submit: 'Sign In',
                 _eventId: 'submit',
-                username: username,
+                username,
                 password,
             }).toString(),
         });

package/dist/config.js

@@ -23,8 +23,21 @@ export function getAttachmentsDir() {
     const override = process.env.OFW_ATTACHMENTS_DIR;
     if (override && override.trim().length > 0)
         return override.trim();
-    // Sibling to the cache db: ~/.cache/ofw-mcp/attachments/<hash>/
-    const username = readUsername();
-    const hash = createHash('sha256').update(username).digest('hex').slice(0, 16);
-    return join(getCacheDir(), 'attachments', hash);
+    // Default to ~/Downloads/ofw-mcp/ — the cache dir (~/.cache/...) is hidden and
+    // typically outside the filesystem allowlist of sandboxed MCP hosts like
+    // Claude Desktop, so files written there are unreadable to the model that
+    // just downloaded them. Downloads is the standard "user-accessible files"
+    // location across macOS/Linux/Windows.
+    return join(homedir(), 'Downloads', 'ofw-mcp');
+}
+// Default for ofw_download_attachment's `inline` arg when the caller doesn't
+// pass one. Set OFW_INLINE_ATTACHMENTS=true to have attachments returned as
+// MCP content blocks by default (skipping disk) — useful on sandboxed MCP
+// hosts where filesystem reads back to the model aren't available.
+// Accepts: "1", "true", "yes", "on" (case-insensitive) → true; anything else → false.
+export function getDefaultInlineAttachments() {
+    const raw = process.env.OFW_INLINE_ATTACHMENTS;
+    if (typeof raw !== 'string')
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase());
 }

package/dist/index.js

@@ -17,7 +17,7 @@ import { registerMessageTools } from './tools/messages.js';
 import { registerCalendarTools } from './tools/calendar.js';
 import { registerExpenseTools } from './tools/expenses.js';
 import { registerJournalTools } from './tools/journal.js';
-const server = new McpServer({ name: 'ofw', version: '2.0.10' });
+const server = new McpServer({ name: 'ofw', version: '2.0.12' });
 registerUserTools(server, client);
 registerMessageTools(server, client);
 registerCalendarTools(server, client);

package/dist/sync.js

@@ -1,26 +1,30 @@
 import { setMeta, upsertMessage, getMessage, setSyncState, upsertDraft, getDraft, deleteDraft, listDraftIds, upsertAttachmentForMessage, } from './cache.js';
-export async function fetchAndCacheAttachmentMeta(client, fileId, messageId) {
-    try {
-        const meta = await client.request('GET', `/pub/v1/myfiles/${fileId}`);
-        upsertAttachmentForMessage({
-            fileId: meta.fileId ?? fileId,
-            fileName: meta.fileName ?? `file-${fileId}`,
-            label: meta.label ?? meta.fileName ?? `file-${fileId}`,
-            mimeType: meta.fileType ?? 'application/octet-stream',
-            sizeBytes: typeof meta.fileSize === 'number' ? meta.fileSize : null,
-            metadata: meta,
-            messageId,
-        });
-    }
-    catch {
-        // Attachment metadata failures shouldn't break the surrounding sync.
-        // The file ids stay in the message's listData; the model can retry later
-        // via ofw_download_attachment, which will surface the actual error.
-    }
+import { mapRecipients } from './tools/_shared.js';
+// Fetches OFW attachment metadata for one file id and writes it to the cache.
+// Throws on network/HTTP errors — callers in bulk-sync paths wrap this in the
+// best-effort helper below; callers that need the result (download tool) let
+// the throw propagate.
+export async function fetchAttachmentMeta(client, fileId, messageId) {
+    const meta = await client.request('GET', `/pub/v1/myfiles/${fileId}`);
+    upsertAttachmentForMessage({
+        fileId: meta.fileId ?? fileId,
+        fileName: meta.fileName ?? `file-${fileId}`,
+        label: meta.label ?? meta.fileName ?? `file-${fileId}`,
+        mimeType: meta.fileType ?? 'application/octet-stream',
+        sizeBytes: typeof meta.fileSize === 'number' ? meta.fileSize : null,
+        metadata: meta,
+        messageId,
+    });
 }
 export async function fetchAttachmentMetaForMessage(client, messageId, fileIds) {
     for (const fid of fileIds) {
-        await fetchAndCacheAttachmentMeta(client, fid, messageId);
+        // Best-effort: a single bad attachment shouldn't break the surrounding
+        // sync. The file id stays in the message's listData; the model can
+        // retry later via ofw_download_attachment, which surfaces the real error.
+        try {
+            await fetchAttachmentMeta(client, fid, messageId);
+        }
+        catch { /* swallow */ }
     }
 }
 export async function resolveFolderIds(client) {
@@ -40,13 +44,6 @@ export async function resolveFolderIds(client) {
     setMeta('drafts_folder_id', ids.drafts);
     return ids;
 }
-function recipientsFromList(item) {
-    return (item.recipients ?? []).map((r) => ({
-        userId: r.user.id,
-        name: r.user.name,
-        viewedAt: r.viewed?.dateTime ?? null,
-    }));
-}
 export async function syncMessageFolder(client, folder, folderId, opts) {
     let page = 1;
     let synced = 0;
@@ -93,7 +90,7 @@ export async function syncMessageFolder(client, folder, folderId, opts) {
                 subject: item.subject ?? '(no subject)',
                 fromUser: item.from?.name ?? '',
                 sentAt: item.date?.dateTime ?? new Date().toISOString(),
-                recipients: recipientsFromList(item),
+                recipients: mapRecipients(item.recipients),
                 body,
                 fetchedBodyAt,
                 replyToId: null,
@@ -139,11 +136,7 @@ export async function syncDrafts(client, draftsFolderId) {
             id: item.id,
             subject: detail.subject ?? item.subject ?? '(no subject)',
             body: detail.body ?? '',
-            recipients: (item.recipients ?? []).map((r) => ({
-                userId: r.user?.id ?? 0,
-                name: r.user?.name ?? '',
-                viewedAt: r.viewed?.dateTime ?? null,
-            })),
+            recipients: mapRecipients(item.recipients),
             replyToId: item.replyToId ?? null,
             modifiedAt,
             listData: item,

package/dist/tools/_shared.js

@@ -0,0 +1,22 @@
+import { isAbsolute, join, resolve } from 'node:path';
+export function jsonResponse(payload) {
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+export function textResponse(text) {
+    return { content: [{ type: 'text', text }] };
+}
+// Translates OFW API recipient shape into the cache's normalized Recipient.
+// Used wherever we surface or persist recipients (sync, get_message, send,
+// save_draft) — all five call sites had near-identical inline mappings.
+export function mapRecipients(items) {
+    return (items ?? []).map((r) => ({
+        userId: r.user?.id ?? 0,
+        name: r.user?.name ?? '',
+        viewedAt: r.viewed?.dateTime ?? null,
+    }));
+}
+// Expand a user-provided path: ~ → $HOME, relative → absolute.
+export function expandPath(p) {
+    const expanded = p.startsWith('~/') ? join(process.env.HOME ?? '', p.slice(2)) : p;
+    return isAbsolute(expanded) ? expanded : resolve(expanded);
+}

package/dist/tools/calendar.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { jsonResponse, textResponse } from './_shared.js';
 export function registerCalendarTools(server, client) {
     server.registerTool('ofw_list_events', {
         description: 'List OurFamilyWizard calendar events in a date range',
@@ -11,7 +12,7 @@ export function registerCalendarTools(server, client) {
     }, async (args) => {
         const variant = args.detailed ? 'detailed' : 'basic';
         const data = await client.request('GET', `/pub/v1/calendar/${variant}?startDate=${encodeURIComponent(args.startDate)}&endDate=${encodeURIComponent(args.endDate)}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return jsonResponse(data);
     });
     server.registerTool('ofw_create_event', {
         description: 'Create a calendar event in OurFamilyWizard',
@@ -31,7 +32,7 @@ export function registerCalendarTools(server, client) {
         },
     }, async (args) => {
         const data = await client.request('POST', '/pub/v1/calendar/events', args);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return jsonResponse(data);
     });
     server.registerTool('ofw_update_event', {
         description: 'Update an existing OurFamilyWizard calendar event',
@@ -49,7 +50,7 @@ export function registerCalendarTools(server, client) {
     }, async (args) => {
         const { eventId, ...updateData } = args;
         const data = await client.request('PUT', `/pub/v1/calendar/events/${encodeURIComponent(eventId)}`, updateData);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return jsonResponse(data);
     });
     server.registerTool('ofw_delete_event', {
         description: 'Delete an OurFamilyWizard calendar event',
@@ -59,6 +60,6 @@ export function registerCalendarTools(server, client) {
         },
     }, async (args) => {
         await client.request('DELETE', `/pub/v1/calendar/events/${encodeURIComponent(args.eventId)}`);
-        return { content: [{ type: 'text', text: `Event ${args.eventId} deleted` }] };
+        return textResponse(`Event ${args.eventId} deleted`);
     });
 }

package/dist/tools/expenses.js

@@ -1,11 +1,12 @@
 import { z } from 'zod';
+import { jsonResponse } from './_shared.js';
 export function registerExpenseTools(server, client) {
     server.registerTool('ofw_get_expense_totals', {
         description: 'Get OurFamilyWizard expense summary totals (owed/paid)',
         annotations: { readOnlyHint: true },
     }, async () => {
         const data = await client.request('GET', '/pub/v2/expense/expenses/totals');
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return jsonResponse(data);
     });
     server.registerTool('ofw_list_expenses', {
         description: 'List OurFamilyWizard expenses with pagination',
@@ -18,7 +19,7 @@ export function registerExpenseTools(server, client) {
         const start = args.start ?? 0;
         const max = args.max ?? 20;
         const data = await client.request('GET', `/pub/v2/expense/expenses?start=${start}&max=${max}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return jsonResponse(data);
     });
     server.registerTool('ofw_create_expense', {
         description: 'Log a new expense in OurFamilyWizard',
@@ -29,6 +30,6 @@ export function registerExpenseTools(server, client) {
         },
     }, async (args) => {
         const data = await client.request('POST', '/pub/v2/expense/expenses', args);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return jsonResponse(data);
     });
 }

package/dist/tools/journal.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { jsonResponse } from './_shared.js';
 export function registerJournalTools(server, client) {
     server.registerTool('ofw_list_journal_entries', {
         description: 'List OurFamilyWizard journal entries',
@@ -12,7 +13,7 @@ export function registerJournalTools(server, client) {
         const start = args.start ?? 1;
         const max = args.max ?? 10;
         const data = await client.request('GET', `/pub/v1/journals?start=${start}&max=${max}`);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return jsonResponse(data);
     });
     server.registerTool('ofw_create_journal_entry', {
         description: 'Create a new journal entry in OurFamilyWizard',
@@ -23,6 +24,6 @@ export function registerJournalTools(server, client) {
         },
     }, async (args) => {
         const data = await client.request('POST', '/pub/v1/journals', args);
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return jsonResponse(data);
     });
 }