simplepractice-mcp 0.0.0

package/dist/client.js

@@ -0,0 +1,177 @@
+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 { flattenDocument, formatJsonApiErrors, } from './jsonapi.js';
+const JSON_API_MEDIA_TYPE = 'application/vnd.api+json';
+export function buildQuery(params) {
+    const pairs = [];
+    const push = (key, value) => pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        if (value !== null && typeof value === 'object') {
+            for (const [sub, subValue] of Object.entries(value))
+                push(`${key}[${sub}]`, subValue);
+        }
+        else {
+            push(key, value);
+        }
+    }
+    return pairs.join('&');
+}
+export class SimplePracticeClient {
+    store;
+    configError;
+    host;
+    fetchImpl;
+    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({
+                    filePath: sessionFilePath(),
+                    keyOf: (session) => session.host,
+                    normalizeKey: (key) => key.toLowerCase(),
+                });
+    }
+    /** Throws the deferred configuration error, if there is one. */
+    requireConfig() {
+        if (this.configError)
+            throw this.configError;
+        return this.host;
+    }
+    portalHost() {
+        return this.requireConfig();
+    }
+    getSession() {
+        if (this.configError)
+            return null;
+        return this.store.get(this.host);
+    }
+    saveSession(cookie) {
+        const host = this.requireConfig();
+        const session = { host, cookie, createdAt: new Date().toISOString() };
+        this.store.add(session);
+        return session;
+    }
+    clearSession() {
+        const host = this.requireConfig();
+        return this.store.remove(host);
+    }
+    requireSession() {
+        const session = this.getSession();
+        if (!session) {
+            // McpToolError rather than SessionNotAuthenticatedError: that subclass's
+            // constructor is (service, signInHost) and composes its own message, and
+            // 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.',
+            });
+        }
+        return session;
+    }
+    headers(session, hasBody) {
+        const headers = {
+            'Api-Version': API_VERSION,
+            // Omitting this is a hard 400 from the API, not a soft default.
+            'Application-Build-Version': APPLICATION_BUILD_VERSION,
+            'Application-Platform': APPLICATION_PLATFORM,
+            Accept: JSON_API_MEDIA_TYPE,
+        };
+        if (hasBody)
+            headers['Content-Type'] = JSON_API_MEDIA_TYPE;
+        if (session)
+            headers.Cookie = session.cookie;
+        return headers;
+    }
+    /** One central place every request goes through. Returns the raw document. */
+    async request(path, options = {}) {
+        const host = this.requireConfig();
+        const session = options.anonymous ? null : this.requireSession();
+        const query = options.query ? buildQuery(options.query) : '';
+        const url = `https://${host}/${API_NAMESPACE}${path}${query ? `?${query}` : ''}`;
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method: options.method ?? 'GET',
+                headers: this.headers(session, options.body !== undefined),
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                redirect: 'manual',
+            });
+        }
+        catch (err) {
+            throw new McpToolError(`Could not reach ${host}: ${truncateErrorMessage(messageOf(err))}`, { hint: 'Check the practice address in SIMPLEPRACTICE_PRACTICE and your network connection.' });
+        }
+        const raw = await response.text();
+        let document = null;
+        try {
+            document = raw ? JSON.parse(raw) : {};
+        }
+        catch {
+            document = null;
+        }
+        if (!response.ok)
+            this.throwForStatus(response.status, document);
+        if (document === null) {
+            // The portal's SPA catch-all answers 200 text/html for ANY path the API
+            // does not define, so this is as often a wrong path as a dead session —
+            // saying only "sign in again" sent a real investigation down the wrong
+            // road once already.
+            throw new McpToolError(`SimplePractice returned HTML rather than JSON for ${path}.`, {
+                hint: 'Either the session expired (sign in again), or that path is not an API endpoint — the portal serves its app shell with HTTP 200 for unknown paths.',
+            });
+        }
+        return { document, setCookie: readSetCookie(response) };
+    }
+    /**
+     * The id of the client whose data the portal is currently showing. Needed
+     * because billing overview and saved cards are relationships ON the client
+     * record, not collections of their own — `/client-billing-overviews` and
+     * `/cards` are not API paths at all (they fall through to the SPA shell).
+     */
+    async currentClientId() {
+        const { records } = await this.list('/environment', { include: 'currentClient' });
+        const current = records[0]?.currentClient;
+        return current?.id ?? null;
+    }
+    /** GET returning flattened records plus the document `meta`. */
+    async list(path, query) {
+        const { document } = await this.request(path, { query });
+        return flattenDocument(document);
+    }
+    throwForStatus(status, document) {
+        const message = formatJsonApiErrors(document, status);
+        if (status === 401 || status === 403) {
+            throw new McpToolError(message, {
+                hint: 'The portal session has expired — there is no refresh token, so sign in again with simplepractice_request_sign_in_link.',
+            });
+        }
+        if (status === 429) {
+            // The two titles are distinct limits and both are punishing; a retry loop
+            // here would lock the account out of the only auth path it has.
+            throw new McpToolError(message, {
+                hint: 'SimplePractice rate-limits sign-in requests per email and per IP. Do not retry — wait before asking for another link.',
+            });
+        }
+        throw new McpToolError(message);
+    }
+}
+/** `getSetCookie()` where available, falling back to the joined header. */
+export function readSetCookie(response) {
+    const headers = response.headers;
+    if (typeof headers.getSetCookie === 'function')
+        return headers.getSetCookie();
+    const joined = headers.get('set-cookie');
+    return joined ? [joined] : [];
+}

