simplepractice-mcp 0.1.0 → 0.3.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/README.md

@@ -20,6 +20,7 @@ and announcements, read over the portal's own JSON:API.
 | `simplepractice_list_documents` | files the practice has shared |
 | `simplepractice_list_announcements` | practice announcements, with unread counts |
 | `simplepractice_session_status` · `_request_sign_in_link` · `_verify_sign_in_token` · `_verify_sign_in_pin` · `_sign_out` | sign-in |
+| `simplepractice_healthcheck` | Verify credentials and upstream reachability; reports failures as data, not exceptions |
 
 Everything is read-only. Cancelling, signing, and paying happen in the portal.
 
@@ -27,15 +28,13 @@ Everything is read-only. Cancelling, signing, and paying happen in the portal.
 
 ```sh
 npm install -g simplepractice-mcp
-export SIMPLEPRACTICE_PRACTICE=achievebalancetherapy   # or the full host
 ```
 
-`SIMPLEPRACTICE_PRACTICE` is the practice's portal address — the slug or the
-whole `<practice>.clientsecure.me` host from the link your provider emailed.
+There is nothing to configure. The practice comes from your sign-in link.
 
 | Variable | |
 |---|---|
-| `SIMPLEPRACTICE_PRACTICE` | **required** — portal slug or host |
+| `SIMPLEPRACTICE_PRACTICE` | optional — pins the server to one practice (slug or host) |
 | `SIMPLEPRACTICE_SESSION_FILE` | optional — session path (default `~/.simplepractice-mcp/session.json`, written `0600`) |
 
 ## Signing in
@@ -43,15 +42,41 @@ whole `<practice>.clientsecure.me` host from the link your provider emailed.
 The Client Portal has **no password**. SimplePractice emails a one-time link
 (or a 6-digit PIN); you trade it for a session cookie:
 
-1. `simplepractice_request_sign_in_link { email, confirm: true }`
-2. Open the email, copy the link.
-3. `simplepractice_verify_sign_in_token { link }` — pass the whole link; the
-   token is its `#` fragment and the tool extracts it.
+1. Open the email your provider sent, copy the link.
+2. `simplepractice_verify_sign_in_token { link }` — pass the **whole** link.
 
-Links are single-use and last 24 hours. The request endpoint is rate-limited
-per address **and** per IP, which is why sending is confirm-gated — a retry
-loop locks you out of the only way in. There is no refresh token: when the
-session lapses, you sign in again.
+The link is `https://<practice>.clientsecure.me/sign-in/token#<TOKEN>`, so one
+paste carries both halves of what the server needs: the token is the `#`
+fragment, and the host names the practice. Nothing is hardcoded, and the
+stored session remembers the practice for every later run —
+`simplepractice_session_status` reports which practice is in play and whether
+it came from a link, the environment variable, or the saved session.
+
+To have a fresh link sent rather than using one you already have, name the
+practice once:
+
+```
+simplepractice_request_sign_in_link { email, practice: "achievebalancetherapy", confirm: true }
+```
+
+`practice` can be omitted whenever the server already knows the practice —
+from an earlier sign-in, or from `SIMPLEPRACTICE_PRACTICE`.
+
+Two sign-in links name no practice, and fall back to whichever one is already
+known: the mobile-app variant SimplePractice sends
+(`https://clientsecure.me/client-portal-api/sign-in/token#<TOKEN>`, pointed at
+the bare apex), and a bare token pasted without its link. A link on any host
+outside `*.clientsecure.me` is never adopted — the token is not sent there.
+
+Links are single-use — replaying one answers
+`401 "Authorization has already been used or expired"` — and last 24 hours. The
+request endpoint is rate-limited per address **and** per IP, which is why
+sending is confirm-gated: a retry loop locks you out of the only way in. There
+is no refresh token; when the session lapses, you sign in again.
+
+The whole chain is verified end to end against a live portal — request, the
+emailed link, the exchange returning `verified` plus a session cookie, and an
+authenticated read with that new session.
 
 Because that flow needs nothing but HTTP and your inbox, this server has no
 browser dependency and can run anywhere.
@@ -82,7 +107,7 @@ records the endpoints and the traps, all confirmed against a live portal:
 ```sh
 npm install
 npm run build
-npm test              # 151 tests
+npm test              # 214 tests
 npm run test:coverage # 100% enforced
 npm run typecheck     # vitest does not run tsc — this does
 ```

package/dist/auth.js

@@ -1,4 +1,5 @@
 import { CookieJar, McpToolError } from '@chrischall/mcp-utils';
+import { practiceHostFromLink } from './config.js';
 /** The Rails/Devise session cookie the portal authenticates with. */
 export const SESSION_COOKIE = 'simplepractice-session';
 /**
@@ -67,11 +68,37 @@ async function establishSession(client, attributes) {
             hint: `Expected a ${SESSION_COOKIE} cookie on the response. If SimplePractice has renamed it, simplepractice-mcp needs updating.`,
         });
     }
-    client.saveSession(`${SESSION_COOKIE}=${cookie}`);
-    return { status, signedIn: true };
+    const session = client.saveSession(`${SESSION_COOKIE}=${cookie}`);
+    return { status, signedIn: true, practiceHost: session.host };
 }
-export function verifySignInToken(client, linkOrToken) {
-    return establishSession(client, { type: 'token', token: extractToken(linkOrToken) });
+/**
+ * Trade an emailed sign-in link for a session — and take the practice from the
+ * link while we are at it.
+ *
+ * The link is `https://<practice>.clientsecure.me/sign-in/token#<TOKEN>`, so
+ * the same paste that carries the token also says which portal to send it to.
+ * That is the only ordering that can work when the link and the configuration
+ * disagree: the token was minted for the practice in the link, and posting it
+ * anywhere else is a 401.
+ *
+ * A link that names no practice — the mobile variant at the bare apex, or a
+ * bare token — falls back to whatever practice is already known.
+ */
+// `async` so that the pre-flight rejections below reach a caller the same way
+// the network ones do, rather than throwing synchronously out of a function
+// that otherwise returns a promise.
+export async function verifySignInToken(client, linkOrToken) {
+    const attributes = { type: 'token', token: extractToken(linkOrToken) };
+    const fromLink = practiceHostFromLink(linkOrToken);
+    // Scoped, so a link that fails to verify does not leave the process pointed
+    // at its practice — links are single-use, so failing is the ordinary case.
+    if (fromLink) {
+        return client.withPracticeHost(fromLink, () => establishSession(client, attributes));
+    }
+    // No practice in the link, so it has to be known already: resolve before
+    // posting, or a single-use token is spent against a guess.
+    client.portalHost();
+    return establishSession(client, attributes);
 }
 export function verifySignInPin(client, email, pin) {
     return establishSession(client, { type: 'pin', email, pin });