ofw-mcp 2.12.0 → 2.14.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "OurFamilyWizard tools for Claude Code",
-    "version": "2.12.0"
+    "version": "2.14.0"
   },
   "plugins": [
     {
@@ -14,7 +14,7 @@
       "displayName": "OurFamilyWizard",
       "source": "./",
       "description": "OurFamilyWizard co-parenting tools for Claude — messages, calendar, expenses, and journal via MCP",
-      "version": "2.12.0",
+      "version": "2.14.0",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ofw",
   "displayName": "OurFamilyWizard",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "description": "OurFamilyWizard co-parenting tools for Claude — messages, calendar, expenses, and journal via MCP",
   "author": {
     "name": "Chris Chall"

package/dist/auth.js

@@ -69,6 +69,38 @@ function fetchproxyDisabled() {
  * return value as opaque credentials — they should not branch on `source`.
  * The field exists for logging / future cache-keying only.
  */
+/**
+ * The message raised when NEITHER auth path is configured.
+ *
+ * Exported with {@link isNoAuthConfigured} because a second reader needs to
+ * tell this case apart from every other auth failure: "nothing is set up" and
+ * "the password was rejected" or "the bridge is down" need opposite advice, and
+ * `ofw_healthcheck` gives the wrong one if it confuses them. A prefix match on
+ * a copy of this string in the other module would pass its own test while
+ * silently stopping matching the day this wording changed.
+ */
+export const NO_AUTH_CONFIGURED = 'OFW auth: set OFW_USERNAME + OFW_PASSWORD, ' +
+    'or install the fetchproxy extension and sign into ourfamilywizard.com ' +
+    '(unset OFW_DISABLE_FETCHPROXY if it is set).';
+/**
+ * Prefix of the message raised when the fetchproxy bridge is unreachable.
+ *
+ * A PREFIX rather than a whole constant because the upstream `.hint` — the
+ * actionable "click the toolbar icon" copy — is appended per failure. Exported
+ * with {@link isBridgeDown} for the reason {@link NO_AUTH_CONFIGURED} is: a
+ * reader that matched a copy of this text would keep its own test green on the
+ * day the wording changed, while silently misreporting a downed bridge as an
+ * unconfigured server.
+ */
+export const BRIDGE_DOWN_PREFIX = 'OFW auth: fetchproxy bridge is down';
+/** True for the {@link BRIDGE_DOWN_PREFIX} failure and nothing else. */
+export function isBridgeDown(e) {
+    return e instanceof Error && e.message.startsWith(BRIDGE_DOWN_PREFIX);
+}
+/** True for the {@link NO_AUTH_CONFIGURED} failure and nothing else. */
+export function isNoAuthConfigured(e) {
+    return e instanceof Error && e.message === NO_AUTH_CONFIGURED;
+}
 export async function resolveAuth() {
     // Which paths are CONFIGURED. `resolveAuthPattern` runs the first one
     // provided, in the fleet's fixed priority order (token → oauth →
@@ -125,7 +157,7 @@ export async function resolveAuth() {
                 // FetchproxyBridgeDownError only escapes bootstrap() after the lazy-revive retry fails — surface .hint verbatim (actionable "click toolbar icon" copy).
                 if (classifyBridgeError(e) === 'bridge_down') {
                     const downErr = e;
-                    throw new Error(`OFW auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`);
+                    throw new Error(`${BRIDGE_DOWN_PREFIX} (extension service worker unreachable after retry). ${downErr.hint}`);
                 }
                 const msg = e instanceof Error ? e.message : String(e);
                 throw new Error(`OFW auth: no OFW_USERNAME/OFW_PASSWORD set, and fetchproxy fallback failed: ${msg}`);
@@ -137,9 +169,7 @@ export async function resolveAuth() {
     // because this one names OFW's own two fixes side-by-side and the generic
     // one cannot.
     if (!pattern.sessionScrape && !pattern.fetchproxy) {
-        throw new Error('OFW auth: set OFW_USERNAME + OFW_PASSWORD, ' +
-            'or install the fetchproxy extension and sign into ourfamilywizard.com ' +
-            '(unset OFW_DISABLE_FETCHPROXY if it is set).');
+        throw new Error(NO_AUTH_CONFIGURED);
     }
     // Errors from the winning path propagate UNWRAPPED, which is what keeps the
     // bridge-down `.hint` above intact.

package/dist/bundle.js

@@ -3314,8 +3314,8 @@ var require_utils = __commonJS({
     var HOST_DELIMS = { "@": "%40", "/": "%2F", "?": "%3F", "#": "%23", ":": "%3A" };
     var HOST_DELIM_RE = /[@/?#:]/g;
     var HOST_DELIM_NO_COLON_RE = /[@/?#]/g;
-    function reescapeHostDelimiters(host, isIP) {
-      const re = isIP ? HOST_DELIM_NO_COLON_RE : HOST_DELIM_RE;
+    function reescapeHostDelimiters(host, isIP2) {
+      const re = isIP2 ? HOST_DELIM_NO_COLON_RE : HOST_DELIM_RE;
       re.lastIndex = 0;
       return host.replace(re, (ch) => HOST_DELIMS[ch]);
     }
@@ -3804,7 +3804,7 @@ var require_fast_uri = __commonJS({
         fragment: void 0
       };
       let malformedAuthorityOrPort = false;
-      let isIP = false;
+      let isIP2 = false;
       if (options.reference === "suffix") {
         if (options.scheme) {
           uri = options.scheme + ":" + uri;
@@ -3853,9 +3853,9 @@ var require_fast_uri = __commonJS({
           if (ipv4result === false) {
             const ipv6result = normalizeIPv6(parsed.host);
             parsed.host = ipv6result.host.toLowerCase();
-            isIP = ipv6result.isIPV6;
+            isIP2 = ipv6result.isIPV6;
           } else {
-            isIP = true;
+            isIP2 = true;
           }
         }
         if (parsed.scheme === void 0 && parsed.userinfo === void 0 && parsed.host === void 0 && parsed.port === void 0 && parsed.query === void 0 && !parsed.path) {
@@ -3872,7 +3872,7 @@ var require_fast_uri = __commonJS({
         }
         const schemeHandler = getSchemeHandler(options.scheme || parsed.scheme);
         if (!options.unicodeSupport && (!schemeHandler || !schemeHandler.unicodeSupport)) {
-          if (parsed.host && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP === false && nonSimpleDomain(parsed.host)) {
+          if (parsed.host && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP2 === false && nonSimpleDomain(parsed.host)) {
             try {
               parsed.host = new URL("http://" + parsed.host).hostname;
             } catch (e) {
@@ -3886,7 +3886,7 @@ var require_fast_uri = __commonJS({
               parsed.scheme = unescape(parsed.scheme);
             }
             if (parsed.host !== void 0) {
-              parsed.host = reescapeHostDelimiters(unescape(parsed.host), isIP);
+              parsed.host = reescapeHostDelimiters(unescape(parsed.host), isIP2);
             }
           }
           if (parsed.path) {
@@ -7199,7 +7199,7 @@ var require_permessage_deflate = __commonJS({
       acceptAsServer(offers) {
         const opts = this._options;
         const accepted = offers.find((params) => {
-          if (opts.serverNoContextTakeover === false && params.server_no_context_takeover || params.server_max_window_bits && (opts.serverMaxWindowBits === false || typeof opts.serverMaxWindowBits === "number" && opts.serverMaxWindowBits > params.server_max_window_bits) || typeof opts.clientMaxWindowBits === "number" && !params.client_max_window_bits) {
+          if (opts.serverNoContextTakeover === false && params.server_no_context_takeover || params.server_max_window_bits && (opts.serverMaxWindowBits === false || typeof opts.serverMaxWindowBits === "number" && opts.serverMaxWindowBits > params.server_max_window_bits) || typeof opts.clientMaxWindowBits === "number" && (typeof params.client_max_window_bits === "number" ? opts.clientMaxWindowBits > params.client_max_window_bits : !params.client_max_window_bits)) {
             return false;
           }
           return true;
@@ -34678,6 +34678,7 @@ var StdioServerTransport = class {
 };
 
 // node_modules/@chrischall/mcp-utils/dist/errors/index.js
+var DEFAULT_ERROR_MESSAGE_MAX = 500;
 var McpToolError = class extends Error {
   /** Actionable remediation text, when one applies. */
   hint;
@@ -34719,6 +34720,18 @@ var JSON_SECRET_SQ_RE = new RegExp(`('(?:${JSON_SECRET_KEYS})'\\s*:\\s*')[^']*('
 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]");
 }
+function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX) {
+  const str = text === null || text === void 0 ? "" : String(text);
+  const redacted = redactSecrets(str);
+  if (redacted.length <= max)
+    return redacted;
+  return `${redacted.slice(0, max)}\u2026 [truncated]`;
+}
+function messageOf(err) {
+  if (err instanceof Error)
+    return err.message;
+  return String(err);
+}
 
 // node_modules/@chrischall/mcp-utils/dist/response/index.js
 function textResult(data) {
@@ -37331,6 +37344,7 @@ function classifyBridgeError(err) {
 }
 
 // node_modules/@fetchproxy/server/dist/ws-server.js
+import { isIP } from "node:net";
 function envWsPort() {
   const raw = process.env.FETCHPROXY_WS_PORT;
   if (raw === void 0 || raw.trim() === "")
@@ -37342,6 +37356,15 @@ function envWsPort() {
     return void 0;
   return port;
 }
+function envWsHost() {
+  const raw = process.env.FETCHPROXY_WS_HOST;
+  if (raw === void 0)
+    return void 0;
+  const host = raw.trim();
+  if (host === "" || isIP(host) === 0)
+    return void 0;
+  return host;
+}
 var FetchproxyProtocolError = class extends Error {
   constructor(message) {
     super(message);
@@ -37590,7 +37613,7 @@ var FetchproxyServer = class {
     }
     this.opts = {
       port: opts.port ?? envWsPort() ?? 37149,
-      host: opts.host ?? "127.0.0.1",
+      host: opts.host ?? envWsHost() ?? "127.0.0.1",
       serverName: opts.serverName,
       version: opts.version,
       domains: [...opts.domains],
@@ -37876,6 +37899,7 @@ var FetchproxyServer = class {
     return {
       role: this.role,
       port: this.opts.port,
+      host: this.opts.host,
       serverVersion: this.opts.version,
       fetchTimeoutMs: this.opts.fetchTimeoutMs ?? 0,
       bridgeReviveDelayMs: this.opts.bridgeReviveDelayMs ?? 0,
@@ -39366,6 +39390,144 @@ var BootstrapDisabledError = class extends Error {
   }
 };
 
+// node_modules/@chrischall/mcp-utils/dist/healthcheck/index.js
+function statusOf(err) {
+  if (typeof err !== "object" || err === null)
+    return void 0;
+  const s = err.status ?? err.statusCode;
+  return typeof s === "number" ? s : void 0;
+}
+var CREDENTIAL_ARMS = /* @__PURE__ */ new Set([
+  "ok",
+  "no_credential",
+  "credential_rejected",
+  "timeout",
+  "http",
+  "transport",
+  "unknown"
+]);
+function isArm(kind) {
+  return kind !== void 0 && CREDENTIAL_ARMS.has(kind);
+}
+function credentialHint(arm, prefix, hostLabel, source) {
+  switch (arm) {
+    case "ok":
+      return `Credential from '${source}' works: ${hostLabel} accepted an authenticated request. If a real tool still fails, the problem is that tool, not auth.`;
+    case "no_credential":
+      return `No credential resolved. Nothing was available to authenticate with \u2014 sign in and reconnect the connector so ${prefix} receives a token, or set the documented environment variable.`;
+    case "credential_rejected":
+      return `${hostLabel} rejected the credential from '${source}'. It is present but no longer valid \u2014 most often expired or revoked upstream. Re-authenticate and reconnect; retrying will not fix it.`;
+    case "timeout":
+      return `The credential from '${source}' resolved, but ${hostLabel} did not answer in time. Usually transient \u2014 retry. If it persists, ${hostLabel} is slow or unreachable from here.`;
+    case "http":
+      return `${hostLabel} answered with an error status that is not an auth rejection. That is USUALLY a ${hostLabel}-side problem rather than an auth one \u2014 but a 404 here more often means the probe path is wrong than that ${hostLabel} is broken, so check error.message and probe.url before concluding anything about the credential.`;
+    case "transport":
+      return `Could not reach ${hostLabel} at all. Check network egress; the credential itself was never judged.`;
+    default:
+      return `Unexpected failure \u2014 see error.message.`;
+  }
+}
+function registerCredentialHealthcheckTool(args) {
+  const { server, prefix, hostLabel, probePath, resolveCredential, probeFn, classifyThrown, hints } = args;
+  const probeUrl = probePath ? `https://${hostLabel}${probePath}` : void 0;
+  server.registerTool(`${prefix}_healthcheck`, {
+    title: "Verify credentials and upstream reachability",
+    description: `Resolves the credential the way real tools do, then makes one authenticated request to ${hostLabel}. Reports which source supplied the credential, whether ${hostLabel} accepted it, the round-trip time, and a plain-English hint distinguishing 'no credential' from 'credential rejected' from 'a ${hostLabel}-side problem'. Call this when a real tool fails and you want to know which hop broke. Read-only; never returns the credential itself.`,
+    annotations: {
+      title: "Verify credentials and upstream reachability",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: {}
+  }, async () => {
+    let probeStarted = 0;
+    let state;
+    try {
+      state = await resolveCredential();
+    } catch (e) {
+      const classified = classifyThrown?.(e);
+      const result2 = {
+        ok: false,
+        // Still false, and still no source: a classification explains WHY
+        // nothing resolved, it does not invent a credential that did.
+        credential: { source: null, resolved: false },
+        // No `url`: nothing was probed, and naming one implies it was tried.
+        probe: { elapsed_ms: 0 },
+        error: {
+          kind: classified?.kind ?? "no_credential",
+          message: truncateErrorMessage(messageOf(e)),
+          ...classified?.detail !== void 0 ? { detail: classified.detail } : {}
+        },
+        // The hint must follow the KIND beside it. Falling back to
+        // `no_credential`'s copy under a classified kind would state a cause
+        // the kind contradicts — the same disagreement this path exists to
+        // remove. So: an inline hint wins; else the classified arm's own
+        // copy (consumer override first); else, for a kind this module has
+        // no copy for, the neutral `unknown` text rather than one that
+        // asserts a cause; else the unclassified `no_credential` default.
+        hint: classified?.hint ?? (isArm(classified?.kind) ? hints?.[classified.kind] ?? credentialHint(classified.kind, prefix, hostLabel, null) : classified !== void 0 ? credentialHint("unknown", prefix, hostLabel, null) : hints?.no_credential ?? credentialHint("no_credential", prefix, hostLabel, null))
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+    }
+    const credential = {
+      source: state.source,
+      resolved: state.source !== null,
+      ...state.detail !== void 0 ? { detail: state.detail } : {}
+    };
+    if (!credential.resolved) {
+      const result2 = {
+        ok: false,
+        credential,
+        probe: { elapsed_ms: 0 },
+        error: { kind: "no_credential", message: "no credential source resolved" },
+        hint: hints?.no_credential ?? credentialHint("no_credential", prefix, hostLabel, null)
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+    }
+    let arm = "ok";
+    let error51;
+    let status;
+    let customHint;
+    probeStarted = Date.now();
+    try {
+      await probeFn();
+    } catch (e) {
+      status = statusOf(e);
+      const aborted2 = e instanceof Error && e.name === "AbortError";
+      arm = status === 401 || status === 403 ? "credential_rejected" : status !== void 0 ? "http" : aborted2 || /timeout|timed out|ETIMEDOUT/i.test(messageOf(e)) ? "timeout" : /fetch failed|ENOTFOUND|ECONNREFUSED|ECONNRESET|network/i.test(messageOf(e)) ? "transport" : "unknown";
+      let kind = arm;
+      let detail;
+      const custom2 = classifyThrown?.(e);
+      if (custom2) {
+        kind = custom2.kind;
+        customHint = custom2.hint;
+        detail = custom2.detail;
+      }
+      error51 = {
+        kind,
+        // Redacted AND bounded before it reaches the result: an upstream
+        // failure routinely quotes what it was sent, and a healthcheck is
+        // the tool people paste into a chat when something is broken.
+        message: truncateErrorMessage(messageOf(e)),
+        ...detail !== void 0 ? { detail } : {}
+      };
+    }
+    const result = {
+      ok: error51 === void 0,
+      credential,
+      probe: {
+        ...probeUrl ? { url: probeUrl } : {},
+        elapsed_ms: Date.now() - probeStarted,
+        ...status !== void 0 ? { status } : {}
+      },
+      ...error51 ? { error: error51 } : {},
+      hint: customHint ?? hints?.[arm] ?? credentialHint(arm, prefix, hostLabel, state.source)
+    };
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  });
+}
+
 // src/protocol.ts
 var BASE_URL = "https://ofw.ourfamilywizard.com";
 var OFW_PROTOCOL_HEADERS = {
@@ -39420,7 +39582,7 @@ async function loginWithPassword(username, password) {
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.12.0",
+  version: "2.14.0",
   license: "MIT",
   mcpName: "io.github.chrischall/ofw-mcp",
   description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
@@ -39454,8 +39616,8 @@ var package_default = {
     typecheck: "tsc -p tsconfig.json --noEmit"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.18.0",
-    "@fetchproxy/bootstrap": "^2.0.0",
+    "@chrischall/mcp-utils": "^0.19.3",
+    "@fetchproxy/bootstrap": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     dotenv: "^17.4.2",
     zod: "^4.4.3"
@@ -39473,6 +39635,14 @@ var package_default = {
 function fetchproxyDisabled() {
   return parseBoolEnv("OFW_DISABLE_FETCHPROXY");
 }
+var NO_AUTH_CONFIGURED = "OFW auth: set OFW_USERNAME + OFW_PASSWORD, or install the fetchproxy extension and sign into ourfamilywizard.com (unset OFW_DISABLE_FETCHPROXY if it is set).";
+var BRIDGE_DOWN_PREFIX = "OFW auth: fetchproxy bridge is down";
+function isBridgeDown(e) {
+  return e instanceof Error && e.message.startsWith(BRIDGE_DOWN_PREFIX);
+}
+function isNoAuthConfigured(e) {
+  return e instanceof Error && e.message === NO_AUTH_CONFIGURED;
+}
 async function resolveAuth() {
   const pattern = {};
   const username = readEnvVar("OFW_USERNAME");
@@ -39520,7 +39690,7 @@ async function resolveAuth() {
         if (classifyBridgeError(e) === "bridge_down") {
           const downErr = e;
           throw new Error(
-            `OFW auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`
+            `${BRIDGE_DOWN_PREFIX} (extension service worker unreachable after retry). ${downErr.hint}`
           );
         }
         const msg = e instanceof Error ? e.message : String(e);
@@ -39531,9 +39701,7 @@ async function resolveAuth() {
     };
   }
   if (!pattern.sessionScrape && !pattern.fetchproxy) {
-    throw new Error(
-      "OFW auth: set OFW_USERNAME + OFW_PASSWORD, or install the fetchproxy extension and sign into ourfamilywizard.com (unset OFW_DISABLE_FETCHPROXY if it is set)."
-    );
+    throw new Error(NO_AUTH_CONFIGURED);
   }
   const { credential, source, expiresAt } = await resolveAuthPattern(pattern);
   return {
@@ -40057,6 +40225,51 @@ function registerUserTools(server, client2) {
   });
 }
 
+// src/tools/healthcheck.ts
+function registerHealthcheckTools(server, client2, resolve3 = resolveAuth) {
+  registerCredentialHealthcheckTool({
+    server,
+    prefix: "ofw",
+    hostLabel: "ourfamilywizard.com",
+    // The same read `ofw_get_profile` makes: authenticated, cheap, and it
+    // changes nothing. A healthcheck that marked a message read would be
+    // co-parent-visible and irreversible.
+    probePath: "/pub/v2/profiles",
+    resolveCredential: async () => {
+      try {
+        const auth = await resolve3();
+        return {
+          source: auth.source,
+          // Never the token. Expiry is the fact that explains a connector
+          // that worked an hour ago and does not now.
+          detail: auth.expiresAt ? { expires_at: auth.expiresAt.toISOString() } : void 0
+        };
+      } catch (e) {
+        if (isNoAuthConfigured(e)) return { source: null };
+        throw e;
+      }
+    },
+    probeFn: () => client2.request("GET", "/pub/v2/profiles"),
+    // A downed bridge is not a missing credential, and since mcp-utils 0.19.3
+    // the helper consults this for a `resolveCredential` failure too — so it
+    // gets its own arm instead of the `no_credential` copy. That copy could
+    // previously only hedge across both cases and point at `error.message`;
+    // now each answer names one cause and one fix.
+    classifyThrown: (err) => isBridgeDown(err) ? {
+      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 not a credential problem: OFW_USERNAME/OFW_PASSWORD, if set, were not reached either. See error.message for the extension-specific fix."
+    } : void 0,
+    hints: {
+      // 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 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 \u2014 sign in again in the tab. Retrying will not fix either."
+    }
+  });
+}
+
 // src/sync.ts
 var FileMetaSchema = external_exports.looseObject({
   fileId: external_exports.number(),
@@ -44233,10 +44446,11 @@ var nodeCacheProvider = () => nodeCache ??= OFWCache.open(getCacheDbPath());
 var nodeAttachmentIO = new NodeAttachmentIO();
 await runMcp({
   name: "ofw",
-  version: "2.12.0",
+  version: "2.14.0",
   // x-release-please-version
   deps: client,
   tools: [
+    registerHealthcheckTools,
     registerUserTools,
     (server, deps) => registerMessageTools(server, deps, nodeCacheProvider, nodeAttachmentIO),
     registerCalendarTools,

package/dist/index.js

@@ -12,6 +12,7 @@ process.emit = function (event, ...args) {
 import { runMcp } from '@chrischall/mcp-utils';
 import { client } from './client.js';
 import { registerUserTools } from './tools/user.js';
+import { registerHealthcheckTools } from './tools/healthcheck.js';
 import { registerMessageTools } from './tools/messages.js';
 import { registerCalendarTools } from './tools/calendar.js';
 import { registerExpenseTools } from './tools/expenses.js';
@@ -35,9 +36,10 @@ const nodeAttachmentIO = new NodeAttachmentIO();
 // always succeeds before any credential check runs.
 await runMcp({
     name: 'ofw',
-    version: '2.12.0', // x-release-please-version
+    version: '2.14.0', // x-release-please-version
     deps: client,
     tools: [
+        registerHealthcheckTools,
         registerUserTools,
         (server, deps) => registerMessageTools(server, deps, nodeCacheProvider, nodeAttachmentIO),
         registerCalendarTools,

package/dist/tools/healthcheck.js

@@ -0,0 +1,81 @@
+import { registerCredentialHealthcheckTool } from '@chrischall/mcp-utils/healthcheck';
+import { resolveAuth, isNoAuthConfigured, isBridgeDown } from '../auth.js';
+/**
+ * `ofw_healthcheck` — the one call that answers "is this connector working?".
+ *
+ * OFW had no such tool. `ofw_status` looks like one and is not: it is a
+ * heavyweight draft-inventory call, `readOnlyHint: false`, that answers "where
+ * do my drafts stand?". Asking it whether auth works spends a drafts sync and
+ * still cannot separate "no credential" from "OFW rejected it".
+ *
+ * The distinction matters most for the two-path auth here: the token comes
+ * from either OFW_USERNAME/OFW_PASSWORD or a signed-in browser tab via
+ * fetchproxy, and "which of those actually supplied it" is the first thing
+ * anyone needs when the connector misbehaves. That is why `source` is
+ * reported.
+ */
+export function registerHealthcheckTools(server, client, 
+/** Seam: the auth resolver, injectable so tests need no network. */
+resolve = resolveAuth) {
+    registerCredentialHealthcheckTool({
+        server,
+        prefix: 'ofw',
+        hostLabel: 'ourfamilywizard.com',
+        // The same read `ofw_get_profile` makes: authenticated, cheap, and it
+        // changes nothing. A healthcheck that marked a message read would be
+        // co-parent-visible and irreversible.
+        probePath: '/pub/v2/profiles',
+        resolveCredential: async () => {
+            try {
+                const auth = await resolve();
+                return {
+                    source: auth.source,
+                    // Never the token. Expiry is the fact that explains a connector
+                    // that worked an hour ago and does not now.
+                    detail: auth.expiresAt ? { expires_at: auth.expiresAt.toISOString() } : undefined,
+                };
+            }
+            catch (e) {
+                // "Nothing is configured" is a CREDENTIAL state, not a failure to
+                // check — it earns the `no_credential` arm and its advice. Every
+                // other error (a rejected password, a bridge that is down) is a real
+                // failure and must keep its own message rather than being flattened
+                // into "no credential", which would send someone to set variables
+                // that are already set.
+                // `isNoAuthConfigured` rather than a prefix match on a copy of the
+                // message: the copy would pass this module's own test while silently
+                // stopping matching the day auth.ts reworded it, and the failure mode
+                // is giving a rejected password the advice meant for a blank setup.
+                if (isNoAuthConfigured(e))
+                    return { source: null };
+                throw e;
+            }
+        },
+        probeFn: () => client.request('GET', '/pub/v2/profiles'),
+        // A downed bridge is not a missing credential, and since mcp-utils 0.19.3
+        // the helper consults this for a `resolveCredential` failure too — so it
+        // gets its own arm instead of the `no_credential` copy. That copy could
+        // previously only hedge across both cases and point at `error.message`;
+        // now each answer names one cause and one fix.
+        classifyThrown: (err) => isBridgeDown(err)
+            ? {
+                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 ' +
+                    'not a credential problem: OFW_USERNAME/OFW_PASSWORD, if set, were not reached ' +
+                    'either. See error.message for the extension-specific fix.',
+            }
+            : undefined,
+        hints: {
+            // 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 ' +
+                '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 ' +
+                'in the tab. Retrying will not fix either.',
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "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": "^0.18.0",
-    "@fetchproxy/bootstrap": "^2.0.0",
+    "@chrischall/mcp-utils": "^0.19.3",
+    "@fetchproxy/bootstrap": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
     "zod": "^4.4.3"

package/server.json

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