ofw-mcp 2.4.3 → 2.5.0

package/dist/bundle.js

@@ -34686,6 +34686,22 @@ async function runMcp(opts) {
 }
 
 // node_modules/@chrischall/mcp-utils/dist/errors/index.js
+var McpToolError = class extends Error {
+  /** Actionable remediation text, when one applies. */
+  hint;
+  constructor(message, opts) {
+    super(message, opts?.cause !== void 0 ? { cause: opts.cause } : void 0);
+    this.name = "McpToolError";
+    if (opts?.hint !== void 0)
+      this.hint = opts.hint;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var BEARER_RE = /(bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi;
+var JWT_RE = /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{8,}\b/g;
+var BASIC_AUTH_RE = /(authorization\s*:\s*basic\s+)[A-Za-z0-9+/=_-]{6,}/gi;
+var SET_COOKIE_RE = /(\bset-cookie\s*:\s*)([^=;,\s]+)=[^;,\s]*/gi;
+var COOKIE_HEADER_RE = /((?<!set-)\bcookie\s*:\s*)((?:[^=;,\s]+=[^;,\s]*)(?:;\s*[^=;,\s]+=[^;,\s]*)*)/gi;
 var API_KEY_RE = new RegExp([
   "sk-[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])",
   // OpenAI / Anthropic (incl. sk-ant-…)
@@ -34700,6 +34716,14 @@ var API_KEY_RE = new RegExp([
   "whsec_[A-Za-z0-9]{16,}\\b"
   // webhook signing secret (Stripe-style)
 ].map((p) => `\\b${p}`).join("|"), "g");
+var QUERY_SECRET_RE = /([?&](?:access_token|refresh_token|client_secret|api_?key|signature|token|key|sig)=)[^&#\s"'<>`]+/gi;
+var AWS_SIGV4_RE = /([?&]X-Amz-(?:Signature|Security-Token|Credential)=)[^&#\s"'<>`]+/gi;
+var JSON_SECRET_KEYS = "access_token|refresh_token|client_secret|api_?key|password|passwd|secret|token";
+var JSON_SECRET_DQ_RE = new RegExp(`("(?:${JSON_SECRET_KEYS})"\\s*:\\s*")[^"]*(")`, "gi");
+var JSON_SECRET_SQ_RE = new RegExp(`('(?:${JSON_SECRET_KEYS})'\\s*:\\s*')[^']*(')`, "gi");
+function redactSecrets(text) {
+  return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(AWS_SIGV4_RE, "$1[REDACTED]").replace(JSON_SECRET_DQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_SQ_RE, "$1[REDACTED]$2").replace(JWT_RE, "[REDACTED]");
+}
 
 // node_modules/@chrischall/mcp-utils/dist/response/index.js
 function textResult(data) {
@@ -34781,6 +34805,21 @@ async function fileBlob(path, opts = {}) {
   return blob;
 }
 
+// node_modules/@chrischall/mcp-utils/dist/zod/parse-lenient.js
+function parseLenient(schema, raw, opts) {
+  const result = schema.safeParse(raw);
+  if (result.success)
+    return result.data;
+  const issues = result.error.issues.map((issue2) => `${issue2.path.join(".") || "(root)"}: ${issue2.message}`).join("; ");
+  if (opts.mode === "strict") {
+    throw new McpToolError(`Unexpected ${opts.context} shape from the upstream API. ${issues}`, {
+      hint: "The upstream API may have changed; the schema needs updating."
+    });
+  }
+  console.error(`[${opts.label}] WARNING: unexpected ${opts.context} shape \u2014 proceeding with the raw response. ${issues}`);
+  return raw;
+}
+
 // node_modules/@chrischall/mcp-utils/dist/zod/index.js
 var PositiveInt = external_exports.number().int().positive();
 var NonNegInt = external_exports.number().int().nonnegative();
@@ -34878,7 +34917,7 @@ var TokenManager = class {
 };
 
 // src/client.ts
-import { dirname, join as join4 } from "path";
+import { dirname, join as join3 } from "path";
 import { fileURLToPath } from "url";
 
 // node_modules/@fetchproxy/protocol/dist/frames.js
@@ -34892,6 +34931,7 @@ var KNOWN_CAPABILITIES = /* @__PURE__ */ new Set([
   "capture_request_header",
   "capture_redirect",
   "read_indexed_db",
+  "read_dom",
   "download"
 ]);
 
@@ -35193,6 +35233,44 @@ function assertIndexedDbScopesArray(value, label) {
     }
   }
 }
+var DOM_SELECTOR_RE = /^[^-]{1,512}$/;
+var DOM_ATTRIBUTE_RE = /^[A-Za-z_:][A-Za-z0-9_:.\-]{0,127}$/;
+function assertDomSelectorsArray(value, label) {
+  if (!Array.isArray(value)) {
+    throw new ProtocolError(`${label}: expected array, got ${typeof value}`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (let i = 0; i < value.length; i++) {
+    const entry = value[i];
+    assertObject(entry, `${label}[${i}]`);
+    if (entry.name === void 0) {
+      throw new ProtocolError(`${label}[${i}].name: missing`);
+    }
+    if (entry.selector === void 0) {
+      throw new ProtocolError(`${label}[${i}].selector: missing`);
+    }
+    if (typeof entry.name !== "string" || !SCOPE_KEY_RE.test(entry.name)) {
+      throw new ProtocolError(`${label}[${i}].name: invalid ${JSON.stringify(entry.name)}`);
+    }
+    if (typeof entry.selector !== "string" || !DOM_SELECTOR_RE.test(entry.selector)) {
+      throw new ProtocolError(`${label}[${i}].selector: invalid ${JSON.stringify(entry.selector)}`);
+    }
+    if (entry.attribute !== void 0) {
+      if (typeof entry.attribute !== "string" || !DOM_ATTRIBUTE_RE.test(entry.attribute)) {
+        throw new ProtocolError(`${label}[${i}].attribute: invalid ${JSON.stringify(entry.attribute)}`);
+      }
+    }
+    if (seen.has(entry.name)) {
+      throw new ProtocolError(`${label}: duplicate name ${JSON.stringify(entry.name)}`);
+    }
+    seen.add(entry.name);
+    for (const k of Object.keys(entry)) {
+      if (k !== "name" && k !== "selector" && k !== "attribute") {
+        throw new ProtocolError(`${label}[${i}]: unexpected field ${JSON.stringify(k)}`);
+      }
+    }
+  }
+}
 function validateFrame(raw) {
   assertObject(raw, "frame");
   const t = raw.type;
@@ -35268,6 +35346,9 @@ function validateHello(raw) {
     if (raw.sessionStoragePointers !== void 0) {
       assertStoragePointersArray(raw.sessionStoragePointers, "hello.sessionStoragePointers", raw.sessionStorageKeys);
     }
+    if (raw.domSelectors !== void 0) {
+      assertDomSelectorsArray(raw.domSelectors, "hello.domSelectors");
+    }
     assertBase64(raw.identityX25519Pub, "hello.identityX25519Pub");
     assertBase64(raw.identityEd25519Pub, "hello.identityEd25519Pub");
     assertBase64(raw.sessionNonce, "hello.sessionNonce");
@@ -35502,6 +35583,21 @@ function validateInnerRequest(raw) {
     }
     return raw;
   }
+  if (raw.op === "read_dom") {
+    assertObject(raw.init, "inner.init");
+    if (raw.init.origin === void 0)
+      throw new ProtocolError("inner.init.origin: missing");
+    if (raw.init.names === void 0)
+      throw new ProtocolError("inner.init.names: missing");
+    assertHttpsOriginOnly(raw.init.origin, "inner.init.origin");
+    assertNonEmptyKeyArray(raw.init.names, "inner.init.names");
+    for (const k of Object.keys(raw.init)) {
+      if (k !== "origin" && k !== "names") {
+        throw new ProtocolError(`inner.init: unexpected field ${JSON.stringify(k)} on read_dom`);
+      }
+    }
+    return raw;
+  }
   if (raw.op === "download") {
     assertObject(raw.init, "inner.init");
     if (raw.init.url === void 0) {
@@ -35527,7 +35623,7 @@ function validateInnerRequest(raw) {
     }
     return raw;
   }
-  throw new ProtocolError(`inner.op: must be one of "fetch", "read_cookies", "read_local_storage", "read_session_storage", "capture_request_header", "capture_redirect", "read_indexed_db", "download"; got ${JSON.stringify(raw.op)}`);
+  throw new ProtocolError(`inner.op: must be one of "fetch", "read_cookies", "read_local_storage", "read_session_storage", "capture_request_header", "capture_redirect", "read_indexed_db", "read_dom", "download"; got ${JSON.stringify(raw.op)}`);
 }
 function assertNonEmptyKeyArray(value, label) {
   if (!Array.isArray(value)) {
@@ -35612,6 +35708,13 @@ function validateInnerResponse(raw) {
       assertObject(raw.values, "inner.values");
       return raw;
     }
+    if (op === "read_dom") {
+      if (raw.values === void 0) {
+        throw new ProtocolError("inner.values: missing on read_dom response");
+      }
+      assertStringMap(raw.values, "inner.values");
+      return raw;
+    }
     if (op === "download") {
       assertObject(raw.value, "inner.value");
       assertString(raw.value.path, "inner.value.path");
@@ -35951,6 +36054,13 @@ async function buildServerHello(opts) {
       jsonPointer: d.jsonPointer
     }));
   }
+  if (opts.domSelectors && opts.domSelectors.length > 0) {
+    hello.domSelectors = opts.domSelectors.map((d) => ({
+      name: d.name,
+      selector: d.selector,
+      ...d.attribute !== void 0 ? { attribute: d.attribute } : {}
+    }));
+  }
   return hello;
 }
 
@@ -36040,7 +36150,8 @@ async function startHost(opts) {
     captureHeaders: opts.ownCaptureHeaders,
     indexedDbScopes: opts.ownIndexedDbScopes,
     localStoragePointers: opts.ownLocalStoragePointers,
-    sessionStoragePointers: opts.ownSessionStoragePointers
+    sessionStoragePointers: opts.ownSessionStoragePointers,
+    domSelectors: opts.ownDomSelectors
   });
   const ownSessionNonce = fromB64(ownHello.sessionNonce);
   let extensionWs = null;
@@ -36275,6 +36386,7 @@ async function startPeer(opts) {
     sessionStorageKeys: opts.sessionStorageKeys,
     captureHeaders: opts.captureHeaders,
     indexedDbScopes: opts.indexedDbScopes,
+    domSelectors: opts.domSelectors,
     localStoragePointers: opts.localStoragePointers,
     sessionStoragePointers: opts.sessionStoragePointers
   });
@@ -36682,6 +36794,11 @@ var FetchproxyServer = class {
         key: d.key,
         jsonPointer: d.jsonPointer
       })),
+      domSelectors: (opts.domSelectors ?? []).map((d) => ({
+        name: d.name,
+        selector: d.selector,
+        ...d.attribute !== void 0 ? { attribute: d.attribute } : {}
+      })),
       // 0.8.0+: timer + lazy-revive default to ON. Every realty MCP
       // adapter was about to set these to the same numbers anyway; the
       // back-door is `0` (explicit opt-out) if a caller genuinely wants
@@ -36802,6 +36919,7 @@ var FetchproxyServer = class {
         ownIndexedDbScopes: this.opts.indexedDbScopes,
         ownLocalStoragePointers: this.opts.localStoragePointers,
         ownSessionStoragePointers: this.opts.sessionStoragePointers,
+        ownDomSelectors: this.opts.domSelectors,
         onPairCode: this.opts.onPairCode
       });
       this.hostHandle.onOwnInner((inner) => this.onInner(inner));
@@ -36829,7 +36947,8 @@ var FetchproxyServer = class {
         captureHeaders: this.opts.captureHeaders,
         indexedDbScopes: this.opts.indexedDbScopes,
         localStoragePointers: this.opts.localStoragePointers,
-        sessionStoragePointers: this.opts.sessionStoragePointers
+        sessionStoragePointers: this.opts.sessionStoragePointers,
+        domSelectors: this.opts.domSelectors
       });
       this.peerHandle.onInner((inner) => this.onInner(inner));
       this.peerHandle.onRenegotiate(() => {
@@ -37804,6 +37923,46 @@ var FetchproxyServer = class {
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingIdb, id, origin);
   }
+  /**
+   * 1.4.0+: read declared DOM values from the user's signed-in tab.
+   * Requires `'read_dom'` in capabilities AND every requested `name` to
+   * match a declared `domSelectors` entry. The extension reads each
+   * declared selector from the matched tab's DOM (isolated-world
+   * `querySelector`, value or attribute) — no page-JS execution.
+   *
+   * Returns a `Record<string, string>` of `name → value`, with names
+   * whose element (or attribute) was absent omitted. Throws
+   * `FetchproxyProtocolError` on bridge failures and a plain `Error` on
+   * developer mistakes (undeclared capability, undeclared name).
+   */
+  async readDom(opts) {
+    if (!this.opts.capabilities.includes("read_dom")) {
+      throw new Error('FetchproxyServer.readDom(): MCP did not declare "read_dom" in capabilities');
+    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
+    if (!Array.isArray(opts.names) || opts.names.length === 0) {
+      throw new Error("FetchproxyServer.readDom: opts.names must be a non-empty array");
+    }
+    this.assertScopeSubset(opts.names, this.opts.domSelectors.map((d) => d.name), "domSelectors");
+    if (opts.subdomain !== void 0)
+      assertSubdomainLabel(opts.subdomain);
+    const baseDomain = this.resolveBaseDomain(opts.domain);
+    const host = opts.subdomain ? `${opts.subdomain}.${baseDomain}` : baseDomain;
+    const origin = `https://${host}`;
+    const id = this.nextRequestId++;
+    const inner = {
+      type: "request",
+      id,
+      op: "read_dom",
+      init: { origin, names: [...opts.names] }
+    };
+    const pending = new Promise((resolve2, reject) => {
+      this.pendingStorage.set(id, { resolve: resolve2, reject });
+    });
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingStorage, id, origin);
+  }
   assertScopeSubset(requested, declared, label) {
     const undeclared = undeclaredKeys(requested, declared);
     if (undeclared.length > 0) {
@@ -37875,7 +38034,7 @@ var FetchproxyServer = class {
     if (storageCb) {
       this.pendingStorage.delete(inner.id);
       if (inner.ok) {
-        if ((inner.op === "read_local_storage" || inner.op === "read_session_storage") && inner.values) {
+        if ((inner.op === "read_local_storage" || inner.op === "read_session_storage" || inner.op === "read_dom") && inner.values) {
           storageCb.resolve({ ...inner.values });
         } else {
           storageCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on storage awaiter`));
@@ -38243,53 +38402,10 @@ async function loginWithPassword(username, password) {
   };
 }
 
-// src/config.ts
-import { createHash } from "node:crypto";
-import { homedir as homedir3 } from "node:os";
-import { join as join3 } from "node:path";
-function readCacheIdentity() {
-  const explicit = process.env.OFW_CACHE_IDENTITY;
-  if (typeof explicit === "string" && explicit.trim().length > 0) return explicit.trim();
-  const username = process.env.OFW_USERNAME;
-  if (typeof username === "string" && username.trim().length > 0) return username.trim();
-  return "_default";
-}
-function getCacheDir() {
-  const override = process.env.OFW_CACHE_DIR;
-  if (override && override.trim().length > 0) return override.trim();
-  return join3(homedir3(), ".cache", "ofw-mcp");
-}
-function getCacheDbPath() {
-  const identity = readCacheIdentity();
-  const hash2 = createHash("sha256").update(identity).digest("hex").slice(0, 16);
-  return join3(getCacheDir(), `${hash2}.db`);
-}
-function getAttachmentsDir() {
-  const override = process.env.OFW_ATTACHMENTS_DIR;
-  if (override && override.trim().length > 0) return override.trim();
-  return join3(homedir3(), "Downloads", "ofw-mcp");
-}
-function parseBoolEnv2(name) {
-  return parseBoolEnv(name);
-}
-function getWriteMode() {
-  const raw = process.env.OFW_WRITE_MODE;
-  if (typeof raw !== "string" || raw.trim().length === 0) return "all";
-  const mode = raw.trim().toLowerCase();
-  if (mode === "none" || mode === "drafts" || mode === "all") return mode;
-  console.error(
-    `[ofw-mcp] Unrecognized OFW_WRITE_MODE "${raw.trim()}" \u2014 failing closed to "none" (no write tools registered). Valid values: none, drafts, all.`
-  );
-  return "none";
-}
-function getDefaultInlineAttachments() {
-  return parseBoolEnv2("OFW_INLINE_ATTACHMENTS");
-}
-
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.4.3",
+  version: "2.5.0",
   license: "MIT",
   mcpName: "io.github.chrischall/ofw-mcp",
   description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
@@ -38321,31 +38437,28 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.10.3",
+    "@chrischall/mcp-utils": "^0.13.0",
     "@fetchproxy/bootstrap": "^1.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     dotenv: "^17.4.2",
     zod: "^4.4.3"
   },
   devDependencies: {
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     esbuild: "^0.28.0",
-    typescript: "^6.0.3",
+    typescript: "^7.0.2",
     vitest: "^4.1.7"
   }
 };
 
 // src/auth.ts
-function readEnv(key) {
-  return readEnvVar(key);
-}
 function fetchproxyDisabled() {
-  return parseBoolEnv2("OFW_DISABLE_FETCHPROXY");
+  return parseBoolEnv("OFW_DISABLE_FETCHPROXY");
 }
 async function resolveAuth() {
-  const username = readEnv("OFW_USERNAME");
-  const password = readEnv("OFW_PASSWORD");
+  const username = readEnvVar("OFW_USERNAME");
+  const password = readEnvVar("OFW_PASSWORD");
   if (username && password) {
     const { token, expiresAt } = await loginWithPassword(username, password);
     return { token, expiresAt, source: "env" };
@@ -38402,7 +38515,7 @@ async function resolveAuth() {
 
 // src/client.ts
 var __dirname = dirname(fileURLToPath(import.meta.url));
-await loadDotenvSafely({ path: join4(__dirname, "..", ".env") });
+await loadDotenvSafely({ path: join3(__dirname, "..", ".env") });
 function parseContentDispositionFilename(cd) {
   const extMatch = /filename\*=(?:UTF-8'')?([^;]+)/i.exec(cd);
   if (extMatch) {
@@ -38417,12 +38530,7 @@ function parseContentDispositionFilename(cd) {
   return m ? m[1] : null;
 }
 function debugLogEnabled() {
-  return parseBoolEnv2("OFW_DEBUG_LOG");
-}
-function redactHeaders(h) {
-  const out = { ...h };
-  if (out.Authorization) out.Authorization = `Bearer ${out.Authorization.slice(7, 17)}\u2026`;
-  return out;
+  return parseBoolEnv("OFW_DEBUG_LOG");
 }
 var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
 function getRequestTimeoutMs() {
@@ -38517,7 +38625,7 @@ var OFWClient = class {
     if (debugLogEnabled()) {
       const bodyPreview = body === void 0 ? "<none>" : isFormData ? `<FormData entries=${Array.from(body.keys()).join(",")}>` : JSON.stringify(body);
       console.error(`[ofw-debug] \u2192 ${method} ${url2}${isRetry ? " (retry)" : ""}`);
-      console.error(`[ofw-debug]   headers: ${JSON.stringify(redactHeaders(headers))}`);
+      console.error(`[ofw-debug]   headers: ${redactSecrets(JSON.stringify(headers))}`);
       console.error(`[ofw-debug]   body: ${bodyPreview}`);
     }
     const timeoutMs = getRequestTimeoutMs();
@@ -38557,17 +38665,6 @@ var OFWClient = class {
 };
 var client = new OFWClient();
 
-// src/validate.ts
-function parseOFW(schema, raw, ctx, mode = "lenient") {
-  const result = schema.safeParse(raw);
-  if (result.success) return result.data;
-  const issues = result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
-  const message = `OFW response for ${ctx} failed validation: ${issues}`;
-  if (mode === "strict") throw new Error(message);
-  console.error(`[ofw-mcp] WARNING: ${message} \u2014 continuing with the raw response; fields derived from it may be missing or wrong.`);
-  return raw;
-}
-
 // src/tools/_shared.ts
 var jsonResponse = textResult;
 var textResponse = rawTextResult;
@@ -38576,11 +38673,14 @@ var ApiRecipientSchema = external_exports.looseObject({
   viewed: external_exports.looseObject({ dateTime: external_exports.string() }).nullable().optional()
 });
 function mapRecipients(items) {
-  return (items ?? []).map((r) => ({
-    userId: r.user?.id ?? 0,
-    name: r.user?.name ?? "",
-    viewedAt: r.viewed?.dateTime ?? null
-  }));
+  return (items ?? []).map((r) => {
+    const dt = r.viewed?.dateTime;
+    const viewedAt = typeof dt === "string" && !dt.startsWith("1970-01-01") ? dt : null;
+    return { userId: r.user?.id ?? 0, name: r.user?.name ?? "", viewedAt };
+  });
+}
+function hasRealView(recipients) {
+  return recipients.some((r) => r.viewedAt !== null && !r.viewedAt.startsWith("1970-01-01"));
 }
 var expandPath2 = expandPath;
 function verifyWriteLanded(kind, sent, persisted) {
@@ -38599,19 +38699,17 @@ var PostMessagesResponseSchema = external_exports.looseObject({
   entityId: external_exports.number().optional()
 }).nullable();
 async function postMessageAndRefetch(client2, payload, detailSchema, ctx) {
-  const raw = parseOFW(
+  const raw = parseLenient(
     PostMessagesResponseSchema,
     await client2.request("POST", "/pub/v3/messages", payload),
-    `POST /pub/v3/messages (${ctx})`,
-    "strict"
+    { label: "ofw-mcp", context: `POST /pub/v3/messages (${ctx})`, mode: "strict" }
   );
   const id = typeof raw?.id === "number" ? raw.id : typeof raw?.entityId === "number" ? raw.entityId : null;
   if (id === null) return { id: null, detail: null, raw };
-  const detail = parseOFW(
+  const detail = parseLenient(
     detailSchema,
     await client2.request("GET", `/pub/v3/messages/${id}`),
-    `GET /pub/v3/messages/{id} (${ctx})`,
-    "strict"
+    { label: "ofw-mcp", context: `GET /pub/v3/messages/{id} (${ctx})`, mode: "strict" }
   );
   return { id, detail, raw };
 }
@@ -38638,6 +38736,49 @@ function registerUserTools(server, client2) {
 import { DatabaseSync } from "node:sqlite";
 import { mkdirSync, chmodSync, existsSync } from "node:fs";
 import { dirname as dirname2 } from "node:path";
+
+// src/config.ts
+import { createHash } from "node:crypto";
+import { homedir as homedir3 } from "node:os";
+import { join as join4 } from "node:path";
+function readCacheIdentity() {
+  return readEnvVar("OFW_CACHE_IDENTITY") ?? readEnvVar("OFW_USERNAME") ?? "_default";
+}
+function getCacheDir() {
+  const override = process.env.OFW_CACHE_DIR;
+  if (override && override.trim().length > 0) return override.trim();
+  return join4(homedir3(), ".cache", "ofw-mcp");
+}
+function getCacheDbPath() {
+  const identity = readCacheIdentity();
+  const hash2 = createHash("sha256").update(identity).digest("hex").slice(0, 16);
+  return join4(getCacheDir(), `${hash2}.db`);
+}
+function getAttachmentsDir() {
+  const override = process.env.OFW_ATTACHMENTS_DIR;
+  if (override && override.trim().length > 0) return override.trim();
+  return join4(homedir3(), "Downloads", "ofw-mcp");
+}
+function getWriteMode() {
+  const raw = process.env.OFW_WRITE_MODE;
+  if (typeof raw !== "string" || raw.trim().length === 0) return "all";
+  const mode = raw.trim().toLowerCase();
+  if (mode === "none" || mode === "drafts" || mode === "all") return mode;
+  console.error(
+    `[ofw-mcp] Unrecognized OFW_WRITE_MODE "${raw.trim()}" \u2014 failing closed to "none" (no write tools registered). Valid values: none, drafts, all.`
+  );
+  return "none";
+}
+function getCalendarWritesAllowed() {
+  const mode = getWriteMode();
+  if (mode === "all") return true;
+  return mode === "drafts" && parseBoolEnv("OFW_CALENDAR_WRITES");
+}
+function getDefaultInlineAttachments() {
+  return parseBoolEnv("OFW_INLINE_ATTACHMENTS");
+}
+
+// src/cache.ts
 var instance = null;
 var SCHEMA_V1 = `
 CREATE TABLE IF NOT EXISTS messages (
@@ -38990,10 +39131,10 @@ var FileMetaSchema = external_exports.looseObject({
   fileSize: external_exports.number().optional()
 });
 async function fetchAttachmentMeta(client2, fileId, messageId) {
-  const meta3 = parseOFW(
+  const meta3 = parseLenient(
     FileMetaSchema,
     await client2.request("GET", `/pub/v1/myfiles/${fileId}`),
-    "GET /pub/v1/myfiles/{fileId}"
+    { label: "ofw-mcp", context: "GET /pub/v1/myfiles/{fileId}" }
   );
   upsertAttachmentForMessage({
     fileId: meta3.fileId ?? fileId,
@@ -39012,10 +39153,10 @@ var FoldersSchema = external_exports.looseObject({
   systemFolders: external_exports.array(external_exports.looseObject({ id: external_exports.string(), folderType: external_exports.string() })).optional()
 });
 async function resolveFolderIds(client2) {
-  const data = parseOFW(
+  const data = parseLenient(
     FoldersSchema,
     await client2.request("GET", "/pub/v1/messageFolders?includeFolderCounts=true"),
-    "GET /pub/v1/messageFolders"
+    { label: "ofw-mcp", context: "GET /pub/v1/messageFolders" }
   );
   const sys = data.systemFolders ?? [];
   const find = (type) => {
@@ -39042,7 +39183,10 @@ var ListItemSchema = external_exports.looseObject({
 var ListResponseSchema = external_exports.looseObject({ data: external_exports.array(ListItemSchema).optional() });
 var DetailResponseSchema = external_exports.looseObject({
   body: external_exports.string().optional(),
-  files: external_exports.array(external_exports.number()).optional()
+  files: external_exports.array(external_exports.number()).optional(),
+  // The detail endpoint carries the REAL recipient view timestamps (the list
+  // endpoint only has an epoch placeholder) — used by the view-status refresh.
+  recipients: external_exports.array(ApiRecipientSchema).optional()
 });
 async function syncMessageFolder(client2, folder, folderId, opts) {
   let page = 1;
@@ -39051,10 +39195,10 @@ async function syncMessageFolder(client2, folder, folderId, opts) {
   const unread = [];
   while (true) {
     const path = `/pub/v3/messages?folders=${encodeURIComponent(folderId)}&page=${page}&size=50&sort=date&sortDirection=desc`;
-    const list = parseOFW(
+    const list = parseLenient(
       ListResponseSchema,
       await client2.request("GET", path),
-      `GET /pub/v3/messages?folders={${folder}}`
+      { label: "ofw-mcp", context: `GET /pub/v3/messages?folders={${folder}}` }
     );
     const items = list.data ?? [];
     if (items.length === 0) break;
@@ -39062,7 +39206,18 @@ async function syncMessageFolder(client2, folder, folderId, opts) {
     for (const item of items) {
       if (newestId === null || item.id > newestId) newestId = item.id;
       const existing = getMessage(item.id);
-      if (existing) continue;
+      if (existing) {
+        if (folder === "sent" && item.showNeverViewed === false && !hasRealView(existing.recipients)) {
+          const detail = parseLenient(
+            DetailResponseSchema,
+            await client2.request("GET", `/pub/v3/messages/${item.id}`),
+            { label: "ofw-mcp", context: "GET /pub/v3/messages/{id} (view-status refresh)" }
+          );
+          upsertMessage({ ...existing, recipients: mapRecipients(detail.recipients), listData: item });
+          synced++;
+        }
+        continue;
+      }
       pageHadNewItem = true;
       const isInboxUnread = folder === "inbox" && item.showNeverViewed === true;
       const shouldFetchBody = !isInboxUnread || opts.fetchUnreadBodies;
@@ -39070,10 +39225,10 @@ async function syncMessageFolder(client2, folder, folderId, opts) {
       let fetchedBodyAt = null;
       let detailFileIds = [];
       if (shouldFetchBody) {
-        const detail = parseOFW(
+        const detail = parseLenient(
           DetailResponseSchema,
           await client2.request("GET", `/pub/v3/messages/${item.id}`),
-          "GET /pub/v3/messages/{id} (sync)"
+          { label: "ofw-mcp", context: "GET /pub/v3/messages/{id} (sync)" }
         );
         body = detail.body ?? "";
         fetchedBodyAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -39133,10 +39288,10 @@ async function syncDrafts(client2, draftsFolderId) {
   let page = 1;
   while (true) {
     const path = `/pub/v3/messages?folders=${encodeURIComponent(draftsFolderId)}&page=${page}&size=50&sort=date&sortDirection=desc`;
-    const list = parseOFW(
+    const list = parseLenient(
       DraftListResponseSchema,
       await client2.request("GET", path),
-      "GET /pub/v3/messages?folders={drafts}"
+      { label: "ofw-mcp", context: "GET /pub/v3/messages?folders={drafts}" }
     );
     const pageItems = list.data ?? [];
     items.push(...pageItems);
@@ -39149,10 +39304,10 @@ async function syncDrafts(client2, draftsFolderId) {
     seenIds.add(item.id);
     const modifiedAt = item.date?.dateTime ?? (/* @__PURE__ */ new Date()).toISOString();
     const existing = getDraft(item.id);
-    const detail = parseOFW(
+    const detail = parseLenient(
       DraftDetailSchema,
       await client2.request("GET", `/pub/v3/messages/${item.id}`),
-      "GET /pub/v3/messages/{id} (drafts sync)"
+      { label: "ofw-mcp", context: "GET /pub/v3/messages/{id} (drafts sync)" }
     );
     const row = {
       id: item.id,
@@ -39349,13 +39504,31 @@ function registerMessageTools(server, client2) {
     }
     const cached2 = getMessage(id);
     if (cached2 && cached2.body !== null) {
+      let row2 = cached2;
+      if (cached2.folder === "sent" && !hasRealView(cached2.recipients)) {
+        try {
+          const detail2 = parseLenient(
+            MessageDetailSchema,
+            await client2.request("GET", `/pub/v3/messages/${id}`),
+            { label: "ofw-mcp", context: "GET /pub/v3/messages/{id} (view-status refresh)" }
+          );
+          const recipients = mapRecipients(detail2.recipients);
+          row2 = {
+            ...cached2,
+            recipients,
+            listData: { ...cached2.listData, showNeverViewed: !hasRealView(recipients) }
+          };
+          upsertMessage(row2);
+        } catch {
+        }
+      }
       let attachments2 = listAttachmentsForMessage(id);
-      if (attachments2.length === 0 && listDataHintsAtFiles(cached2.listData)) {
+      if (attachments2.length === 0 && listDataHintsAtFiles(row2.listData)) {
         try {
-          const detail2 = parseOFW(
+          const detail2 = parseLenient(
             DetailFilesSchema,
             await client2.request("GET", `/pub/v3/messages/${id}`),
-            "GET /pub/v3/messages/{id} (attachment backfill)"
+            { label: "ofw-mcp", context: "GET /pub/v3/messages/{id} (attachment backfill)" }
           );
           if (Array.isArray(detail2.files) && detail2.files.length > 0) {
             await fetchAttachmentMetaForMessage(client2, id, detail2.files);
@@ -39364,12 +39537,12 @@ function registerMessageTools(server, client2) {
         } catch {
         }
       }
-      return jsonResponse({ ...cached2, attachments: attachments2 });
+      return jsonResponse({ ...row2, attachments: attachments2 });
     }
-    const detail = parseOFW(
+    const detail = parseLenient(
       MessageDetailSchema,
       await client2.request("GET", `/pub/v3/messages/${encodeURIComponent(args.messageId)}`),
-      "GET /pub/v3/messages/{id} (ofw_get_message)"
+      { label: "ofw-mcp", context: "GET /pub/v3/messages/{id} (ofw_get_message)" }
     );
     const folder = cached2?.folder ?? "inbox";
     const row = {
@@ -39651,11 +39824,10 @@ ${text}` : text);
     form.append("label", args.label ?? fileName);
     form.append("fileName", fileName);
     form.append("shareClass", args.shareClass ?? "PRIVATE");
-    const meta3 = parseOFW(
+    const meta3 = parseLenient(
       UploadedFileSchema,
       await client2.request("POST", "/pub/v3/myfiles/multipart", form),
-      "POST /pub/v3/myfiles/multipart (ofw_upload_attachment)",
-      "strict"
+      { label: "ofw-mcp", context: "POST /pub/v3/myfiles/multipart (ofw_upload_attachment)", mode: "strict" }
     );
     upsertAttachmentForMessage({
       fileId: meta3.fileId,
@@ -39727,12 +39899,13 @@ ${text}` : text);
       } }] };
     }
     let dest;
+    const safeName = basename(cached2.fileName);
     if (args.saveTo) {
       const isDirArg = args.saveTo.endsWith("/") || args.saveTo.endsWith("\\");
       const abs = expandPath2(args.saveTo);
-      dest = isDirArg ? join5(abs, `${fileId}-${cached2.fileName}`) : abs;
+      dest = isDirArg ? join5(abs, `${fileId}-${safeName}`) : abs;
     } else {
-      dest = join5(getAttachmentsDir(), `${fileId}-${cached2.fileName}`);
+      dest = join5(getAttachmentsDir(), `${fileId}-${safeName}`);
     }
     if (!args.force && cached2.downloadedPath === dest) {
       return jsonResponse({
@@ -39780,8 +39953,87 @@ async function deleteOFWMessages(client2, ids) {
 }
 
 // src/tools/calendar.ts
+var ofwDate = external_exports.looseObject({ dateTime: external_exports.string() });
+var userRef = external_exports.looseObject({ userId: external_exports.number() });
+var eventDetailSchema = external_exports.looseObject({
+  eventRecurrenceId: external_exports.number(),
+  title: external_exports.string(),
+  allDay: external_exports.boolean(),
+  publicFlag: external_exports.boolean(),
+  startDate: ofwDate,
+  endDate: ofwDate,
+  location: external_exports.string().nullish(),
+  notes: external_exports.string().nullish(),
+  reminderMinutes: external_exports.number().nullish(),
+  children: external_exports.array(userRef).nullish(),
+  eventParent: userRef.nullish(),
+  dropOffParent: userRef.nullish(),
+  pickUpParent: userRef.nullish()
+});
+var eventWriteFields = {
+  startDate: external_exports.string().describe("Start date YYYY-MM-DD"),
+  endDate: external_exports.string().describe("End date YYYY-MM-DD (default: startDate)").optional(),
+  startTime: external_exports.string().describe("Start time HH:mm, 24-hour (required unless allDay)").optional(),
+  endTime: external_exports.string().describe("End time HH:mm, 24-hour (required unless allDay)").optional(),
+  allDay: external_exports.boolean().optional(),
+  privateEvent: external_exports.boolean().describe("true = visible only to you; default false = shared with co-parent").optional(),
+  location: external_exports.string().optional(),
+  notes: external_exports.string().optional(),
+  reminderMinutes: external_exports.number().int().min(0).optional(),
+  children: external_exports.array(external_exports.number()).describe("Child userIds to tag (see ofw_get_profile)").optional(),
+  eventParentId: external_exports.number().describe("userId of the parent the event is 'for'").optional(),
+  dropOffParentId: external_exports.number().describe("userId of the drop-off parent").optional(),
+  pickUpParentId: external_exports.number().describe("userId of the pick-up parent").optional()
+};
+function buildEventPayload(a) {
+  const allDay = a.allDay ?? false;
+  if (!allDay && (!a.startTime || !a.endTime)) {
+    throw new Error("startTime and endTime (HH:mm) are required unless allDay is true");
+  }
+  const payload = {
+    title: a.title,
+    startDate: a.startDate,
+    endDate: a.endDate ?? a.startDate,
+    // The web form always sends times; for all-day events it uses 01:00/02:00
+    // placeholders that OFW ignores.
+    startTime: a.startTime ?? "01:00",
+    endTime: a.endTime ?? "02:00",
+    allDay,
+    publicFlag: !(a.privateEvent ?? false)
+  };
+  if (a.location) payload.location = a.location;
+  if (a.notes) payload.notes = a.notes;
+  if (a.reminderMinutes !== void 0) payload.reminderMinutes = String(a.reminderMinutes);
+  if (a.children !== void 0) payload.children = a.children;
+  if (a.eventParentId !== void 0) payload.eventParentId = String(a.eventParentId);
+  if (a.dropOffParentId !== void 0) payload.dropOffParentId = String(a.dropOffParentId);
+  if (a.pickUpParentId !== void 0) payload.pickUpParentId = String(a.pickUpParentId);
+  return payload;
+}
+function detailToWriteArgs(d) {
+  const [startDate, startClock] = d.startDate.dateTime.split("T");
+  const [endDate, endClock] = d.endDate.dateTime.split("T");
+  return {
+    title: d.title,
+    startDate,
+    endDate,
+    startTime: (startClock ?? "01:00:00").slice(0, 5),
+    endTime: (endClock ?? "02:00:00").slice(0, 5),
+    allDay: d.allDay,
+    privateEvent: !d.publicFlag,
+    location: d.location ?? void 0,
+    notes: d.notes ?? void 0,
+    reminderMinutes: d.reminderMinutes ?? void 0,
+    // Untagged (nullish or empty) → undefined, so the merged PUT omits the
+    // field (omission preserves; only a CALLER-supplied [] should clear).
+    children: d.children?.length ? d.children.map((c) => c.userId) : void 0,
+    eventParentId: d.eventParent?.userId,
+    dropOffParentId: d.dropOffParent?.userId,
+    pickUpParentId: d.pickUpParent?.userId
+  };
+}
 function registerCalendarTools(server, client2) {
-  const allowWrites = getWriteMode() === "all";
+  const allowWrites = getCalendarWritesAllowed();
   server.registerTool("ofw_list_events", {
     description: "List OurFamilyWizard calendar events in a date range",
     annotations: { readOnlyHint: true },
@@ -39799,51 +40051,62 @@ function registerCalendarTools(server, client2) {
     return jsonResponse(data);
   });
   if (allowWrites) server.registerTool("ofw_create_event", {
-    description: "Create a calendar event in OurFamilyWizard",
+    description: "Create a calendar event in OurFamilyWizard. Unless privateEvent is true, the event is immediately visible to the co-parent \u2014 there is no draft stage.",
     annotations: { destructiveHint: false },
     inputSchema: {
       title: external_exports.string(),
-      startDate: external_exports.string().describe("ISO datetime string"),
-      endDate: external_exports.string().describe("ISO datetime string"),
-      allDay: external_exports.boolean().optional(),
-      location: external_exports.string().optional(),
-      reminder: external_exports.string().describe('Reminder setting (e.g. "1 hour before")').optional(),
-      privateEvent: external_exports.boolean().optional(),
-      eventFor: external_exports.string().describe("neither | parent1 | parent2").optional(),
-      dropOffParent: external_exports.string().optional(),
-      pickUpParent: external_exports.string().optional(),
-      children: external_exports.array(external_exports.number()).describe("Array of child IDs").optional()
+      ...eventWriteFields
     }
   }, async (args) => {
-    const data = await client2.request("POST", "/pub/v1/calendar/events", args);
-    return jsonResponse(data);
+    const raw = await client2.request("POST", "/pub/v3/events", buildEventPayload(args));
+    const event = parseLenient(eventDetailSchema, raw, { label: "ofw-mcp", context: "POST /pub/v3/events", mode: "strict" });
+    return jsonResponse({
+      note: `Event created. Use eventRecurrenceId ${event.eventRecurrenceId} as eventId for ofw_update_event/ofw_delete_event.`,
+      event
+    });
   });
   if (allowWrites) server.registerTool("ofw_update_event", {
-    description: "Update an existing OurFamilyWizard calendar event",
+    description: "Update an existing OurFamilyWizard calendar event. Fetches the event, applies the given changes, and writes the merged result back (OFW has no partial update).",
     annotations: { destructiveHint: true },
     inputSchema: {
-      eventId: external_exports.string(),
+      eventId: external_exports.string().describe("Event id \u2014 the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event"),
       title: external_exports.string().optional(),
-      startDate: external_exports.string().optional(),
-      endDate: external_exports.string().optional(),
-      allDay: external_exports.boolean().optional(),
-      location: external_exports.string().optional(),
-      reminder: external_exports.string().optional(),
-      privateEvent: external_exports.boolean().optional()
+      startDate: eventWriteFields.startDate.optional(),
+      endDate: eventWriteFields.endDate,
+      startTime: eventWriteFields.startTime,
+      endTime: eventWriteFields.endTime,
+      allDay: eventWriteFields.allDay,
+      privateEvent: eventWriteFields.privateEvent,
+      location: eventWriteFields.location,
+      notes: eventWriteFields.notes,
+      reminderMinutes: eventWriteFields.reminderMinutes,
+      children: external_exports.array(external_exports.number()).describe("Child userIds to tag; pass [] to remove all child tags (omit to keep current tags)").optional(),
+      eventParentId: eventWriteFields.eventParentId,
+      dropOffParentId: eventWriteFields.dropOffParentId,
+      pickUpParentId: eventWriteFields.pickUpParentId
     }
   }, async (args) => {
-    const { eventId, ...updateData } = args;
-    const data = await client2.request("PUT", `/pub/v1/calendar/events/${encodeURIComponent(eventId)}`, updateData);
-    return jsonResponse(data);
+    const { eventId, ...changes } = args;
+    const id = encodeURIComponent(eventId);
+    const rawDetail = await client2.request("GET", `/pub/v3/events/${id}`);
+    const current = parseLenient(eventDetailSchema, rawDetail, { label: "ofw-mcp", context: `GET /pub/v3/events/${eventId}`, mode: "strict" });
+    const defined = Object.fromEntries(Object.entries(changes).filter(([, v]) => v !== void 0));
+    const merged = { ...detailToWriteArgs(current), ...defined };
+    await client2.request("PUT", `/pub/v3/events/${id}`, buildEventPayload(merged));
+    const rawAfter = await client2.request("GET", `/pub/v3/events/${id}`);
+    const event = parseLenient(eventDetailSchema, rawAfter, { label: "ofw-mcp", context: `GET /pub/v3/events/${eventId} (post-update)`, mode: "strict" });
+    return jsonResponse({ note: "Event updated; returning re-fetched event state.", event });
   });
   if (allowWrites) server.registerTool("ofw_delete_event", {
     description: "Delete an OurFamilyWizard calendar event",
     annotations: { destructiveHint: true },
     inputSchema: {
-      eventId: external_exports.string().describe("Event ID to delete")
+      eventId: external_exports.string().describe("Event id \u2014 the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event"),
+      includeFuture: external_exports.boolean().describe("For repeating events: also delete future occurrences (default false)").optional()
     }
   }, async (args) => {
-    await client2.request("DELETE", `/pub/v1/calendar/events/${encodeURIComponent(args.eventId)}`);
+    const includeFuture = args.includeFuture ?? false;
+    await client2.request("DELETE", `/pub/v3/events/${encodeURIComponent(args.eventId)}?includeFuture=${includeFuture}`);
     return textResponse(`Event ${args.eventId} deleted`);
   });
 }
@@ -39926,7 +40189,7 @@ process.emit = function(event, ...args) {
 };
 await runMcp({
   name: "ofw",
-  version: "2.4.3",
+  version: "2.5.0",
   // x-release-please-version
   deps: client,
   tools: [