simplepractice-mcp 0.1.0 → 0.3.0

package/dist/bundle.js

@@ -2985,7 +2985,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve2.call(this, root, ref);
+      let _sch = resolve3.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a3 = root.localRefs) === null || _a3 === void 0 ? void 0 : _a3[ref];
         const { schemaId } = this.opts;
@@ -3012,7 +3012,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve2(root, ref) {
+    function resolve3(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3837,7 +3837,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve2(baseURI, relativeURI, options) {
+    function resolve3(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const {
         parsed: baseParsed,
@@ -4199,7 +4199,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve2,
+      resolve: resolve3,
       resolveComponent,
       equal,
       serialize,
@@ -29146,7 +29146,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+        await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error51) {
@@ -29163,7 +29163,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const earlyReject = (error51) => {
         reject(error51);
       };
@@ -29241,7 +29241,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve2(parseResult.data);
+            resolve3(parseResult.data);
           }
         } catch (error51) {
           reject(error51);
@@ -29502,12 +29502,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve2, interval);
+      const timeoutId = setTimeout(resolve3, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -30598,7 +30598,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+      await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -31262,12 +31262,12 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve2) => {
+    return new Promise((resolve3) => {
       const json2 = serializeMessage(message);
       if (this._stdout.write(json2)) {
-        resolve2();
+        resolve3();
       } else {
-        this._stdout.once("drain", resolve2);
+        this._stdout.once("drain", resolve3);
       }
     });
   }
@@ -31530,11 +31530,11 @@ function toolAnnotations(opts = {}) {
 }
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.3.0";
 
 // node_modules/@chrischall/mcp-utils/dist/session/index.js
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync } from "node:fs";
-import { dirname } from "node:path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync, unlinkSync } from "node:fs";
+import { dirname, join as join2, resolve as resolve2 } from "node:path";
 function normalizeOrigin(input) {
   try {
     return new URL(input).origin.replace(/\/$/, "");
@@ -31670,7 +31670,7 @@ var TOKEN_REFRESH_SKEW_MS = 5 * 60 * 1e3;
 
 // src/config.ts
 import { homedir as homedir2 } from "node:os";
-import { join as join2 } from "node:path";
+import { join as join3 } from "node:path";
 var API_VERSION = "2026-05-25";
 var APPLICATION_BUILD_VERSION = "0.0.0";
 var APPLICATION_PLATFORM = "web";
@@ -31688,13 +31688,21 @@ function resolvePortalHost(raw) {
   if (!/^[a-z0-9][a-z0-9-]*$/.test(label)) return null;
   return value;
 }
+function practiceHostFromLink(raw) {
+  if (!raw) return null;
+  const hash2 = raw.indexOf("#");
+  if (hash2 < 0) return null;
+  const prefix = raw.slice(0, hash2).trim();
+  if (!prefix.includes(".")) return null;
+  return resolvePortalHost(prefix);
+}
 function readPortalHost() {
   return resolvePortalHost(readEnvVar("SIMPLEPRACTICE_PRACTICE"));
 }
 function sessionFilePath() {
   const override = readEnvVar("SIMPLEPRACTICE_SESSION_FILE");
   if (override) return expandPath(override);
-  return join2(homedir2(), ".simplepractice-mcp", "session.json");
+  return join3(homedir2(), ".simplepractice-mcp", "session.json");
 }
 
 // src/jsonapi.ts
@@ -31768,36 +31776,139 @@ function buildQuery(params) {
 }
 var SimplePracticeClient = class {
   store;
-  configError;
-  host;
   fetchImpl;
+  /** A practice learned at runtime — from a sign-in link, or named on a tool call. */
+  adoptedHost = null;
   constructor(opts = {}) {
     this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
-    const host = readPortalHost();
-    this.configError = host ? null : new McpToolError(
-      "SIMPLEPRACTICE_PRACTICE is not set, or is not a valid Client Portal address.",
-      {
-        hint: `Set SIMPLEPRACTICE_PRACTICE to your practice's portal address \u2014 either the slug ("achievebalancetherapy") or the full host ("achievebalancetherapy.clientsecure.me"). It is the host in the portal link your provider emailed you.`
-      }
-    );
-    this.host = host ?? "";
     this.store = opts.store ?? new SessionStore({
       filePath: sessionFilePath(),
       keyOf: (session) => session.host,
       normalizeKey: (key) => key.toLowerCase()
     });
   }
-  /** Throws the deferred configuration error, if there is one. */
+  /**
+   * Which practice this server is talking to, and how it found out.
+   *
+   * Resolved per call rather than fixed at construction, because the practice
+   * is usually not known when the process starts: it arrives with the sign-in
+   * link. In order:
+   *
+   *  1. **link** — adopted at runtime from the emailed link (or named on the
+   *     tool call). The most recent explicit statement of intent, and the only
+   *     one that can be right when a token is minted for a different practice
+   *     than the environment names.
+   *  2. **environment** — `SIMPLEPRACTICE_PRACTICE`, an explicit pin for
+   *     someone who wants this server bound to one practice.
+   *  3. **session** — the practice of the most recent sign-in. This is what
+   *     makes the link route survive a restart: sign in once, and every later
+   *     process knows the practice with no configuration at all.
+   */
+  resolveHost() {
+    if (this.adoptedHost) return { host: this.adoptedHost, source: "link" };
+    const configured = readPortalHost();
+    if (configured) return { host: configured, source: "environment" };
+    const remembered = this.mostRecentSessionHost();
+    return remembered ? { host: remembered, source: "session" } : null;
+  }
+  /**
+   * The practice signed into most recently, by our own `createdAt` rather than
+   * `SessionStore`'s active pointer.
+   *
+   * The two agree right up until a practice is signed into twice, and then
+   * they disagree across a restart: `add()` on an existing key leaves the Map
+   * entry in its ORIGINAL insertion position, so the in-memory pointer names
+   * the practice just added, while a fresh process restores the pointer as the
+   * LAST key on disk. Signing in to A, then B, then A again would leave the
+   * next process quietly talking to B.
+   *
+   * `createdAt` is the fact this fallback actually means, and unlike the
+   * pointer it survives the restart.
+   */
+  mostRecentSessionHost() {
+    let newest = null;
+    for (const session of this.store.list()) {
+      if (!newest || session.createdAt > newest.createdAt) newest = session;
+    }
+    return newest?.host ?? null;
+  }
+  /** The practice host, or `null` when none is known yet. Never throws. */
+  knownPortalHost() {
+    return this.resolveHost()?.host ?? null;
+  }
+  /** How the practice was determined, or `null` when it has not been. */
+  practiceSource() {
+    return this.resolveHost()?.source ?? null;
+  }
+  /**
+   * The host a practice address names, WITHOUT adopting it.
+   *
+   * Validated through the same `resolvePortalHost` the environment goes
+   * through, so a link outside `*.clientsecure.me` cannot redirect a token.
+   *
+   * Separate from {@link adoptPracticeHost} so a caller that only wants to
+   * *name* the practice — a dry run reporting what it would do — can do that
+   * without the side effect. Answering a question should not move the server.
+   */
+  validatePracticeHost(raw) {
+    const host = resolvePortalHost(raw);
+    if (!host) {
+      throw new McpToolError(`"${raw}" is not a SimplePractice Client Portal address.`, {
+        hint: 'A portal address is a single practice under clientsecure.me \u2014 the slug ("achievebalancetherapy") or the whole host ("achievebalancetherapy.clientsecure.me").'
+      });
+    }
+    return host;
+  }
+  /**
+   * Point this server at a practice for the rest of the process — what the
+   * sign-in link's own host feeds.
+   */
+  adoptPracticeHost(raw) {
+    this.adoptedHost = this.validatePracticeHost(raw);
+    return this.adoptedHost;
+  }
+  /**
+   * Adopt `raw`'s practice for the duration of `fn`, and keep it only if `fn`
+   * succeeds.
+   *
+   * Sign-in links are single-use, so a failed exchange is the ordinary case,
+   * not the exception. Letting a failed attempt stick would leave someone who
+   * pasted a stale link for practice B pointed at B for the life of the
+   * process — and their intact session for practice A would report "Not signed
+   * in" until a restart. A link only earns the practice by working.
+   */
+  async withPracticeHost(raw, fn) {
+    const previous = this.adoptedHost;
+    this.adoptPracticeHost(raw);
+    try {
+      return await fn();
+    } catch (err) {
+      this.adoptedHost = previous;
+      throw err;
+    }
+  }
+  /**
+   * The practice host, or the deferred error explaining that none is known.
+   *
+   * Deferred rather than thrown at construction: the server must still boot
+   * (and answer the host's install-time tools/list probe) knowing no practice,
+   * which is now the ordinary first-run state rather than a misconfiguration.
+   */
   requireConfig() {
-    if (this.configError) throw this.configError;
-    return this.host;
+    const host = this.knownPortalHost();
+    if (!host) {
+      throw new McpToolError("I do not know which practice portal to talk to yet.", {
+        hint: "Paste the sign-in link your provider emailed into simplepractice_verify_sign_in_token \u2014 its address names the practice, and this server remembers it. To ask for that link first, pass `practice` to simplepractice_request_sign_in_link, or set SIMPLEPRACTICE_PRACTICE to pin this server to one practice."
+      });
+    }
+    return host;
   }
   portalHost() {
     return this.requireConfig();
   }
   getSession() {
-    if (this.configError) return null;
-    return this.store.get(this.host);
+    const host = this.knownPortalHost();
+    return host ? this.store.get(host) : null;
   }
   saveSession(cookie) {
     const host = this.requireConfig();
@@ -31806,14 +31917,14 @@ var SimplePracticeClient = class {
     return session;
   }
   clearSession() {
-    const host = this.requireConfig();
-    return this.store.remove(host);
+    const host = this.knownPortalHost();
+    return host ? this.store.remove(host) : false;
   }
   requireSession() {
     const session = this.getSession();
     if (!session) {
       throw new McpToolError("Not signed in to the SimplePractice Client Portal.", {
-        hint: 'Run simplepractice_request_sign_in_link to have SimplePractice email you a sign-in link, then pass the part of that link after the "#" to simplepractice_verify_sign_in_token.'
+        hint: "Pass the sign-in link SimplePractice emailed to simplepractice_verify_sign_in_token \u2014 the whole link, which names the practice as well as carrying the token. Run simplepractice_request_sign_in_link first if you do not have one."
       });
     }
     return session;
@@ -31847,7 +31958,9 @@ var SimplePracticeClient = class {
     } catch (err) {
       throw new McpToolError(
         `Could not reach ${host}: ${truncateErrorMessage(messageOf(err))}`,
-        { hint: "Check the practice address in SIMPLEPRACTICE_PRACTICE and your network connection." }
+        {
+          hint: `Check your network connection, and that ${host} is really your practice's portal \u2014 simplepractice_session_status reports where that address came from.`
+        }
       );
     }
     const raw = await response.text();
@@ -31857,7 +31970,7 @@ var SimplePracticeClient = class {
     } catch {
       document = null;
     }
-    if (!response.ok) this.throwForStatus(response.status, document);
+    if (!response.ok) this.throwForStatus(response.status, document, path);
     if (document === null) {
       throw new McpToolError(
         `SimplePractice returned HTML rather than JSON for ${path}.`,
@@ -31884,11 +31997,12 @@ var SimplePracticeClient = class {
     const { document } = await this.request(path, { query });
     return flattenDocument(document);
   }
-  throwForStatus(status, document) {
+  throwForStatus(status, document, path) {
     const message = formatJsonApiErrors(document, status);
+    const isSignIn = path.startsWith("/sessions/") || path.startsWith("/sign-in-tokens");
     if (status === 401 || status === 403) {
       throw new McpToolError(message, {
-        hint: "The portal session has expired \u2014 there is no refresh token, so sign in again with simplepractice_request_sign_in_link."
+        hint: isSignIn ? "Sign-in links and PINs are single-use and last 24 hours. Request a fresh one with simplepractice_request_sign_in_link." : "The portal session has expired \u2014 there is no refresh token, so sign in again with simplepractice_request_sign_in_link."
       });
     }
     if (status === 429) {
@@ -31958,11 +32072,17 @@ async function establishSession(client2, attributes) {
       hint: `Expected a ${SESSION_COOKIE} cookie on the response. If SimplePractice has renamed it, simplepractice-mcp needs updating.`
     });
   }
-  client2.saveSession(`${SESSION_COOKIE}=${cookie}`);
-  return { status, signedIn: true };
+  const session = client2.saveSession(`${SESSION_COOKIE}=${cookie}`);
+  return { status, signedIn: true, practiceHost: session.host };
 }
-function verifySignInToken(client2, linkOrToken) {
-  return establishSession(client2, { type: "token", token: extractToken(linkOrToken) });
+async function verifySignInToken(client2, linkOrToken) {
+  const attributes = { type: "token", token: extractToken(linkOrToken) };
+  const fromLink = practiceHostFromLink(linkOrToken);
+  if (fromLink) {
+    return client2.withPracticeHost(fromLink, () => establishSession(client2, attributes));
+  }
+  client2.portalHost();
+  return establishSession(client2, attributes);
 }
 function verifySignInPin(client2, email3, pin) {
   return establishSession(client2, { type: "pin", email: email3, pin });
@@ -31973,17 +32093,23 @@ function registerAuthTools(server, client2) {
   server.registerTool(
     "simplepractice_session_status",
     {
-      description: "Report whether this server holds a Client Portal session, and for which practice. Reads local state only \u2014 makes no network call.",
+      description: "Report whether this server holds a Client Portal session, for which practice, and how that practice was determined (from a sign-in link, from SIMPLEPRACTICE_PRACTICE, or remembered from the stored session). Reads local state only \u2014 makes no network call.",
       annotations: toolAnnotations({ readOnly: true }),
       inputSchema: {}
     },
     async () => {
-      const host = client2.portalHost();
+      const host = client2.knownPortalHost();
       const session = client2.getSession();
       return textResult({
         practiceHost: host,
+        // Not knowing the practice yet is a state to report, not an error:
+        // it is what a first run looks like before anyone has pasted a link.
+        practiceSource: client2.practiceSource(),
         signedIn: session !== null,
-        signedInAt: session?.createdAt ?? null
+        signedInAt: session?.createdAt ?? null,
+        ...host ? {} : {
+          next: "Paste the sign-in link your provider emailed into simplepractice_verify_sign_in_token \u2014 its address names the practice. Or set SIMPLEPRACTICE_PRACTICE to pin this server to one."
+        }
       });
     }
   );
@@ -31994,33 +32120,43 @@ function registerAuthTools(server, client2) {
       annotations: toolAnnotations({ readOnly: false, idempotent: false }),
       inputSchema: {
         email: external_exports.string().email().describe("The email address the Client Portal is registered to."),
+        practice: external_exports.string().min(1).optional().describe(
+          'The practice whose portal to sign in to \u2014 the slug ("achievebalancetherapy"), the host, or the portal URL. Only needed when this server does not know the practice yet; signing in with an emailed link teaches it, and it then remembers.'
+        ),
         confirm: schemaConfirm
       }
     },
-    async ({ email: email3, confirm }) => {
+    async ({ email: email3, practice, confirm }) => {
       if (!confirm) {
         return textResult({
           dryRun: true,
           wouldSend: "a Client Portal sign-in email",
           to: email3,
-          practiceHost: client2.portalHost(),
+          // Named, not adopted. A dry run sends nothing, so it must not move
+          // the server either — silently overriding a SIMPLEPRACTICE_PRACTICE
+          // pin is not something an inert preview gets to do.
+          practiceHost: practice ? client2.validatePracticeHost(practice) : client2.portalHost(),
           note: "Re-run with confirm:true to actually send it. Do not retry a failed send \u2014 SimplePractice locks out repeated sign-in requests."
         });
       }
-      const { expiresIn } = await requestSignInLink(client2, email3);
-      return textResult({
-        sent: true,
-        to: email3,
-        expiresIn,
-        next: 'Open the email, copy the sign-in link (or just the part after the "#"), and pass it to simplepractice_verify_sign_in_token.',
-        note: "This response is the same whether or not the address has an account."
-      });
+      const send = async () => {
+        const { expiresIn } = await requestSignInLink(client2, email3);
+        return textResult({
+          sent: true,
+          to: email3,
+          practiceHost: client2.portalHost(),
+          expiresIn,
+          next: 'Open the email, copy the sign-in link (or just the part after the "#"), and pass it to simplepractice_verify_sign_in_token.',
+          note: "This response is the same whether or not the address has an account."
+        });
+      };
+      return practice ? client2.withPracticeHost(practice, send) : send();
     }
   );
   server.registerTool(
     "simplepractice_verify_sign_in_token",
     {
-      description: 'Exchange an emailed sign-in link (or the token in it) for a Client Portal session. Accepts the whole link or just the part after the "#". Tokens are single-use and last 24 hours.',
+      description: 'Exchange an emailed sign-in link (or the token in it) for a Client Portal session. Accepts the whole link or just the part after the "#". Prefer passing the WHOLE link: its address names the practice, so no practice has to be configured, and this server remembers it afterwards. Tokens are single-use and last 24 hours.',
       annotations: toolAnnotations({ readOnly: false, idempotent: false }),
       inputSchema: {
         link: external_exports.string().min(1).describe('The sign-in link from the email, or just the token after the "#".')
@@ -32333,6 +32469,211 @@ function registerDocumentTools(server, client2) {
   );
 }
 
+// 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/tools/health.ts
+var CLIENT_ERROR_TEXT = {
+  /** From client.ts `requireConfig()` — thrown by `portalHost()`. */
+  noPractice: "I do not know which practice portal to talk to yet",
+  /** From client.ts `throwForStatus()` 401/403, on the HINT — not the message. */
+  sessionExpired: "The portal session has expired",
+  /** From client.ts `requireSession()`, on the MESSAGE. */
+  notSignedIn: "Not signed in to the SimplePractice Client Portal",
+  /** From client.ts `throwForStatus()` 429, on the HINT. */
+  rateLimited: "SimplePractice rate-limits sign-in requests"
+};
+function classifySimplePracticeError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  const hint = typeof err?.hint === "string" ? err.hint : "";
+  const text = `${message}
+${hint}`;
+  if (text.includes(CLIENT_ERROR_TEXT.noPractice)) {
+    return {
+      kind: "no_practice_host",
+      hint: "No practice known yet. Paste the sign-in link your provider emailed into simplepractice_verify_sign_in_token \u2014 its address names the practice, and this server remembers it afterwards. SIMPLEPRACTICE_PRACTICE is optional, and only pins the server to one practice."
+    };
+  }
+  if (text.includes(CLIENT_ERROR_TEXT.rateLimited)) {
+    return {
+      kind: "rate_limited",
+      hint: "SimplePractice rate-limits sign-in requests per email and per IP. The session is not necessarily bad \u2014 do NOT retry, and wait before requesting another link."
+    };
+  }
+  if (text.includes(CLIENT_ERROR_TEXT.sessionExpired) || text.includes(CLIENT_ERROR_TEXT.notSignedIn)) {
+    return {
+      kind: "session_expired",
+      hint: 'The portal rejected the stored session. There is no refresh token, so it cannot be renewed silently: run simplepractice_request_sign_in_link, then pass the part of the emailed link after the "#" to simplepractice_verify_sign_in_token.'
+    };
+  }
+  return void 0;
+}
+function registerHealthcheckTools(server, client2) {
+  registerCredentialHealthcheckTool({
+    server,
+    prefix: "simplepractice",
+    hostLabel: "clientsecure.me",
+    probePath: "/environment",
+    resolveCredential: async () => {
+      const session = client2.getSession();
+      return {
+        source: session ? "portal_session" : null,
+        detail: {
+          // `knownPortalHost`, not `portalHost`: the latter throws, and not
+          // knowing the practice is the ordinary state before anyone has
+          // pasted a sign-in link. A healthcheck that throws where it should
+          // report `practice_host: null` fails at the one job it has — saying
+          // which hop is broken.
+          practice_host: client2.knownPortalHost(),
+          // When the session was minted — the fact that explains a connector
+          // that worked yesterday and does not today. Never the cookie.
+          signed_in_at: session?.createdAt ?? null
+        }
+      };
+    },
+    // The cheapest authenticated read in the portal, and the one the client
+    // already uses to resolve the current client id. It changes nothing: no
+    // appointment booked, no document touched.
+    probeFn: () => client2.list("/environment", { include: "currentClient" }),
+    classifyThrown: classifySimplePracticeError
+  });
+}
+
 // src/index.ts
 var client = new SimplePracticeClient();
 await runMcp({
@@ -32345,6 +32686,7 @@ await runMcp({
     registerAccountTools,
     registerAppointmentTools,
     registerBillingTools,
-    registerDocumentTools
+    registerDocumentTools,
+    registerHealthcheckTools
   ]
 });