simplepractice-mcp 0.3.0 → 0.4.1

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "SimplePractice Client Portal tools for Claude",
-    "version": "0.3.0"
+    "version": "0.4.1"
   },
   "plugins": [
     {
       "name": "simplepractice",
       "source": "./",
       "description": "Read a SimplePractice Client Portal — appointments, invoices and superbills, documents to sign, and practice announcements. Signs in with the portal's own passwordless emailed link; requests go straight to the portal's JSON:API over your own session.",
-      "version": "0.3.0",
+      "version": "0.4.1",
       "author": {
         "name": "Chris Chall",
         "url": "https://github.com/chrischall"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "simplepractice",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "SimplePractice Client Portal — appointments, billing, documents, and announcements",
   "author": {
     "name": "Chris Chall",

package/README.md

@@ -24,6 +24,14 @@ and announcements, read over the portal's own JSON:API.
 
 Everything is read-only. Cancelling, signing, and paying happen in the portal.
 
+The reads that answer with a SimplePractice record rather than a projection —
+appointments, billing items, the billing overview, one document request,
+announcements — take a `view`. It defaults to `compact`, which returns the slim
+projection where this server has one and otherwise drops logo and avatar URLs a
+model cannot see; `view: "full"` returns the record untouched.
+`simplepractice_list_documents` deliberately takes none: what it returns is the
+file reference, and a shared scan is a `.jpg`.
+
 ## Setup
 
 ```sh

package/dist/bundle.js

@@ -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,7 +31600,7 @@ function toolAnnotations(opts = {}) {
 }
 
 // src/version.ts
-var VERSION = "0.3.0";
+var VERSION = "0.4.1";
 
 // node_modules/@chrischall/mcp-utils/dist/session/index.js
 import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync, unlinkSync } from "node:fs";
@@ -32100,7 +32170,7 @@ function registerAuthTools(server, client2) {
     async () => {
       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.
@@ -32128,7 +32198,7 @@ function registerAuthTools(server, client2) {
     },
     async ({ email: email3, practice, confirm }) => {
       if (!confirm) {
-        return textResult({
+        return minifiedResult({
           dryRun: true,
           wouldSend: "a Client Portal sign-in email",
           to: email3,
@@ -32141,7 +32211,7 @@ function registerAuthTools(server, client2) {
       }
       const send = async () => {
         const { expiresIn } = await requestSignInLink(client2, email3);
-        return textResult({
+        return minifiedResult({
           sent: true,
           to: email3,
           practiceHost: client2.portalHost(),
@@ -32162,7 +32232,7 @@ function registerAuthTools(server, client2) {
         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",
@@ -32174,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",
@@ -32183,7 +32253,7 @@ function registerAuthTools(server, client2) {
       annotations: toolAnnotations({ readOnly: false, idempotent: true }),
       inputSchema: {}
     },
-    async () => textResult({ signedOut: client2.clearSession() })
+    async () => minifiedResult({ signedOut: client2.clearSession() })
   );
 }
 
@@ -32205,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,
@@ -32238,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) {
@@ -32267,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
       });
     }
   );
@@ -32314,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,
@@ -32338,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(
@@ -32352,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,
@@ -32385,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 }
@@ -32410,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,
@@ -32423,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
       });
@@ -32444,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(
@@ -32455,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

package/dist/tools/account.js

@@ -1,5 +1,15 @@
-import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
 import { parseJsonString } from '../jsonapi.js';
+/**
+ * No `view` here, deliberately.
+ *
+ * `simplepractice_get_account` returns a hand-written projection: every field
+ * on it is picked by name out of `/environment`, chosen WITH knowledge of the
+ * payload (which is why `clientMayCancelAppointments` and the parsed
+ * `permissions` string are on it at all). There is no un-projected upstream
+ * shape left for a blind media-strip to act on, so a `view` parameter here
+ * would be one that changes nothing — worse than none.
+ */
 export function registerAccountTools(server, client) {
     server.registerTool('simplepractice_get_account', {
         description: 'The practice, the signed-in client, and every client this login can see. One portal login is a "client access" and may cover more than one client — a parent seeing two children, say — so clients is always a list.',
@@ -15,7 +25,7 @@ export function registerAccountTools(server, client) {
         const options = environment.currentClientOptions ?? [];
         // Only ever called with a resolved client record, so no undefined guard.
         const name = (c) => [c.preferredName ?? c.firstName, c.lastName].filter(Boolean).join(' ');
-        return textResult({
+        return minifiedResult({
             practice: practice && {
                 id: practice.id,
                 name: practice.fullName,

package/dist/tools/appointments.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { isCompact, viewArg } from '../view.js';
+import { minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
 const PAGE_SIZE_MAX = 50;
 function compactAppointment(a) {
     const clinician = a.clinician;
@@ -31,24 +32,21 @@ export function registerAppointmentTools(server, client) {
                 .describe('Which side of the pending-confirmation filter to read.'),
             page: z.number().int().positive().default(1),
             pageSize: z.number().int().positive().max(PAGE_SIZE_MAX).default(PAGE_SIZE_MAX),
-            compact: z
-                .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 client.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,
         });
     });
 }

package/dist/tools/auth.js

@@ -1,6 +1,15 @@
 import { z } from 'zod';
-import { textResult, toolAnnotations, schemaConfirm } from '@chrischall/mcp-utils';
+import { minifiedResult, schemaConfirm, toolAnnotations } from '@chrischall/mcp-utils';
 import { requestSignInLink, verifySignInPin, verifySignInToken } from '../auth.js';
+/**
+ * No `view` here, deliberately.
+ *
+ * Nothing in this file answers with a SimplePractice record: every response is
+ * a small object this server builds — local session state, a dry-run preview,
+ * the result of a sign-in exchange. There is no upstream payload to project or
+ * strip, and none of these are reads a caller pages through, so the rung would
+ * have nothing to switch between.
+ */
 export function registerAuthTools(server, client) {
     server.registerTool('simplepractice_session_status', {
         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 — makes no network call.',
@@ -9,7 +18,7 @@ export function registerAuthTools(server, client) {
     }, async () => {
         const host = client.knownPortalHost();
         const session = client.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.
@@ -37,7 +46,7 @@ export function registerAuthTools(server, client) {
         },
     }, async ({ email, practice, confirm }) => {
         if (!confirm) {
-            return textResult({
+            return minifiedResult({
                 dryRun: true,
                 wouldSend: 'a Client Portal sign-in email',
                 to: email,
@@ -50,7 +59,7 @@ export function registerAuthTools(server, client) {
         }
         const send = async () => {
             const { expiresIn } = await requestSignInLink(client, email);
-            return textResult({
+            return minifiedResult({
                 sent: true,
                 to: email,
                 practiceHost: client.portalHost(),
@@ -72,7 +81,7 @@ export function registerAuthTools(server, client) {
                 .min(1)
                 .describe('The sign-in link from the email, or just the token after the "#".'),
         },
-    }, async ({ link }) => textResult(await verifySignInToken(client, link)));
+    }, async ({ link }) => minifiedResult(await verifySignInToken(client, link)));
     server.registerTool('simplepractice_verify_sign_in_pin', {
         description: 'Exchange a 6-digit Client Portal sign-in PIN for a session, for practices that email a code instead of a link. Single-use.',
         annotations: toolAnnotations({ readOnly: false, idempotent: false }),
@@ -80,10 +89,10 @@ export function registerAuthTools(server, client) {
             email: z.string().email().describe('The address the PIN was sent to.'),
             pin: z.string().regex(/^\d{6}$/, 'The PIN is exactly 6 digits.'),
         },
-    }, async ({ email, pin }) => textResult(await verifySignInPin(client, email, pin)));
+    }, async ({ email, pin }) => minifiedResult(await verifySignInPin(client, email, pin)));
     server.registerTool('simplepractice_sign_out', {
         description: 'Discard the stored Client Portal session from local state.',
         annotations: toolAnnotations({ readOnly: false, idempotent: true }),
         inputSchema: {},
-    }, async () => textResult({ signedOut: client.clearSession() }));
+    }, async () => minifiedResult({ signedOut: client.clearSession() }));
 }

package/dist/tools/billing.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { viewArg, viewResponse } from '../view.js';
+import { minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
 import { asBoolean } from '../jsonapi.js';
 const PAGE_SIZE_MAX = 50;
 /**
@@ -42,14 +43,26 @@ export function registerBillingTools(server, client) {
                 .optional()
                 .describe('Cursor for the next page — the nextCursor from a previous call.'),
             pageSize: z.number().int().positive().max(PAGE_SIZE_MAX).default(PAGE_SIZE_MAX),
+            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 } = await client.list('/billing-items', {
             filter: KINDS[kind],
             page: before ? { size: pageSize, before } : { size: pageSize },
         });
         const last = records[records.length - 1];
-        return textResult({
+        // `items` is the upstream billing-item record verbatim — this tool has no
+        // projection, because `billing-items` is polymorphic (five `thisType`
+        // switches) and a field list picked for an invoice would quietly drop
+        // half of a superbill. That is exactly the payload the blind rung is for:
+        // compact strips the practice logo and provider avatars an invoice row
+        // carries, and touches nothing whose key names an amount, a date, or a
+        // document link.
+        return viewResponse(view, {
             kind,
             count: records.length,
             endBalance: meta?.endBalance ?? null,
@@ -61,19 +74,27 @@ export function registerBillingTools(server, client) {
     server.registerTool('simplepractice_get_billing_overview', {
         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: {},
-    }, async () => {
+        inputSchema: { view: viewArg() },
+    }, async ({ view }) => {
         const overview = await loadClientRelationship(client, 'clientBillingOverview');
-        return textResult(overview ?? { note: 'No billing overview returned for this client.' });
+        // Also un-projected: the overview is whatever `clientBillingOverview`
+        // hangs off the client record, and its per-category counts vary by what
+        // the practice bills for. Stripping media is the only shrink available
+        // that cannot drop a balance.
+        return viewResponse(view, overview ?? { note: 'No billing overview returned for this client.' });
     });
     server.registerTool('simplepractice_list_payment_methods', {
         description: 'Payment methods saved to the Client Portal — brand, last four digits, and expiry. No full card numbers.',
         annotations: toolAnnotations({ readOnly: true }),
         inputSchema: {},
-    }, async () => {
+    }, 
+    // 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(client, 'cards');
         const list = Array.isArray(cards) ? cards : [];
-        return textResult({
+        return minifiedResult({
             count: list.length,
             paymentMethods: list.map((c) => ({
                 id: c.id,

package/dist/tools/documents.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { viewArg, viewResponse } from '../view.js';
+import { minifiedResult, toolAnnotations } from '@chrischall/mcp-utils';
 import { asBoolean } from '../jsonapi.js';
 const PAGE_SIZE_MAX = 50;
 /** Statuses that mean the client has nothing left to do. */
@@ -19,7 +20,11 @@ export function registerDocumentTools(server, client) {
                 .default(false)
                 .describe('Include the full document body/questions. Off by default — these are long.'),
         },
-    }, async ({ outstandingOnly, pageSize, includeBody }) => {
+    }, 
+    // 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 } = await client.list('/document-requests', {
             page: { size: pageSize },
         });
@@ -46,7 +51,7 @@ export function registerDocumentTools(server, client) {
             }
             return base;
         });
-        return textResult({
+        return minifiedResult({
             count: items.length,
             outstanding: records.filter((r) => !SETTLED.has(String(r.status))).length,
             welcomeText: meta?.welcomeText ?? null,
@@ -56,13 +61,24 @@ export function registerDocumentTools(server, client) {
     server.registerTool('simplepractice_get_document_request', {
         description: 'One document request in full, including its body or its questions and the answers already given.',
         annotations: toolAnnotations({ readOnly: true }),
-        inputSchema: { id: z.string().min(1).describe('The document request id.') },
-    }, async ({ id }) => {
+        inputSchema: {
+            id: z.string().min(1).describe('The document request id.'),
+            view: viewArg(),
+        },
+    }, 
+    // `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 client.list(`/document-requests/${encodeURIComponent(id)}`);
         const record = records[0];
         if (!record)
-            return textResult({ found: false, id });
-        return textResult({
+            return minifiedResult({ found: false, id });
+        // The record goes out verbatim — a consent form, a questionnaire and a
+        // Good Faith Estimate are different shapes under one endpoint, so there
+        // is no field list to pick. Compact strips the practice logo and
+        // clinician avatars these carry; `hasDocumentPdf` is a fact about the
+        // document, not a media key, and survives.
+        return viewResponse(view, {
             ...record,
             hasDocumentPdf: asBoolean(record.hasDocumentPdf) ?? false,
         });
@@ -73,19 +89,31 @@ export function registerDocumentTools(server, client) {
         inputSchema: {
             pageSize: z.number().int().positive().max(PAGE_SIZE_MAX).default(PAGE_SIZE_MAX),
         },
-    }, async ({ pageSize }) => {
+    }, 
+    // 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 client.list('/documents', { page: { size: pageSize } });
-        return textResult({ count: records.length, documents: records });
+        return minifiedResult({ count: records.length, documents: records });
     });
     server.registerTool('simplepractice_list_announcements', {
         description: 'Announcements the practice has posted to the Client Portal. readAt is null on unread ones.',
         annotations: toolAnnotations({ readOnly: true }),
         inputSchema: {
             pageSize: z.number().int().positive().max(PAGE_SIZE_MAX).default(PAGE_SIZE_MAX),
+            view: viewArg(),
         },
-    }, async ({ pageSize }) => {
+    }, async ({ pageSize, view }) => {
         const { records } = await client.list('/announcements', { page: { size: pageSize } });
-        return textResult({
+        // Verbatim upstream records again. An announcement is text the practice
+        // posted, so its banner and author avatar are decoration a model cannot
+        // see — and `readAt: null` is data, which this rung leaves alone (it
+        // drops media keys, never nulls), so the unread count above stays
+        // reconcilable against the rows below it.
+        return viewResponse(view, {
             count: records.length,
             unread: records.filter((r) => r.readAt === null || r.readAt === undefined).length,
             announcements: records,

package/dist/version.js

@@ -2,4 +2,4 @@
  * Single source of truth for the server version. release-please rewrites the
  * literal below; every other file imports VERSION rather than repeating it.
  */
-export const VERSION = '0.3.0'; // x-release-please-version
+export const VERSION = '0.4.1'; // x-release-please-version

package/dist/view.js

@@ -0,0 +1,37 @@
+import { minifiedResult, resolveView, stripMediaUrls, viewParam } from '@chrischall/mcp-utils';
+/**
+ * The rungs this server honours (`@chrischall/mcp-utils`' `view` vocabulary;
+ * `chrischall/workflows` `docs/fleet-conventions.md`, "Response shape").
+ *
+ * A GROUNDED repo: it already had a field projection, and it was opt-in —
+ * `compact: false`, so the caller had to know the slim rung existed and ask
+ * for it. An efficiency that has to be requested is one that usually is not,
+ * and the caller paying for it is the one least able to know.
+ *
+ * `compact` is the default now. SimplePractice payloads that have no projection get
+ * media stripping instead, which needs no knowledge of the shape.
+ *
+ * A hand-written projection is NOT then media-stripped. Its field choices were
+ * made WITH knowledge of the API; running a blind subtractive rule over its
+ * output would let an un-grounded rule overrule a grounded one — which bit
+ * viator-mcp, where the projection deliberately keeps a cover image.
+ *
+ * No `raw` rung: `full` already returns the untouched upstream payload.
+ */
+export const SP_VIEWS = ['compact', 'full'];
+const NOTE = 'compact returns the slim projection where one exists and strips image URLs elsewhere; ' +
+    '"full" returns SimplePractice\'s whole records.';
+/** The `view` parameter every read tool in this server takes. */
+export const viewArg = () => viewParam(SP_VIEWS, { note: NOTE });
+/** Is this call asking for the slim rung? Replaces the old `compact` boolean. */
+export function isCompact(view) {
+    const rung = resolveView(view, SP_VIEWS);
+    return rung === 'compact';
+}
+/**
+ * Answer a payload that has NO hand-written projection: compact strips media,
+ * full passes through.
+ */
+export function viewResponse(view, data) {
+    return minifiedResult(isCompact(view) ? stripMediaUrls(data) : data);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simplepractice-mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "license": "MIT",
   "mcpName": "io.github.chrischall/simplepractice-mcp",
   "description": "SimplePractice Client Portal MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -34,7 +34,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.19.3",
+    "@chrischall/mcp-utils": "^0.23.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/simplepractice-mcp",
     "source": "github"
   },
-  "version": "0.3.0",
+  "version": "0.4.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "simplepractice-mcp",
-      "version": "0.3.0",
+      "version": "0.4.1",
       "transport": {
         "type": "stdio"
       },

package/skills/simplepractice/SKILL.md

@@ -53,18 +53,89 @@ again; that means another email.
   several people (a parent for two children), so confirm *whose* record you
   are about to report on before you report on it. It also returns the
   practice's real cancellation policy and the client's feature permissions.
-- `simplepractice_list_appointments` — `status: "scheduled"` for confirmed and
+- `simplepractice_list_appointments(status?, page?, pageSize?, view?)` — `status: "scheduled"` for confirmed and
   upcoming, `"requested"` for ones the practice has not confirmed yet.
 - `simplepractice_list_document_requests` — paperwork. `outstandingOnly: true`
   answers "is anything waiting for me?", which is the usual question.
-- `simplepractice_get_billing_overview` — balance due and per-category counts.
+- `simplepractice_get_billing_overview(view?)` — balance due and per-category counts.
   Cheaper than listing the billing collections to find out they are empty.
-- `simplepractice_list_billing_items` — invoices, statements, **superbills**
+- `simplepractice_list_billing_items(kind?, before?, pageSize?, view?)` — invoices, statements, **superbills**
   (the receipt to claim out-of-network insurance), receipts, or account
   history. Pages by cursor: pass the returned `nextCursor` back as `before`.
 - `simplepractice_list_payment_methods`, `simplepractice_list_documents`,
   `simplepractice_list_announcements`.
 
+## Response shape (`view`)
+
+Five of the reads take `view: "compact" | "full"`, and **`compact` is the
+default**: `simplepractice_list_appointments`,
+`simplepractice_list_billing_items`, `simplepractice_get_billing_overview`,
+`simplepractice_get_document_request` and
+`simplepractice_list_announcements`.
+
+That default is the point of the parameter. This rung used to be a
+`compact: false` boolean — opt-in, so a caller had to know the slim shape
+existed and ask for it. An efficiency that has to be requested is one that
+usually is not, and the caller paying for it is the one least able to know.
+
+**Compact is not one thing here.** One of the tools gets a real field
+projection; the other four get media stripping and no field projection at all,
+and the difference matters because expecting a named field set from the second
+group would be expecting something that was never going to be there.
+
+- **`simplepractice_list_appointments` is projected**, down to
+  `{id, startTime, endTime, service, clinician, location, videoRoomUrl,
+  confirmationStatus, clientConfirmationStatus, isCancellable, fee}`.
+  `clinician` is the first and last name JOINED into one string, and
+  `location` collapses the office record to `"telehealth"` or
+  `"name, city, state"` — so if you are reaching for `clinician.firstName` or
+  the `office` object, they are on `full` only.
+- **`list_billing_items`, `get_billing_overview`, `get_document_request` and
+  `list_announcements` are media-stripped only.** No field projection is
+  claimed, and that is deliberate rather than unfinished: `billing-items` is
+  one polymorphic collection switched five ways (`invoice`, `statement`,
+  `superbill`, `receipt`, account history), and a field list picked for an
+  invoice would quietly drop half of a superbill. The same is true of
+  `document-requests`, where a consent form, a questionnaire and a Good Faith
+  Estimate are different shapes under one endpoint. What compact takes is the
+  practice logo and the clinician avatars; it touches nothing whose key names
+  an amount, a date, or a document link.
+
+One consequence worth knowing on announcements: the rung drops media keys,
+never nulls. `readAt: null` is data — it is what "unread" means — so it
+survives, and the `unread` count stays reconcilable against the rows beneath
+it.
+
+`view: "full"` returns SimplePractice's whole record. There is **no `raw`
+rung**: `full` already IS the untouched upstream payload, so a third value
+could only alias it. And `view` never reaches SimplePractice — it is
+destructured off before the request is built, because `client.list` turns
+whatever it is handed into a JSON:API query string and a stray `view=compact`
+would arrive as a filter SimplePractice never defined.
+
+The other ten tools take no `view`, and each has its own reason:
+
+- **`simplepractice_get_account`, `simplepractice_list_document_requests` and
+  `simplepractice_list_payment_methods` are ALREADY hand-written
+  projections** — every field on them was picked by name with knowledge of the
+  payload. There is no un-projected shape left underneath, so a `view` there
+  would be a parameter that changes nothing, and running a blind rung over that
+  output would let an un-grounded rule overrule a grounded one.
+  (`list_document_requests` also takes `includeBody`, a field the caller
+  explicitly asked for; a blind rung could only take back something chosen on
+  purpose.)
+- **`simplepractice_list_documents` is the exception worth stating**: its
+  PRODUCT is the file references. 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 not shrink the answer, it would
+  empty exactly the rows you came for.
+- **`simplepractice_session_status` and `simplepractice_healthcheck`** answer
+  with status, not records.
+- **`simplepractice_request_sign_in_link`, `simplepractice_verify_sign_in_pin`,
+  `simplepractice_verify_sign_in_token` and `simplepractice_sign_out`** are
+  writes. A write's response is a receipt, with nothing to strip and everything
+  to keep.
+
 ## Reading the results honestly
 
 - **An empty billing list is a real answer.** Plenty of practices invoice