simplepractice-mcp 0.1.0 → 0.3.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;
@@ -122,7 +230,7 @@ export class SimplePracticeClient {
             document = null;
         }
         if (!response.ok)
-            this.throwForStatus(response.status, document);
+            this.throwForStatus(response.status, document, path);
         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 —
@@ -150,11 +258,18 @@ export class SimplePracticeClient {
         const { document } = await this.request(path, { query });
         return flattenDocument(document);
     }
-    throwForStatus(status, document) {
+    throwForStatus(status, document, path) {
         const message = formatJsonApiErrors(document, status);
+        // A 401 on the sign-in endpoints means the TOKEN was bad — most often
+        // already used, since they are single-use. Telling the caller their
+        // session expired there is simply the wrong diagnosis: they have no
+        // session yet, which is why they are signing in.
+        const isSignIn = path.startsWith('/sessions/') || path.startsWith('/sign-in-tokens');
         if (status === 401 || status === 403) {
             throw new McpToolError(message, {
-                hint: 'The portal session has expired — there is no refresh token, so sign in again with simplepractice_request_sign_in_link.',
+                hint: isSignIn
+                    ? 'Sign-in links and PINs are single-use and last 24 hours. Request a fresh one with simplepractice_request_sign_in_link.'
+                    : 'The portal session has expired — there is no refresh token, so sign in again with simplepractice_request_sign_in_link.',
             });
         }
         if (status === 429) {

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/auth.js

@@ -3,16 +3,24 @@ import { textResult, toolAnnotations, schemaConfirm } from '@chrischall/mcp-util
 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.',
+        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({
             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 +28,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({
                 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 textResult({
+                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

package/dist/tools/health.js

@@ -0,0 +1,103 @@
+import { registerCredentialHealthcheckTool } from '@chrischall/mcp-utils/healthcheck';
+/**
+ * `simplepractice_healthcheck` — the one call that answers "is this connector
+ * working?", and the only tool here that reports a failure as DATA rather
+ * than throwing.
+ *
+ * `simplepractice_session_status` is NOT this, and the difference is the
+ * reason this exists: its own description says it "reads local state only —
+ * makes no network call". So it reports `signedIn: true` for a session the
+ * portal has already killed. That is the worst shape of health signal — a
+ * confident yes that is wrong precisely when someone is asking because
+ * something is broken.
+ *
+ * This makes one authenticated round-trip, so `ok: true` means the portal
+ * accepted the session just now, not that a cookie exists on disk.
+ */
+/**
+ * Strings this classifier matches, kept as named constants because they are a
+ * CONTRACT WITH client.ts, not free text. `tests/health.test.ts` asserts each
+ * one still appears in that file: the first version of this classifier matched
+ * invented text that no code path ever produced, and every unit test passed
+ * because the tests fabricated errors to match the classifier instead of the
+ * client.
+ */
+export const CLIENT_ERROR_TEXT = {
+    /** From client.ts `requireConfig()` — thrown by `portalHost()`. */
+    noPractice: 'I do not know which practice portal to talk to yet',
+    /** From client.ts `throwForStatus()` 401/403, on the HINT — not the message. */
+    sessionExpired: 'The portal session has expired',
+    /** From client.ts `requireSession()`, on the MESSAGE. */
+    notSignedIn: 'Not signed in to the SimplePractice Client Portal',
+    /** From client.ts `throwForStatus()` 429, on the HINT. */
+    rateLimited: 'SimplePractice rate-limits sign-in requests',
+};
+export function classifySimplePracticeError(err) {
+    // The client raises McpToolError, which carries its remediation on `.hint`
+    // and a formatted JSON:API summary on `.message`. A 401 says nothing useful
+    // in the message, so BOTH must be searched — matching only `.message` is
+    // exactly the bug the auto-review on #13 caught.
+    const message = err instanceof Error ? err.message : String(err);
+    const hint = typeof err?.hint === 'string' ? err.hint : '';
+    const text = `${message}\n${hint}`;
+    if (text.includes(CLIENT_ERROR_TEXT.noPractice)) {
+        return {
+            kind: 'no_practice_host',
+            hint: 'No practice known yet. Paste the sign-in link your provider emailed into ' +
+                'simplepractice_verify_sign_in_token — its address names the practice, and this server remembers ' +
+                'it afterwards. SIMPLEPRACTICE_PRACTICE is optional, and only pins the server to one practice.',
+        };
+    }
+    // Rate limiting is checked BEFORE the session arms: a 429 is the far side
+    // working correctly, and this one is punishing — retrying can lock the
+    // account out of the only auth path it has.
+    if (text.includes(CLIENT_ERROR_TEXT.rateLimited)) {
+        return {
+            kind: 'rate_limited',
+            hint: 'SimplePractice rate-limits sign-in requests per email and per IP. The session is not necessarily bad — ' +
+                'do NOT retry, and wait before requesting another link.',
+        };
+    }
+    if (text.includes(CLIENT_ERROR_TEXT.sessionExpired) || text.includes(CLIENT_ERROR_TEXT.notSignedIn)) {
+        return {
+            kind: 'session_expired',
+            hint: 'The portal rejected the stored session. There is no refresh token, so it cannot be renewed silently: ' +
+                'run simplepractice_request_sign_in_link, then pass the part of the emailed link after the "#" to ' +
+                'simplepractice_verify_sign_in_token.',
+        };
+    }
+    return undefined;
+}
+export function registerHealthcheckTools(server, client) {
+    registerCredentialHealthcheckTool({
+        server,
+        prefix: 'simplepractice',
+        hostLabel: 'clientsecure.me',
+        probePath: '/environment',
+        resolveCredential: async () => {
+            const session = client.getSession();
+            // `source: null` short-circuits the probe. Without a session there is
+            // nothing to test, and probing anyway returns a failure that reads like
+            // a rejected session rather than an absent one.
+            return {
+                source: session ? 'portal_session' : null,
+                detail: {
+                    // `knownPortalHost`, not `portalHost`: the latter throws, and not
+                    // knowing the practice is the ordinary state before anyone has
+                    // pasted a sign-in link. A healthcheck that throws where it should
+                    // report `practice_host: null` fails at the one job it has — saying
+                    // which hop is broken.
+                    practice_host: client.knownPortalHost(),
+                    // When the session was minted — the fact that explains a connector
+                    // that worked yesterday and does not today. Never the cookie.
+                    signed_in_at: session?.createdAt ?? null,
+                },
+            };
+        },
+        // The cheapest authenticated read in the portal, and the one the client
+        // already uses to resolve the current client id. It changes nothing: no
+        // appointment booked, no document touched.
+        probeFn: () => client.list('/environment', { include: 'currentClient' }),
+        classifyThrown: classifySimplePracticeError,
+    });
+}

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.1.0'; // x-release-please-version
+export const VERSION = '0.3.0'; // x-release-please-version

package/mint.yaml

@@ -0,0 +1,74 @@
+# How this MCP wants to be hosted on mcp-host (see mcp-host/docs/HOSTING-MANIFEST.md).
+#
+# The FILENAME is load-bearing: mcp-host matches it exactly, against
+# MINT_MANIFEST_FILE in packages/core — `mint.yaml`, with the earlier
+# `mcp-host.yaml` still read as a deprecated fallback. A name the reader does
+# not expect is not an error; it is simply never found, and the registration
+# preview falls back to inference with nothing to notice. If this file ever
+# looks ignored, check that constant first rather than this comment.
+#
+# This file is a PROPOSAL, never an application. It is read at the resolved pin
+# and rendered for a human; nothing here changes a registration until an owner
+# saves it through the ordinary write path. It is NOT covered by the tarball
+# integrity check, so it carries no secrets and nothing that decides what runs.
+version: 1
+
+name: SimplePractice
+slug: simplepractice
+summary: >-
+  Read a SimplePractice Client Portal as one of a practice's clients —
+  appointments, billing, documents to sign, and announcements.
+
+env:
+  - name: SIMPLEPRACTICE_PRACTICE
+    secret: false
+    # Optional: the sign-in link a provider emails is
+    # https://<practice>.clientsecure.me/sign-in/token#<TOKEN>, so pasting it
+    # into simplepractice_verify_sign_in_token tells the server the practice —
+    # and the stored session remembers it. This only pins the server to one.
+    required: false
+    # No default: this names one specific practice's portal, so any value here
+    # would be wrong for everyone but its author.
+    help: >-
+      Optional. Pins this server to one practice's Client Portal — either the
+      slug ("achievebalancetherapy") or the full host
+      ("achievebalancetherapy.clientsecure.me"). Leave it unset and the
+      practice is taken from the sign-in link your provider emailed you.
+
+  - name: SIMPLEPRACTICE_SESSION_FILE
+    secret: false
+    required: false
+    # No default: the built-in one already resolves under $HOME, which the
+    # data dir below persists. Naming a path here would only risk pointing the
+    # session outside it.
+    help: >-
+      Where the signed-in portal session is kept (written 0600). Defaults to
+      $HOME/.simplepractice-mcp/session.json; leave unset unless you need it
+      somewhere specific.
+
+state:
+  dataDir: true
+  reason: >-
+    The portal session cookie is the only credential this server has, and
+    SimplePractice issues no refresh token. It is persisted under
+    $HOME/.simplepractice-mcp/session.json. Without a data dir every cold start
+    loses it, and recovering means a human requesting a fresh magic-link email
+    and pasting the link back in — so on a scale-to-zero machine the connector
+    would demand an inbox round-trip after nearly every idle period.
+
+identity:
+  # True because this server authenticates as its CALLER, not as the
+  # registration: there is no credential in the environment at all, and each
+  # caller signs in through the tools with a magic link mailed to their own
+  # address. One shared child would leave the first caller's portal session in
+  # place for every later caller to read — someone else's medical record. The
+  # uid and state dir per caller are worth that.
+  perUserChild: true
+
+egress:
+  # Every request goes to the practice's own portal host; the client builds
+  # exactly one URL template and there is no analytics, no CDN and no browser
+  # bridge. The bare apex is never called — only the practice subdomain.
+  # Honoured on the isolated tier, a proposal elsewhere.
+  allow:
+    - "*.clientsecure.me"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simplepractice-mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "license": "MIT",
   "mcpName": "io.github.chrischall/simplepractice-mcp",
   "description": "SimplePractice Client Portal MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -21,19 +21,20 @@
     ".claude-plugin",
     "skills",
     ".mcp.json",
-    "server.json"
+    "server.json",
+    "mint.yaml"
   ],
   "scripts": {
     "build": "tsc && npm run bundle",
     "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --banner:js='import { createRequire as __createRequire } from \"module\"; const require = __createRequire(import.meta.url);' --outfile=dist/bundle.js",
     "dev": "node --env-file=.env dist/index.js",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
+    "test": "npm run typecheck && vitest run",
+    "test:coverage": "npm run typecheck && vitest run --coverage",
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.15.0",
+    "@chrischall/mcp-utils": "^0.19.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
     "zod": "^4.4.3"
@@ -43,6 +44,7 @@
     "@vitest/coverage-v8": "^4.1.7",
     "esbuild": "^0.28.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.7",
+    "yaml": "^2.9.0"
   }
 }

package/server.json

@@ -6,20 +6,20 @@
     "url": "https://github.com/chrischall/simplepractice-mcp",
     "source": "github"
   },
-  "version": "0.1.0",
+  "version": "0.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "simplepractice-mcp",
-      "version": "0.1.0",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       },
       "environmentVariables": [
         {
           "name": "SIMPLEPRACTICE_PRACTICE",
-          "description": "Your practice's Client Portal address — the slug (\"achievebalancetherapy\") or the full host (\"achievebalancetherapy.clientsecure.me\").",
-          "isRequired": true,
+          "description": "Optional. Pins the server to one practice — the slug (\"achievebalancetherapy\") or the full host. Unset, the practice comes from your emailed sign-in link.",
+          "isRequired": false,
           "format": "string"
         },
         {