simplepractice-mcp 0.2.0 → 0.4.0

package/dist/client.js

@@ -1,6 +1,6 @@
 import { McpToolError, messageOf, truncateErrorMessage } from '@chrischall/mcp-utils';
 import { SessionStore } from '@chrischall/mcp-utils/session';
-import { API_NAMESPACE, API_VERSION, APPLICATION_BUILD_VERSION, APPLICATION_PLATFORM, readPortalHost, sessionFilePath, } from './config.js';
+import { API_NAMESPACE, API_VERSION, APPLICATION_BUILD_VERSION, APPLICATION_PLATFORM, readPortalHost, resolvePortalHost, sessionFilePath, } from './config.js';
 import { flattenDocument, formatJsonApiErrors, } from './jsonapi.js';
 const JSON_API_MEDIA_TYPE = 'application/vnd.api+json';
 export function buildQuery(params) {
@@ -21,21 +21,11 @@ export function buildQuery(params) {
 }
 export class SimplePracticeClient {
     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();
-        // Deferred-config-error: the server must still boot (and answer the host's
-        // install-time tools/list probe) with no configuration; the error surfaces
-        // on the first tool call instead.
-        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 — 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({
@@ -44,19 +34,132 @@ export class SimplePracticeClient {
                     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 — 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 — 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();
@@ -65,8 +168,11 @@ export class SimplePracticeClient {
         return session;
     }
     clearSession() {
-        const host = this.requireConfig();
-        return this.store.remove(host);
+        const host = this.knownPortalHost();
+        // Not knowing the practice is the same outcome as having no session for
+        // it: nothing to sign out of. Throwing would make sign-out the one tool
+        // that fails when it has nothing to do.
+        return host ? this.store.remove(host) : false;
     }
     requireSession() {
         const session = this.getSession();
@@ -76,7 +182,7 @@ export class SimplePracticeClient {
             // the two-step remediation below is worth more here than the class name —
             // nothing in this server discriminates on the type.
             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 — 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;
@@ -111,7 +217,9 @@ export class SimplePracticeClient {
             });
         }
         catch (err) {
-            throw new McpToolError(`Could not reach ${host}: ${truncateErrorMessage(messageOf(err))}`, { hint: 'Check the practice address in SIMPLEPRACTICE_PRACTICE and your network connection.' });
+            throw new McpToolError(`Could not reach ${host}: ${truncateErrorMessage(messageOf(err))}`, {
+                hint: `Check your network connection, and that ${host} is really your practice's portal — simplepractice_session_status reports where that address came from.`,
+            });
         }
         const raw = await response.text();
         let document = null;

package/dist/config.js

@@ -15,13 +15,17 @@ export const APPLICATION_PLATFORM = 'web';
 export const API_NAMESPACE = 'client-portal-api';
 const PORTAL_DOMAIN = 'clientsecure.me';
 /**
- * Resolve the practice's portal host from `SIMPLEPRACTICE_PRACTICE`, which
- * accepts either the bare slug (`achievebalancetherapy`) or the full host
- * (`achievebalancetherapy.clientsecure.me`) — users copy whichever half of the
- * link they happen to have.
+ * Resolve a practice's portal host from anything a user might hand over: the
+ * bare slug (`achievebalancetherapy`), the full host, or a pasted URL — they
+ * copy whichever half of the link they happen to have.
  *
- * Returns `null` rather than throwing so the server still boots without
- * configuration and reports the problem on the first tool call.
+ * The single gate on which hosts this server will talk to, so both routes in
+ * (`SIMPLEPRACTICE_PRACTICE` and {@link practiceHostFromLink}) go through it:
+ * a value outside `*.clientsecure.me`, or a nested subdomain under it, would
+ * otherwise be enough to aim a session cookie at a stranger's domain.
+ *
+ * Returns `null` rather than throwing so the server still boots knowing no
+ * practice — the ordinary first-run state — and reports it on the first call.
  */
 export function resolvePortalHost(raw) {
     if (!raw)
@@ -42,6 +46,37 @@ export function resolvePortalHost(raw) {
         return null;
     return value;
 }
+/**
+ * The practice named by an emailed sign-in link.
+ *
+ * The link is `https://<practice>.clientsecure.me/sign-in/token#<TOKEN>`, so
+ * the practice is already in the user's hands the moment they have a link to
+ * paste — which is why `SIMPLEPRACTICE_PRACTICE` is an override rather than a
+ * requirement.
+ *
+ * Returns `null` when the link names no practice, which is not an error:
+ * SimplePractice's mobile variant points at the bare apex
+ * (`https://clientsecure.me/client-portal-api/sign-in/token#<TOKEN>`), and the
+ * caller may equally have pasted a bare token.
+ *
+ * Only text with a `#` is considered — that is the shape of a link, and a bare
+ * TOKEN must never be read as a host: `resolvePortalHost` slug-expands, so
+ * `abc123` would otherwise resolve to `abc123.clientsecure.me` and the sign-in
+ * POST would carry the token to a stranger's subdomain. The same reasoning
+ * rules out slug-expanding the text in front of the fragment, so a link has to
+ * spell out a host that is already under the portal apex.
+ */
+export function practiceHostFromLink(raw) {
+    if (!raw)
+        return null;
+    const hash = raw.indexOf('#');
+    if (hash < 0)
+        return null;
+    const prefix = raw.slice(0, hash).trim();
+    if (!prefix.includes('.'))
+        return null;
+    return resolvePortalHost(prefix);
+}
 export function readPortalHost() {
     return resolvePortalHost(readEnvVar('SIMPLEPRACTICE_PRACTICE'));
 }

package/dist/index.js

@@ -7,9 +7,11 @@ import { registerAccountTools } from './tools/account.js';
 import { registerAppointmentTools } from './tools/appointments.js';
 import { registerBillingTools } from './tools/billing.js';
 import { registerDocumentTools } from './tools/documents.js';
+import { registerHealthcheckTools } from './tools/health.js';
 // Built in the caller so the deferred-config-error pattern holds: the server
-// still boots, and answers the host's install-time tools/list probe, with no
-// SIMPLEPRACTICE_PRACTICE set. The error surfaces on the first tool call.
+// still boots, and answers the host's install-time tools/list probe, knowing no
+// practice — which is the ordinary first-run state, since the practice arrives
+// with the sign-in link rather than from the environment.
 const client = new SimplePracticeClient();
 await runMcp({
     name: 'simplepractice-mcp',
@@ -22,5 +24,6 @@ await runMcp({
         registerAppointmentTools,
         registerBillingTools,
         registerDocumentTools,
+        registerHealthcheckTools,
     ],
 });

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,18 +1,35 @@
 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, and for which practice. Reads local state only — 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 — makes no network call.',
         annotations: toolAnnotations({ readOnly: true }),
         inputSchema: {},
     }, async () => {
-        const host = client.portalHost();
+        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.
+            practiceSource: client.practiceSource(),
             signedIn: session !== null,
             signedInAt: session?.createdAt ?? null,
+            ...(host
+                ? {}
+                : {
+                    next: 'Paste the sign-in link your provider emailed into simplepractice_verify_sign_in_token — its address names the practice. Or set SIMPLEPRACTICE_PRACTICE to pin this server to one.',
+                }),
         });
     });
     server.registerTool('simplepractice_request_sign_in_link', {
@@ -20,29 +37,43 @@ export function registerAuthTools(server, client) {
         annotations: toolAnnotations({ readOnly: false, idempotent: false }),
         inputSchema: {
             email: z.string().email().describe('The email address the Client Portal is registered to.'),
+            practice: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('The practice whose portal to sign in to — 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, confirm }) => {
+    }, async ({ email, practice, confirm }) => {
         if (!confirm) {
-            return textResult({
+            return minifiedResult({
                 dryRun: true,
                 wouldSend: 'a Client Portal sign-in email',
                 to: email,
-                practiceHost: client.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 ? client.validatePracticeHost(practice) : client.portalHost(),
                 note: 'Re-run with confirm:true to actually send it. Do not retry a failed send — SimplePractice locks out repeated sign-in requests.',
             });
         }
-        const { expiresIn } = await requestSignInLink(client, email);
-        return textResult({
-            sent: true,
-            to: email,
-            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(client, email);
+            return minifiedResult({
+                sent: true,
+                to: email,
+                practiceHost: client.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.',
+            });
+        };
+        // Scoped exactly as the sign-in exchange is: the practice sticks only if
+        // the send works, so a rejected send leaves the previous one standing.
+        return practice ? client.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: z
@@ -50,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 }),
@@ -58,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,