package/dist/config.js

@@ -0,0 +1,58 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { expandPath, readEnvVar } from '@chrischall/mcp-utils';
+/** The API contract version the Client Portal app currently sends. */
+export const API_VERSION = '2026-05-25';
+/**
+ * The portal app reports itself as build `0.0.0`. The API only checks that the
+ * header is PRESENT — it answers
+ * `400 {"title":"Application build version is missing"}` when omitted — so this
+ * is a required constant rather than anything version-like of ours.
+ */
+export const APPLICATION_BUILD_VERSION = '0.0.0';
+export const APPLICATION_PLATFORM = 'web';
+/** Every Client Portal API path hangs off this namespace. */
+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.
+ *
+ * Returns `null` rather than throwing so the server still boots without
+ * configuration and reports the problem on the first tool call.
+ */
+export function resolvePortalHost(raw) {
+    if (!raw)
+        return null;
+    let value = raw.trim().toLowerCase();
+    if (!value)
+        return null;
+    value = value.replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+    if (!value)
+        return null;
+    if (!value.includes('.'))
+        value = `${value}.${PORTAL_DOMAIN}`;
+    if (!value.endsWith(`.${PORTAL_DOMAIN}`))
+        return null;
+    // Reject anything that is not a single practice label under the apex.
+    const label = value.slice(0, -(PORTAL_DOMAIN.length + 1));
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(label))
+        return null;
+    return value;
+}
+export function readPortalHost() {
+    return resolvePortalHost(readEnvVar('SIMPLEPRACTICE_PRACTICE'));
+}
+/**
+ * Where the session cookie is persisted. Deliberately NOT the path the
+ * `simplepractice-fpx` skill uses (`~/.simplepractice-cookies`): the two hold
+ * different formats, and sharing a path would have each corrupt the other.
+ */
+export function sessionFilePath() {
+    const override = readEnvVar('SIMPLEPRACTICE_SESSION_FILE');
+    if (override)
+        return expandPath(override);
+    return join(homedir(), '.simplepractice-mcp', 'session.json');
+}

