ofw-mcp 2.19.4 → 2.19.5

package/dist/index.js

@@ -36,7 +36,7 @@ const nodeAttachmentIO = new NodeAttachmentIO();
 // always succeeds before any credential check runs.
 await runMcp({
     name: 'ofw',
-    version: '2.19.4', // x-release-please-version
+    version: '2.19.5', // x-release-please-version
     deps: client,
     tools: [
         registerHealthcheckTools,

package/dist/tools/delivery.js

@@ -14,12 +14,29 @@
 //   2. extractable document   → the FILE'S TEXT, as text (see src/extract)
 //   3. raw bytes              → base64 EmbeddedResource, as before
 //
+// Rungs 1 and 3 are bounded by MAX_INLINE_BYTES (10 MiB raw; see below).
 // Rung 3 never disappears, so nothing regresses; rung 2 is what makes a
 // spreadsheet, PDF, Word or PowerPoint attachment readable at all. When a rung
 // is skipped or fails, the response says so by name in `deliveryAttempts` —
 // a caller must never be left guessing why it got bytes instead of content.
 import { extractAttachment } from '../extract/index.js';
 import { isHostRenderableImage } from './attachments.js';
+/**
+ * Upper bound on the RAW bytes this tool will return inline (as ImageContent
+ * or a base64 EmbeddedResource). Extracted text is not subject to it — that is
+ * already bounded by `maxChars`.
+ *
+ * Why 10 MiB: mcp-host, the hosted runtime that runs this MCP for claude.ai,
+ * caps any single child result at 14 MiB of serialized JSON-RPC
+ * (`CHILD_RESULT_MAX_BYTES`, chrischall/mcp-host#952) and replaces anything
+ * larger with a generic "result too large" tool error. 10 MiB raw is ~13.3 MiB
+ * as base64, which with the JSON-RPC envelope still fits under 14 MiB — so this
+ * bound fires first, with a message that says what to do instead. claude.ai
+ * itself accepts images up to 10 MB each (measured 2026-09-27), and before
+ * #952 anything over 10 MiB killed the child process outright. Real traffic
+ * for this tool has peaked at ~3 MB, so normal use never reaches it.
+ */
+export const MAX_INLINE_BYTES = 10 * 1024 * 1024;
 /**
  * Attempt extraction, converting every failure into a REASON rather than an
  * exception: a format we cannot read must still be delivered as bytes, and the
@@ -42,6 +59,26 @@ export async function tryExtract(bytes, mimeType, fileName, opts) {
         return { reason: `extraction failed: ${err instanceof Error ? err.message : String(err)}` };
     }
 }
+/**
+ * Refuse to inline more than {@link MAX_INLINE_BYTES}. This is a tool error
+ * rather than a fallback: the only non-inline channel is disk mode, which the
+ * hosted runtime (the one the cap protects) does not have, and silently
+ * writing to disk when the caller asked for content would not be honest.
+ */
+function assertInlineSize(input, rawRequested) {
+    const { bytes, fileName, fileId, diskAvailable } = input;
+    if (bytes.length <= MAX_INLINE_BYTES)
+        return;
+    const hints = [];
+    if (rawRequested)
+        hints.push('omit extract:false to get the file\'s extracted text instead, if it is a readable document type');
+    if (diskAvailable)
+        hints.push('pass inline:false to save it to disk and get the path');
+    hints.push('or open it directly in OurFamilyWizard');
+    throw new Error(`Attachment ${fileId} (${fileName}) is ${bytes.length} bytes, over the ${MAX_INLINE_BYTES / (1024 * 1024)} MiB `
+        + `limit for returning a file inline (a larger result would exceed the host's response size limit). `
+        + `To get it: ${hints.join('; ')}.`);
+}
 /**
  * Build the content blocks for an inline download by walking the ladder.
  * The first block is always a JSON meta block naming `deliveredVia`, so the
@@ -57,6 +94,7 @@ export async function buildInlineDelivery(input) {
     const block = () => ({ type: 'text', text: JSON.stringify(meta, null, 2) });
     // Rung 1 — the host renders these itself, and a picture beats a description.
     if (isHostRenderableImage(mimeType)) {
+        assertInlineSize(input, false);
         meta.deliveredVia = 'image';
         return { content: [block(), { type: 'image', data: bytes.toString('base64'), mimeType }] };
     }
@@ -80,8 +118,10 @@ export async function buildInlineDelivery(input) {
         /* v8 ignore next -- tryExtract always sets `reason` when it returns no extraction */
         attempts.push(outcome.reason ?? 'extraction produced no content');
     }
-    // Rung 3 — the bytes themselves. Always available, so a fetch that succeeded
-    // never ends with the caller holding nothing.
+    // Rung 3 — the bytes themselves. Always available up to MAX_INLINE_BYTES, so
+    // a fetch that succeeded never ends with the caller holding nothing; beyond
+    // it the caller gets a tool error that says how to reach the file instead.
+    assertInlineSize(input, options.extract === false);
     meta.deliveredVia = 'blob';
     meta.deliveryAttempts = attempts;
     meta.note = 'Returned as raw bytes. Some hosts cannot render an embedded resource of this type; '

package/dist/tools/healthcheck.js

@@ -62,7 +62,7 @@ resolve = resolveAuth) {
                 kind: 'transport',
                 // The upstream `.hint` rides along in `error.message` — it carries
                 // the actionable "click the toolbar icon" copy this cannot know.
-                hint: 'The fetchproxy bridge is down, so the browser path could not be tried. This is ' +
+                hint: 'ContextMint Bridge is down, so the browser path could not be tried. This is ' +
                     'not a credential problem: OFW_USERNAME/OFW_PASSWORD, if set, were not reached ' +
                     'either. See error.message for the extension-specific fix.',
             }
@@ -71,7 +71,7 @@ resolve = resolveAuth) {
             // Now means exactly what it says: nothing is set up. A configured path
             // that was tried and failed no longer lands here.
             no_credential: 'No OFW credential is configured. Either set OFW_USERNAME + OFW_PASSWORD, or install ' +
-                'the fetchproxy extension and sign in to ourfamilywizard.com in a tab (unsetting ' +
+                'ContextMint Bridge and sign in to ourfamilywizard.com in a tab (unsetting ' +
                 'OFW_DISABLE_FETCHPROXY if you set it).',
             credential_rejected: 'OurFamilyWizard rejected the credential. If it came from `env`, the password changed or ' +
                 'the account is locked; if from `fetchproxy`, the browser session expired — sign in again ' +

package/dist/tools/messages.js

@@ -1526,7 +1526,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             });
         });
     server.registerTool('ofw_download_attachment', {
-        description: 'Download an OFW message attachment by fileId and return content you can actually read. Inline delivery walks a ladder and returns the first rung that works: (1) host-renderable images (PNG/JPEG/GIF/WEBP) come back as ImageContent; (2) .xlsx/.csv/.tsv, .pdf, .docx, .pptx and text files come back as EXTRACTED CONTENT — per-sheet CSV, per-page/slide text, document text — in the response JSON under `extracted`; (3) anything else comes back as an EmbeddedResource blob of the raw bytes. The meta block names the rung as `deliveredVia` and, when it falls through to bytes, lists what was tried in `deliveryAttempts`. Reported mime types are always normalized to a bare media type (no charset/name parameters). In disk mode the bytes are saved to ~/Downloads/ofw-mcp/ and the response carries the absolute path; pass extract:true to ALSO get the extracted content in that response. The default for `inline` can be flipped server-side via the OFW_INLINE_ATTACHMENTS env var. On a hosted deployment with no filesystem, disk mode is unavailable, so inline is forced (forcedInline:true) rather than failing — a saveTo path never costs you the content. fileId comes from attachments[].fileId on ofw_get_message. Override disk destination with OFW_ATTACHMENTS_DIR or saveTo; saveTo must stay inside the attachments directory, and an existing file is never overwritten unless force:true. Re-downloading to the same path is a no-op (disk mode only).',
+        description: 'Download an OFW message attachment by fileId and return content you can actually read. Inline delivery walks a ladder and returns the first rung that works: (1) host-renderable images (PNG/JPEG/GIF/WEBP) come back as ImageContent; (2) .xlsx/.csv/.tsv, .pdf, .docx, .pptx and text files come back as EXTRACTED CONTENT — per-sheet CSV, per-page/slide text, document text — in the response JSON under `extracted`; (3) anything else comes back as an EmbeddedResource blob of the raw bytes. Images and raw bytes are only returned inline up to 10 MiB; a larger file fails with a tool error that says how to get it instead (extracted text is unaffected — it is bounded by maxChars). The meta block names the rung as `deliveredVia` and, when it falls through to bytes, lists what was tried in `deliveryAttempts`. Reported mime types are always normalized to a bare media type (no charset/name parameters). In disk mode the bytes are saved to ~/Downloads/ofw-mcp/ and the response carries the absolute path; pass extract:true to ALSO get the extracted content in that response. The default for `inline` can be flipped server-side via the OFW_INLINE_ATTACHMENTS env var. On a hosted deployment with no filesystem, disk mode is unavailable, so inline is forced (forcedInline:true) rather than failing — a saveTo path never costs you the content. fileId comes from attachments[].fileId on ofw_get_message. Override disk destination with OFW_ATTACHMENTS_DIR or saveTo; saveTo must stay inside the attachments directory, and an existing file is never overwritten unless force:true. Re-downloading to the same path is a no-op (disk mode only).',
         annotations: { readOnlyHint: false, destructiveHint: false },
         inputSchema: z.object({
             fileId: z.number().describe('Attachment file id (from ofw_get_message → attachments[].fileId)'),
@@ -1581,6 +1581,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             // ends up holding something readable.
             return await buildInlineDelivery({
                 fileId, fileName, mimeType, bytes, forcedInline, options: deliveryOptions,
+                diskAvailable: attachmentIO.supportsDisk,
             });
         }
         let dest;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.19.4",
+  "version": "2.19.5",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -34,8 +34,8 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.6.0",
-    "@fetchproxy/bootstrap": "^3.2.0",
+    "@chrischall/mcp-utils": "^2.8.0",
+    "@fetchproxy/bootstrap": "^3.4.1",
     "@modelcontextprotocol/server": "^2.0.0",
     "dotenv": "^18.0.0",
     "zod": "^4.6.5"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/ofw-mcp",
     "source": "github"
   },
-  "version": "2.19.4",
+  "version": "2.19.5",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.19.4",
+      "version": "2.19.5",
       "transport": {
         "type": "stdio"
       },

package/skills/ofw/SKILL.md

@@ -100,7 +100,7 @@ Always pass `--config ~/.mcporter/mcporter.json` unless a local `config/mcporter
 | `ofw_save_draft(subject, body, recipientIds?, messageId?, replyToId?, myFileIDs?, expectedRevision?, force?)` | Create a new draft. Pass `messageId` to **replace** an existing draft: the tool creates a fresh draft and deletes the old one (OFW's update-in-place endpoint silently no-ops). The returned `id` is the NEW id; the response leads with `draftKey`, which stays the same across every edit — **track that, not the id**. Note: OFW does **not** store recipients on drafts — `recipientIds` are accepted but come back empty (a one-line NOTE says so; supply them at send time instead). Threading warnings fire only on genuine drops — a draft echoing `inReplyTo`/`showContext` IS threaded. |
 | `ofw_delete_draft(messageId)` | Delete a draft. |
 | `ofw_upload_attachment(path, shareClass?, label?, description?)` | Upload a local file to My Files; returns a fileId to pass into `myFileIDs`. Only files inside the upload directory (`OFW_UPLOAD_DIR`, default `~/Downloads/ofw-mcp`) can be uploaded; hidden files are refused. `shareClass:"SHARED"` needs write mode `all`. |
-| `ofw_download_attachment(fileId, inline?, saveTo?, force?, extract?, maxChars?, parts?)` | Download an attachment. Inline delivery returns the first rung that works: image → `ImageContent`; .xlsx/.csv/.pdf/.docx/.pptx/text → **extracted content** under `extracted` (per-sheet CSV, per-page/slide text); anything else → raw bytes. Default writes to `~/Downloads/ofw-mcp/` (add `extract:true` for content too). Use `parts:"1-2"` / a sheet name and `maxChars` on large files. |
+| `ofw_download_attachment(fileId, inline?, saveTo?, force?, extract?, maxChars?, parts?)` | Download an attachment. Inline delivery returns the first rung that works: image → `ImageContent`; .xlsx/.csv/.pdf/.docx/.pptx/text → **extracted content** under `extracted` (per-sheet CSV, per-page/slide text); anything else → raw bytes. Default writes to `~/Downloads/ofw-mcp/` (add `extract:true` for content too). Use `parts:"1-2"` / a sheet name and `maxChars` on large files. Images and raw bytes over 10 MiB are not returned inline (tool error) — use disk mode or open the file in OFW. |
 | `ofw_check_freshness(folders?, messageIds?, allowMarkRead?)` | Cheap live check that the cache still matches OFW — one request for folder counts plus one per id, no bodies, no sync. Each id gets a live `state` (`draft`/`sent`/`received`/`deleted`/`unknown`) plus `folder` and `sentAt`. Probes ids cached as drafts, as sent, or as already-read inbox messages freely; anything else needs `allowMarkRead:true` (it would mark an inbox message read). |
 | `ofw_status(ids?, draftKeys?, includeDraftInventory?, allowMarkRead?)` | **The status call.** One live round trip. With no arguments: the full, server-verified draft inventory. With `ids`/`draftKeys`: each one's live lifecycle state. Top-level `complete` is true only when every part was verified live. |
 

package/skills/ofw-fpx/SKILL.md

@@ -33,13 +33,16 @@ dry-run/confirm here — curl just does it. Treat every write like the MCP's
 npm install -g @fetchproxy/cli                                       # provides `fpx`
 fpx profile add ofw --domain ourfamilywizard.com
 fpx profile declare ofw --local-storage auth --local-storage tokenExpiry
-fpx pair -p ofw                                                       # prints a pair code → approve in Transporter
+fpx pair -p ofw                                                       # prints a pair code → approve in ContextMint Bridge
 ```
 
-Requirements: the **Transporter** browser extension installed, with an
+Requirements: the **ContextMint Bridge** browser extension installed
+([releases](https://github.com/nullnet-app/contextmint-bridge/releases) —
+Chrome: load the Chrome zip unpacked; Safari isn't available yet, so use Chrome for now), with an
 open, signed-in `ofw.ourfamilywizard.com` (or `www.ourfamilywizard.com`)
 tab, and its Chrome **Site access** allowing `ourfamilywizard.com`. Pairing
 persists across invocations.
+ContextMint Bridge is the fetchproxy extension renamed, same maintainer (see https://github.com/chrischall/fetchproxy#extension); source at https://github.com/nullnet-app/contextmint-bridge — build it, or verify a release zip with `shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256`.
 
 ## Capture the token (once per shell / whenever it goes stale)