simplepractice-mcp 0.0.0 → 0.2.0

package/.claude-plugin/marketplace.json

@@ -6,21 +6,27 @@
   },
   "metadata": {
     "description": "SimplePractice Client Portal tools for Claude",
-    "version": "0.0.0"
+    "version": "0.2.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.0.0",
+      "version": "0.2.0",
       "author": {
         "name": "Chris Chall",
         "url": "https://github.com/chrischall"
       },
       "homepage": "https://github.com/chrischall/simplepractice-mcp",
       "license": "MIT",
-      "keywords": ["simplepractice", "client-portal", "therapy", "appointments", "billing"]
+      "keywords": [
+        "simplepractice",
+        "client-portal",
+        "therapy",
+        "appointments",
+        "billing"
+      ]
     }
   ]
 }

package/.claude-plugin/plugin.json

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

package/README.md

@@ -48,10 +48,15 @@ The Client Portal has **no password**. SimplePractice emails a one-time link
 3. `simplepractice_verify_sign_in_token { link }` — pass the whole link; the
    token is its `#` fragment and the tool extracts it.
 
-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.
+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.

package/dist/bundle.js

@@ -31530,7 +31530,7 @@ function toolAnnotations(opts = {}) {
 }
 
 // src/version.ts
-var VERSION = "0.0.0";
+var VERSION = "0.2.0";
 
 // node_modules/@chrischall/mcp-utils/dist/session/index.js
 import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync } from "node:fs";
@@ -31857,7 +31857,7 @@ var SimplePracticeClient = class {
     } catch {
       document = null;
     }
-    if (!response.ok) this.throwForStatus(response.status, document);
+    if (!response.ok) this.throwForStatus(response.status, document, path);
     if (document === null) {
       throw new McpToolError(
         `SimplePractice returned HTML rather than JSON for ${path}.`,
@@ -31884,11 +31884,12 @@ var SimplePracticeClient = class {
     const { document } = await this.request(path, { query });
     return flattenDocument(document);
   }
-  throwForStatus(status, document) {
+  throwForStatus(status, document, path) {
     const message = formatJsonApiErrors(document, status);
+    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 \u2014 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 \u2014 there is no refresh token, so sign in again with simplepractice_request_sign_in_link."
       });
     }
     if (status === 429) {

package/dist/client.js

@@ -122,7 +122,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 +150,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/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.0.0'; // x-release-please-version
+export const VERSION = '0.2.0'; // x-release-please-version

package/mint.yaml

@@ -0,0 +1,70 @@
+# 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
+    required: true
+    # 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.
+
+  - 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.0.0",
+  "version": "0.2.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,7 +21,8 @@
     ".claude-plugin",
     "skills",
     ".mcp.json",
-    "server.json"
+    "server.json",
+    "mint.yaml"
   ],
   "scripts": {
     "build": "tsc && npm run bundle",
@@ -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,12 +6,12 @@
     "url": "https://github.com/chrischall/simplepractice-mcp",
     "source": "github"
   },
-  "version": "0.0.0",
+  "version": "0.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "simplepractice-mcp",
-      "version": "0.0.0",
+      "version": "0.2.0",
       "transport": {
         "type": "stdio"
       },

package/skills/simplepractice-fpx/SKILL.md

@@ -82,13 +82,21 @@ hammering it locks you out of the only auth path there is. Wait it out.
 **b. Take the token out of the emailed link.** The link looks like
 
 ```
-https://<practice>.clientsecure.me/sign-in/token/verify#<TOKEN>
+https://<practice>.clientsecure.me/sign-in/token#<TOKEN>
 ```
 
-The token is the **URL fragment**, after the `#`. Because it is a fragment it
-is never sent to the server by a browser navigation — the app reads it in JS
-and posts it. So you must copy it yourself; following the link with `curl`
-does nothing.
+SimplePractice also mails a mobile-app variant on the bare apex,
+`https://clientsecure.me/client-portal-api/sign-in/token#<TOKEN>`. Either
+works — the path is irrelevant, only the fragment matters.
+
+The token is the **URL fragment**, after the `#` (about 300 characters).
+Because it is a fragment it is never sent to the server by a browser
+navigation — the app reads it in JS and posts it. So you must copy it
+yourself; following the link with `curl` does nothing.
+
+If you are pulling the link out of a raw message rather than clicking it, note
+the mail is **quoted-printable**: the URL is wrapped across lines with trailing
+`=`, and a naive regex will hand you a silently truncated token. Decode first.
 
 **c. Trade it for a session cookie.**
 

package/skills/simplepractice-fpx/references/requests.md

@@ -60,10 +60,20 @@ sp -X POST "$SP_API/sign-in-tokens" \
 
 ### 1.2 Exchange the token — `POST /sessions/token`
 
-The emailed link is `https://<practice>.clientsecure.me/sign-in/token/verify#<TOKEN>`.
-The token is the **fragment**. A browser never sends a fragment to the server;
-the Ember app reads `location.hash` and posts it. Fetching the link with `curl`
-accomplishes nothing — copy the part after `#`.
+The emailed link is
+**`https://<practice>.clientsecure.me/sign-in/token#<TOKEN>`** — `/sign-in/token`,
+*not* the `sign-in/token/verify` the app's route tree implies. A second variant,
+sent for the mobile app, points at the bare apex under the API namespace:
+`https://clientsecure.me/client-portal-api/sign-in/token#<TOKEN>`. Either works —
+take the fragment, ignore the path.
+
+The token is the **fragment** (303–317 characters observed). A browser never
+sends a fragment to the server; the app reads `location.hash` and posts it.
+Fetching the link with `curl` accomplishes nothing — copy the part after `#`.
+
+Both emails are quoted-printable, so the URL is **wrapped across lines with
+trailing `=`**. Pulling it out of a raw message with a naive regex silently
+truncates the token — decode the quoted-printable first.
 
 ```sh
 sp -X POST "$SP_API/sessions/token" \
@@ -80,13 +90,10 @@ Success sets the `simplepractice-session` cookie (Rails/Devise) and returns
 | `expired` | older than 24h — request a new link |
 | `merged` | the account was merged into another; sign in from the new portal |
 
-Tokens are single-use; replaying one gives `401`/`422`.
-
-> Not exercised live during this build: the exchange call itself. §1.1 was
-> confirmed against a real account (`202`), and the shape above comes from
-> `routes/sign-in/token/verify.js` + `services/sign-in.js`, but reading the
-> emailed token was out of scope for the agent that wrote this. Treat
-> `meta.status` handling as source-derived until you've run it once.
+Tokens are single-use — confirmed by replay, which answers
+`401 {"title":"Authorization has already been used or expired"}`. That is a 401
+on a sign-in endpoint, where you have no session yet; it means *get a new
+link*, not *your session expired*.
 
 ### 1.3 PIN variant — `POST /sessions/pin`