package/dist/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { runMcp } from '@chrischall/mcp-utils';
+import { VERSION } from './version.js';
+import { SimplePracticeClient } from './client.js';
+import { registerAuthTools } from './tools/auth.js';
+import { registerAccountTools } from './tools/account.js';
+import { registerAppointmentTools } from './tools/appointments.js';
+import { registerBillingTools } from './tools/billing.js';
+import { registerDocumentTools } from './tools/documents.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.
+const client = new SimplePracticeClient();
+await runMcp({
+    name: 'simplepractice-mcp',
+    version: VERSION,
+    banner: '[simplepractice-mcp] This project was developed and is maintained by AI. Use at your own discretion.',
+    deps: client,
+    tools: [
+        registerAuthTools,
+        registerAccountTools,
+        registerAppointmentTools,
+        registerBillingTools,
+        registerDocumentTools,
+    ],
+});

package/dist/jsonapi.js

@@ -0,0 +1,91 @@
+/**
+ * JSON:API helpers.
+ *
+ * `flattenJsonApi` in @chrischall/mcp-utils merges `attributes` into the record
+ * but does not resolve `included[]`, and the Client Portal leans on `include=`
+ * for everything worth reading (an appointment without its clinician and office
+ * is not useful). So relationship resolution lives here.
+ */
+/**
+ * Parse a field the API sends as a JSON *string* rather than an object — the
+ * client's `permissions` blob is one (`'{"messaging":true,…}'`). Returns null
+ * rather than throwing: a portal that starts sending a real object, or none at
+ * all, must not break the account tool.
+ */
+export function parseJsonString(value) {
+    if (value !== null && typeof value === 'object')
+        return value;
+    if (typeof value !== 'string')
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        return parsed !== null && typeof parsed === 'object'
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `"true"`/`"false"` arrive as STRINGS on the wire — see `hasDocumentPdf`. */
+export function asBoolean(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return undefined;
+}
+function flattenOne(resource) {
+    return { id: resource.id, type: resource.type, ...(resource.attributes ?? {}) };
+}
+function indexIncluded(included) {
+    const index = new Map();
+    for (const resource of included) {
+        if (resource.type && resource.id)
+            index.set(`${resource.type}:${resource.id}`, resource);
+    }
+    return index;
+}
+function resolveRef(ref, index) {
+    if (!ref || typeof ref !== 'object')
+        return null;
+    const { type, id } = ref;
+    if (!type || !id)
+        return null;
+    const hit = index.get(`${type}:${id}`);
+    // A relationship whose record was not asked for via `include=` still tells us
+    // the id — surfacing that beats dropping the field entirely.
+    return hit ? flattenOne(hit) : { id, type };
+}
+/**
+ * Flatten a JSON:API document into plain records, splicing each `include`d
+ * relationship in beside the attributes under its relationship name.
+ */
+export function flattenDocument(doc) {
+    const index = indexIncluded(doc.included ?? []);
+    const list = Array.isArray(doc.data) ? doc.data : doc.data ? [doc.data] : [];
+    const records = list.map((resource) => {
+        const flat = flattenOne(resource);
+        for (const [name, rel] of Object.entries(resource.relationships ?? {})) {
+            const ref = rel?.data;
+            if (ref === undefined)
+                continue;
+            flat[name] = Array.isArray(ref)
+                ? ref.map((r) => resolveRef(r, index)).filter((r) => r !== null)
+                : resolveRef(ref, index);
+        }
+        return flat;
+    });
+    return doc.meta ? { records, meta: doc.meta } : { records };
+}
+/** Render `.errors[]` into one line, for an McpToolError message. */
+export function formatJsonApiErrors(doc, status) {
+    const errors = doc?.errors;
+    if (!errors?.length)
+        return `SimplePractice returned HTTP ${status}`;
+    return errors
+        .map((e) => [e.title, e.detail].filter(Boolean).join(': ') || `HTTP ${e.status ?? status}`)
+        .join('; ');
+}

package/dist/tools/account.js

@@ -0,0 +1,48 @@
+import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { parseJsonString } from '../jsonapi.js';
+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.',
+        annotations: toolAnnotations({ readOnly: true }),
+        inputSchema: {},
+    }, async () => {
+        const { records } = await client.list('/environment', {
+            include: 'currentPractice,currentClient,currentClientOptions,currentClientAccess',
+        });
+        const environment = records[0] ?? {};
+        const practice = environment.currentPractice;
+        const currentClient = environment.currentClient;
+        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({
+            practice: practice && {
+                id: practice.id,
+                name: practice.fullName,
+                timeZone: practice.timeZone,
+                phone: practice.phoneNumber,
+                currency: practice.currency,
+                isGroupPractice: practice.isGroupPractice,
+                telehealthEnabled: practice.telehealthEnabled,
+                selfSchedulingEnabled: practice.selfSchedulingEnabled,
+                // The practice's actual cancellation policy — read this before
+                // telling anyone an appointment can be cancelled.
+                clientMayCancelAppointments: practice.isClientAllowedToCancelAppt,
+                clientMayConfirmAppointments: practice.isClientAllowedToConfirmAppt,
+                cancellationNoticeHours: practice.clientCancellableHrs,
+            },
+            currentClient: currentClient && {
+                id: currentClient.id,
+                name: name(currentClient),
+                status: currentClient.status,
+                hasIncompleteDocument: currentClient.hasIncompleteDocument,
+                hasNewAnnouncements: currentClient.hasNewAnnouncements,
+                // Sent as a JSON *string*, not an object — and it decides which
+                // portal features this client actually has, so a caller that reads
+                // it raw gets a string of characters instead of the flags.
+                permissions: parseJsonString(currentClient.permissions),
+            },
+            clients: options.map((c) => ({ id: c.id, name: name(c) })),
+        });
+    });
+}

