simplepractice-mcp 0.2.0 → 0.4.0

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

package/dist/view.js

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

package/mint.yaml

@@ -22,14 +22,18 @@ summary: >-
 env:
   - name: SIMPLEPRACTICE_PRACTICE
     secret: false
-    required: true
+    # 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: >-
-      Your practice's Client 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.
+      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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simplepractice-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "license": "MIT",
   "mcpName": "io.github.chrischall/simplepractice-mcp",
   "description": "SimplePractice Client Portal MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -29,12 +29,12 @@
     "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.23.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
     "zod": "^4.4.3"

package/server.json

@@ -6,20 +6,20 @@
     "url": "https://github.com/chrischall/simplepractice-mcp",
     "source": "github"
   },
-  "version": "0.2.0",
+  "version": "0.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "simplepractice-mcp",
-      "version": "0.2.0",
+      "version": "0.4.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"
         },
         {

package/skills/simplepractice/SKILL.md

@@ -21,18 +21,27 @@ The portal has **no password**. SimplePractice emails a one-time link (or a
 6-digit PIN), and that is the only way in.
 
 1. `simplepractice_session_status` — check first; a session persists between
-   runs, so most of the time there is nothing to do.
-2. `simplepractice_request_sign_in_link` with the user's portal email. It is
+   runs, so most of the time there is nothing to do. It also reports which
+   practice is in play, and whether that came from a link, the environment, or
+   the saved session.
+2. If the user already has the email, skip straight to step 4 — asking for a
+   second link when one is in their inbox spends a rate limit for nothing.
+3. `simplepractice_request_sign_in_link` with the user's portal email. It is
    confirm-gated because it sends a real email and the endpoint is rate-limited
    **per address and per IP** — a retry loop locks the user out of the only
-   auth path there is. Ask before sending, and never send twice.
-3. The user opens the email and gives you the link. Pass it whole to
+   auth path there is. Ask before sending, and never send twice. If the server
+   does not know the practice yet, pass `practice` (the slug, host, or portal
+   URL) — otherwise it has no portal to ask.
+4. The user opens the email and gives you the link. Pass it **whole** to
    `simplepractice_verify_sign_in_token` — it takes the token out of the
-   fragment itself. Tokens are single-use and last 24 hours.
+   fragment *and* the practice out of the host, which is why the whole link is
+   worth more than the token alone. Tokens are single-use and last 24 hours.
 
-`SIMPLEPRACTICE_PRACTICE` must name the practice's portal — the slug or the
-full `<practice>.clientsecure.me` host, from the link the provider emailed.
-If it is unset, every tool says so on its first call.
+Nothing has to be configured: the practice comes from the link, and the stored
+session remembers it. `SIMPLEPRACTICE_PRACTICE` only pins the server to one
+practice. Two link shapes name no practice and need one already known — the
+mobile variant on the bare `clientsecure.me` apex, and a bare token pasted
+without its link.
 
 There is no refresh token. When a session lapses the tools say to sign in
 again; that means another email.