simplepractice-mcp 0.2.0 → 0.4.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);
       }
     });
   }
@@ -31326,12 +31326,82 @@ function messageOf(err) {
   return String(err);
 }
 
-// node_modules/@chrischall/mcp-utils/dist/response/index.js
-function textResult(data) {
-  return {
-    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
-  };
+// node_modules/@chrischall/mcp-utils/dist/response/view.js
+var VIEWS = ["compact", "full", "raw"];
+var DEFAULT_VIEW = "compact";
+var BLURB = {
+  compact: '"compact" (default) drops fields the response already carries elsewhere',
+  full: '"full" returns every field this server understands',
+  raw: '"raw" returns the upstream payload unprojected'
+};
+function viewParam(honoured, opts = {}) {
+  if (honoured.length < 2) {
+    throw new Error("viewParam needs at least two rungs: a parameter offering one value decides nothing");
+  }
+  if (!honoured.includes("compact")) {
+    throw new Error('viewParam must offer "compact": a tool with no cheap rung has nothing to default to');
+  }
+  const ordered = VIEWS.filter((v) => honoured.includes(v));
+  const sentence = `Response shape: ${ordered.map((v) => BLURB[v]).join("; ")}.`;
+  return external_exports.enum(Object.fromEntries(ordered.map((v) => [v, v]))).optional().describe(opts.note ? `${sentence} ${opts.note}` : sentence);
+}
+function resolveView(value, honoured) {
+  return value !== void 0 && honoured.includes(value) ? value : DEFAULT_VIEW;
+}
+function minifiedResult(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+
+// node_modules/@chrischall/mcp-utils/dist/response/media.js
+var MEDIA_NOUN = "(?:avatar|picture|photo|thumbnail|thumb|image|icon|banner|profile_pic(?:ture)?|logo)";
+var MEDIA_QUALIFIER = "(?:primary|secondary|main|default|cover|hero|profile|master|rendered|small|medium|large|full|original|tall)";
+var MEDIA_KEY = new RegExp(`^(?:(?:${MEDIA_QUALIFIER}|${MEDIA_NOUN})[_-]?)?${MEDIA_NOUN}s?(?:[_-]?(?:link|uri|url|src)s?)?$`, "i");
+var MEDIA_URL = /^https?:\/\/[^\s]+?\.(png|jpe?g|gif|webp|svg|avif|bmp|ico)([?#]|$)/i;
+function stripMediaUrls(value, opts = {}) {
+  const keep = normalizeRules(opts.keep ?? []);
+  const drop = normalizeRules(opts.drop ?? []);
+  return walk(value, keep, drop);
+}
+function normalizeRules(rules) {
+  return rules.map((rule) => typeof rule === "string" ? rule.toLowerCase() : new RegExp(rule.source, rule.flags));
+}
+function matchesRule(key, rules) {
+  const lower = key.toLowerCase();
+  for (const rule of rules) {
+    if (typeof rule === "string") {
+      if (rule === lower)
+        return true;
+      continue;
+    }
+    rule.lastIndex = 0;
+    if (rule.test(key))
+      return true;
+  }
+  return false;
 }
+function walk(value, keep, drop) {
+  if (Array.isArray(value))
+    return value.map((v) => walk(v, keep, drop));
+  if (value === null || typeof value !== "object")
+    return value;
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+    return value;
+  const out = {};
+  for (const [key, v] of Object.entries(value)) {
+    if (matchesRule(key, keep)) {
+      out[key] = v;
+      continue;
+    }
+    if (MEDIA_KEY.test(key) || matchesRule(key, drop))
+      continue;
+    if (typeof v === "string" && MEDIA_URL.test(v))
+      continue;
+    out[key] = walk(v, keep, drop);
+  }
+  return out;
+}
+
+// node_modules/@chrischall/mcp-utils/dist/response/index.js
 function errorResult(message) {
   return {
     content: [{ type: "text", text: redactSecrets(message) }],
@@ -31530,11 +31600,11 @@ function toolAnnotations(opts = {}) {
 }
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.4.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 +31740,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 +31758,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 +31846,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 +31987,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 +32028,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();
@@ -31959,11 +32142,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 });
@@ -31974,17 +32163,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({
+      return minifiedResult({
         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."
+        }
       });
     }
   );
@@ -31995,39 +32190,49 @@ 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({
+        return minifiedResult({
           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 minifiedResult({
+          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 "#".')
       }
     },
-    async ({ link }) => textResult(await verifySignInToken(client2, link))
+    async ({ link }) => minifiedResult(await verifySignInToken(client2, link))
   );
   server.registerTool(
     "simplepractice_verify_sign_in_pin",
@@ -32039,7 +32244,7 @@ function registerAuthTools(server, client2) {
         pin: external_exports.string().regex(/^\d{6}$/, "The PIN is exactly 6 digits.")
       }
     },
-    async ({ email: email3, pin }) => textResult(await verifySignInPin(client2, email3, pin))
+    async ({ email: email3, pin }) => minifiedResult(await verifySignInPin(client2, email3, pin))
   );
   server.registerTool(
     "simplepractice_sign_out",
@@ -32048,7 +32253,7 @@ function registerAuthTools(server, client2) {
       annotations: toolAnnotations({ readOnly: false, idempotent: true }),
       inputSchema: {}
     },
-    async () => textResult({ signedOut: client2.clearSession() })
+    async () => minifiedResult({ signedOut: client2.clearSession() })
   );
 }
 
@@ -32070,7 +32275,7 @@ function registerAccountTools(server, client2) {
       const currentClient = environment.currentClient;
       const options = environment.currentClientOptions ?? [];
       const name = (c) => [c.preferredName ?? c.firstName, c.lastName].filter(Boolean).join(" ");
-      return textResult({
+      return minifiedResult({
         practice: practice && {
           id: practice.id,
           name: practice.fullName,
@@ -32103,6 +32308,18 @@ function registerAccountTools(server, client2) {
   );
 }
 
+// src/view.ts
+var SP_VIEWS = ["compact", "full"];
+var NOTE = `compact returns the slim projection where one exists and strips image URLs elsewhere; "full" returns SimplePractice's whole records.`;
+var viewArg = () => viewParam(SP_VIEWS, { note: NOTE });
+function isCompact(view) {
+  const rung = resolveView(view, SP_VIEWS);
+  return rung === "compact";
+}
+function viewResponse(view, data) {
+  return minifiedResult(isCompact(view) ? stripMediaUrls(data) : data);
+}
+
 // src/tools/appointments.ts
 var PAGE_SIZE_MAX = 50;
 function compactAppointment(a) {
@@ -32132,22 +32349,22 @@ function registerAppointmentTools(server, client2) {
         status: external_exports.enum(["scheduled", "requested"]).default("scheduled").describe("Which side of the pending-confirmation filter to read."),
         page: external_exports.number().int().positive().default(1),
         pageSize: external_exports.number().int().positive().max(PAGE_SIZE_MAX).default(PAGE_SIZE_MAX),
-        compact: external_exports.boolean().default(true).describe("Return a slim projection. Set false for the full records.")
+        view: viewArg()
       }
     },
-    async ({ status, page, pageSize, compact }) => {
+    async ({ status, page, pageSize, view }) => {
       const { records } = await client2.list("/appointments", {
         include: "clinician,office,client",
         filter: { hasPendingConfirmation: status === "requested" },
         page: { number: page, size: pageSize }
       });
-      return textResult({
+      return minifiedResult({
         status,
         page,
         count: records.length,
         // The API sends no total; a short page is the last page.
         hasMore: records.length >= pageSize,
-        appointments: compact ? records.map(compactAppointment) : records
+        appointments: isCompact(view) ? records.map(compactAppointment) : records
       });
     }
   );
@@ -32179,16 +32396,20 @@ function registerBillingTools(server, client2) {
       inputSchema: {
         kind: external_exports.enum(["invoice", "statement", "superbill", "receipt", "account-history"]).default("invoice"),
         before: external_exports.string().optional().describe("Cursor for the next page \u2014 the nextCursor from a previous call."),
-        pageSize: external_exports.number().int().positive().max(PAGE_SIZE_MAX2).default(PAGE_SIZE_MAX2)
+        pageSize: external_exports.number().int().positive().max(PAGE_SIZE_MAX2).default(PAGE_SIZE_MAX2),
+        view: viewArg()
       }
     },
-    async ({ kind, before, pageSize }) => {
+    // `view` is destructured off, never forwarded: `client.list` turns whatever
+    // it is handed into a JSON:API query string, and a stray `view=compact`
+    // would reach SimplePractice as a filter it never defined.
+    async ({ kind, before, pageSize, view }) => {
       const { records, meta: meta3 } = await client2.list("/billing-items", {
         filter: KINDS[kind],
         page: before ? { size: pageSize, before } : { size: pageSize }
       });
       const last = records[records.length - 1];
-      return textResult({
+      return viewResponse(view, {
         kind,
         count: records.length,
         endBalance: meta3?.endBalance ?? null,
@@ -32203,11 +32424,11 @@ function registerBillingTools(server, client2) {
     {
       description: "Balance due and per-category counts for the Client Portal account. Cheaper than paging the billing collections just to find out whether anything is there.",
       annotations: toolAnnotations({ readOnly: true }),
-      inputSchema: {}
+      inputSchema: { view: viewArg() }
     },
-    async () => {
+    async ({ view }) => {
       const overview = await loadClientRelationship(client2, "clientBillingOverview");
-      return textResult(overview ?? { note: "No billing overview returned for this client." });
+      return viewResponse(view, overview ?? { note: "No billing overview returned for this client." });
     }
   );
   server.registerTool(
@@ -32217,10 +32438,13 @@ function registerBillingTools(server, client2) {
       annotations: toolAnnotations({ readOnly: true }),
       inputSchema: {}
     },
+    // No `view`: the response below IS a projection, hand-written down to five
+    // fields with knowledge of what a card record holds. Running the blind rung
+    // over it afterwards would let an un-grounded rule overrule a grounded one.
     async () => {
       const cards = await loadClientRelationship(client2, "cards");
       const list = Array.isArray(cards) ? cards : [];
-      return textResult({
+      return minifiedResult({
         count: list.length,
         paymentMethods: list.map((c) => ({
           id: c.id,
@@ -32250,6 +32474,9 @@ function registerDocumentTools(server, client2) {
         includeBody: external_exports.boolean().default(false).describe("Include the full document body/questions. Off by default \u2014 these are long.")
       }
     },
+    // No `view`: `items` below is a hand-written projection, and `includeBody`
+    // is a field the caller explicitly asked for. A blind rung run over that
+    // output could only take back something chosen on purpose.
     async ({ outstandingOnly, pageSize, includeBody }) => {
       const { records, meta: meta3 } = await client2.list("/document-requests", {
         page: { size: pageSize }
@@ -32275,7 +32502,7 @@ function registerDocumentTools(server, client2) {
         }
         return base;
       });
-      return textResult({
+      return minifiedResult({
         count: items.length,
         outstanding: records.filter((r) => !SETTLED.has(String(r.status))).length,
         welcomeText: meta3?.welcomeText ?? null,
@@ -32288,13 +32515,18 @@ function registerDocumentTools(server, client2) {
     {
       description: "One document request in full, including its body or its questions and the answers already given.",
       annotations: toolAnnotations({ readOnly: true }),
-      inputSchema: { id: external_exports.string().min(1).describe("The document request id.") }
+      inputSchema: {
+        id: external_exports.string().min(1).describe("The document request id."),
+        view: viewArg()
+      }
     },
-    async ({ id }) => {
+    // `view` is destructured off rather than passed on: the id is the only part
+    // of this input that may reach the request path.
+    async ({ id, view }) => {
       const { records } = await client2.list(`/document-requests/${encodeURIComponent(id)}`);
       const record2 = records[0];
-      if (!record2) return textResult({ found: false, id });
-      return textResult({
+      if (!record2) return minifiedResult({ found: false, id });
+      return viewResponse(view, {
         ...record2,
         hasDocumentPdf: asBoolean(record2.hasDocumentPdf) ?? false
       });
@@ -32309,9 +32541,14 @@ function registerDocumentTools(server, client2) {
         pageSize: external_exports.number().int().positive().max(PAGE_SIZE_MAX3).default(PAGE_SIZE_MAX3)
       }
     },
+    // No `view`, and this one is the exception worth stating: the PRODUCT of
+    // this tool is the file references themselves. A practice that shares a
+    // scan shares it as a .jpg or .png, and the blind rung drops any string
+    // whose path ends in an image extension — so compacting here would empty
+    // exactly the rows a caller came for rather than shrink them.
     async ({ pageSize }) => {
       const { records } = await client2.list("/documents", { page: { size: pageSize } });
-      return textResult({ count: records.length, documents: records });
+      return minifiedResult({ count: records.length, documents: records });
     }
   );
   server.registerTool(
@@ -32320,12 +32557,13 @@ function registerDocumentTools(server, client2) {
       description: "Announcements the practice has posted to the Client Portal. readAt is null on unread ones.",
       annotations: toolAnnotations({ readOnly: true }),
       inputSchema: {
-        pageSize: external_exports.number().int().positive().max(PAGE_SIZE_MAX3).default(PAGE_SIZE_MAX3)
+        pageSize: external_exports.number().int().positive().max(PAGE_SIZE_MAX3).default(PAGE_SIZE_MAX3),
+        view: viewArg()
       }
     },
-    async ({ pageSize }) => {
+    async ({ pageSize, view }) => {
       const { records } = await client2.list("/announcements", { page: { size: pageSize } });
-      return textResult({
+      return viewResponse(view, {
         count: records.length,
         unread: records.filter((r) => r.readAt === null || r.readAt === void 0).length,
         announcements: records
@@ -32334,6 +32572,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({
@@ -32346,6 +32789,7 @@ await runMcp({
     registerAccountTools,
     registerAppointmentTools,
     registerBillingTools,
-    registerDocumentTools
+    registerDocumentTools,
+    registerHealthcheckTools
   ]
 });