package/dist/tools/appointments.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+const PAGE_SIZE_MAX = 50;
+function compactAppointment(a) {
+    const clinician = a.clinician;
+    const office = a.office;
+    return {
+        id: a.id,
+        startTime: a.startTime,
+        endTime: a.endTime,
+        service: a.serviceDescription,
+        clinician: clinician && [clinician.firstName, clinician.lastName].filter(Boolean).join(' '),
+        location: office?.isVideo
+            ? 'telehealth'
+            : office && [office.name, office.city, office.state].filter(Boolean).join(', '),
+        videoRoomUrl: a.videoRoomUrl,
+        confirmationStatus: a.confirmationStatus,
+        clientConfirmationStatus: a.clientConfirmationStatus,
+        isCancellable: a.isCancellable,
+        fee: a.fee,
+    };
+}
+export function registerAppointmentTools(server, client) {
+    server.registerTool('simplepractice_list_appointments', {
+        description: 'Appointments from the Client Portal. status "scheduled" returns confirmed/upcoming ones; "requested" returns those still awaiting the practice\'s confirmation. Pages by number.',
+        annotations: toolAnnotations({ readOnly: true }),
+        inputSchema: {
+            status: z
+                .enum(['scheduled', 'requested'])
+                .default('scheduled')
+                .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.'),
+        },
+    }, async ({ status, page, pageSize, compact }) => {
+        const { records } = await client.list('/appointments', {
+            include: 'clinician,office,client',
+            filter: { hasPendingConfirmation: status === 'requested' },
+            page: { number: page, size: pageSize },
+        });
+        return textResult({
+            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,
+        });
+    });
+}

package/dist/tools/auth.js

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations, schemaConfirm } from '@chrischall/mcp-utils';
+import { requestSignInLink, verifySignInPin, verifySignInToken } from '../auth.js';
+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.',
+        annotations: toolAnnotations({ readOnly: true }),
+        inputSchema: {},
+    }, async () => {
+        const host = client.portalHost();
+        const session = client.getSession();
+        return textResult({
+            practiceHost: host,
+            signedIn: session !== null,
+            signedInAt: session?.createdAt ?? null,
+        });
+    });
+    server.registerTool('simplepractice_request_sign_in_link', {
+        description: 'Ask SimplePractice to email a sign-in link to a Client Portal address. The portal has no password — this is how you sign in. Sends a real email and is rate-limited per email address AND per IP, so it requires confirm:true. A success does not prove the address has an account: the API answers identically for unknown addresses by design.',
+        annotations: toolAnnotations({ readOnly: false, idempotent: false }),
+        inputSchema: {
+            email: z.string().email().describe('The email address the Client Portal is registered to.'),
+            confirm: schemaConfirm,
+        },
+    }, async ({ email, confirm }) => {
+        if (!confirm) {
+            return textResult({
+                dryRun: true,
+                wouldSend: 'a Client Portal sign-in email',
+                to: email,
+                practiceHost: 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.',
+        });
+    });
+    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.',
+        annotations: toolAnnotations({ readOnly: false, idempotent: false }),
+        inputSchema: {
+            link: z
+                .string()
+                .min(1)
+                .describe('The sign-in link from the email, or just the token after the "#".'),
+        },
+    }, async ({ link }) => textResult(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 }),
+        inputSchema: {
+            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)));
+    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() }));
+}

package/dist/tools/billing.js

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { asBoolean } from '../jsonapi.js';
+const PAGE_SIZE_MAX = 50;
+/**
+ * `billing-items` is one polymorphic collection switched by `filter[thisType]`.
+ * Account history is the odd one out: two types at once, plus a condition.
+ */
+const KINDS = {
+    invoice: { thisType: 'invoice' },
+    statement: { thisType: 'statement' },
+    superbill: { thisType: 'superbill' },
+    receipt: { thisType: 'receipt' },
+    'account-history': { thisType: 'billable-item,payment', thisTypeCondition: 'unallocated' },
+};
+/**
+ * Read one relationship off the current client record.
+ *
+ * Billing overview and saved cards hang off `/clients/<id>` via `include=`;
+ * there is no `/client-billing-overviews` or `/cards` collection. Asking for
+ * one gets HTTP 200 and the Ember app shell, which reads like success.
+ */
+async function loadClientRelationship(client, relationship) {
+    const id = await client.currentClientId();
+    if (id === null)
+        return null;
+    const { records } = await client.list(`/clients/${encodeURIComponent(id)}`, {
+        include: relationship,
+    });
+    return records[0]?.[relationship] ?? null;
+}
+export function registerBillingTools(server, client) {
+    server.registerTool('simplepractice_list_billing_items', {
+        description: 'Invoices, statements, superbills, receipts, or account history from the Client Portal. An empty list is a real answer — many practices bill entirely outside the portal. Pages by cursor: pass the returned nextCursor as "before".',
+        annotations: toolAnnotations({ readOnly: true }),
+        inputSchema: {
+            kind: z
+                .enum(['invoice', 'statement', 'superbill', 'receipt', 'account-history'])
+                .default('invoice'),
+            before: z
+                .string()
+                .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),
+        },
+    }, async ({ kind, before, pageSize }) => {
+        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({
+            kind,
+            count: records.length,
+            endBalance: meta?.endBalance ?? null,
+            // The cursor is the row's cursorId, NOT its id.
+            nextCursor: records.length >= pageSize ? (last?.cursorId ?? null) : null,
+            items: records,
+        });
+    });
+    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 () => {
+        const overview = await loadClientRelationship(client, 'clientBillingOverview');
+        return textResult(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 () => {
+        const cards = await loadClientRelationship(client, 'cards');
+        const list = Array.isArray(cards) ? cards : [];
+        return textResult({
+            count: list.length,
+            paymentMethods: list.map((c) => ({
+                id: c.id,
+                brand: c.brand,
+                last4: c.last4,
+                expiry: c.expiry ?? [c.expMonth, c.expYear].filter(Boolean).join('/'),
+                // Another stringly-typed boolean, like hasDocumentPdf.
+                isDefault: asBoolean(c.isDefault) ?? false,
+            })),
+        });
+    });
+}