simplepractice-mcp 0.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,26 @@
+{
+  "name": "simplepractice",
+  "owner": {
+    "name": "Chris Chall",
+    "url": "https://github.com/chrischall"
+  },
+  "metadata": {
+    "description": "SimplePractice Client Portal tools for Claude",
+    "version": "0.0.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",
+      "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"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "simplepractice",
+  "version": "0.0.0",
+  "description": "SimplePractice Client Portal — appointments, billing, documents, and announcements",
+  "author": {
+    "name": "Chris Chall",
+    "url": "https://github.com/chrischall"
+  },
+  "homepage": "https://github.com/chrischall/simplepractice-mcp",
+  "license": "MIT",
+  "mcpServers": "./.mcp.json",
+  "skills": "./skills/"
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "simplepractice": {
+      "command": "npx",
+      "args": ["-y", "simplepractice-mcp"],
+      "env": {
+        "SIMPLEPRACTICE_PRACTICE": "${SIMPLEPRACTICE_PRACTICE}"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Hall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# simplepractice-mcp
+
+MCP server for the **SimplePractice Client Portal** — the side a practice's
+*clients* log into, not the clinician side. Appointments, billing, paperwork,
+and announcements, read over the portal's own JSON:API.
+
+> Developed and maintained by AI (Claude Code). Use at your own discretion.
+
+## What it reads
+
+| Tool | What it gives you |
+|---|---|
+| `simplepractice_get_account` | practice, current client, every client this login covers, cancellation policy, feature permissions |
+| `simplepractice_list_appointments` | scheduled or requested appointments, with clinician and location |
+| `simplepractice_list_billing_items` | invoices · statements · superbills · receipts · account history |
+| `simplepractice_get_billing_overview` | balance due and per-category counts |
+| `simplepractice_list_payment_methods` | saved cards — brand, last four, expiry |
+| `simplepractice_list_document_requests` | paperwork sent to you, with an outstanding-only filter |
+| `simplepractice_get_document_request` | one request in full, with its questions and answers |
+| `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 |
+
+Everything is read-only. Cancelling, signing, and paying happen in the portal.
+
+## Setup
+
+```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.
+
+| Variable | |
+|---|---|
+| `SIMPLEPRACTICE_PRACTICE` | **required** — portal slug or host |
+| `SIMPLEPRACTICE_SESSION_FILE` | optional — session path (default `~/.simplepractice-mcp/session.json`, written `0600`) |
+
+## Signing in
+
+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.
+
+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.
+
+Because that flow needs nothing but HTTP and your inbox, this server has no
+browser dependency and can run anywhere.
+
+## Without the server
+
+`skills/simplepractice-fpx` does the same reads with `curl`, either signing in
+by magic link or lifting the session cookie from a browser tab with
+[`fpx`](https://www.npmjs.com/package/@fetchproxy/cli).
+
+## Notes from building this
+
+The portal is an Ember app that ships **public sourcemaps**, so its models,
+adapters and routes are readable directly — `docs/SIMPLEPRACTICE-API.md`
+records the endpoints and the traps, all confirmed against a live portal:
+
+- The SPA catch-all answers **HTTP 200 with `text/html`** for any path the API
+  does not define. `/cards` and `/client-billing-overviews` look like working,
+  empty endpoints and are not endpoints at all — both are `include`
+  relationships of `/clients/<id>`.
+- `hasDocumentPdf`, a card's `isDefault`, and the client's `permissions` blob
+  are all **strings**, not booleans or objects.
+- Billing pages by *cursor* (`page[before]` = a row's `cursorId`), appointments
+  page by *number*. The two are not interchangeable.
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test              # 151 tests
+npm run test:coverage # 100% enforced
+npm run typecheck     # vitest does not run tsc — this does
+```
+
+## License
+
+MIT

package/dist/auth.js

@@ -0,0 +1,79 @@
+import { CookieJar, McpToolError } from '@chrischall/mcp-utils';
+/** The Rails/Devise session cookie the portal authenticates with. */
+export const SESSION_COOKIE = 'simplepractice-session';
+/**
+ * Ask SimplePractice to email a sign-in link.
+ *
+ * The response always reports a 24-hour lifetime and always succeeds for a
+ * well-formed address — deliberately, so that it cannot be used to probe
+ * whether an email has an account. A 202 is therefore NOT evidence the address
+ * is registered, and the tool description says so.
+ */
+export async function requestSignInLink(client, email) {
+    const { document } = await client.request('/sign-in-tokens', {
+        method: 'POST',
+        anonymous: true,
+        body: {
+            data: { type: 'sign-in-tokens', attributes: { email, expiresIn: '15 minutes' } },
+        },
+    });
+    const data = Array.isArray(document.data) ? document.data[0] : document.data;
+    const expiresIn = data?.attributes?.expiresIn ?? '24 hours';
+    return { expiresIn };
+}
+function extractToken(raw) {
+    const trimmed = raw.trim();
+    // Users paste the whole emailed link about as often as just the token, and
+    // the token is the URL FRAGMENT — a browser never sends it, so there is no
+    // way to recover it from anything but the link text itself.
+    const hash = trimmed.indexOf('#');
+    // A link with NO fragment is not a token-bearing link: the token lives only
+    // in the fragment, so accepting the bare URL here would POST the whole URL
+    // as if it were the token and report a confusing upstream rejection.
+    if (hash < 0 && /^https?:\/\//i.test(trimmed)) {
+        throw new McpToolError('That sign-in link has no token in it.', {
+            hint: 'The token is the part after the "#". Copy the link straight out of the email — some mail clients drop the fragment when they rewrite links, in which case open the email in a browser and copy the address from the address bar.',
+        });
+    }
+    const token = hash >= 0 ? trimmed.slice(hash + 1) : trimmed;
+    if (!token || /\s/.test(token) || token.includes('/')) {
+        throw new McpToolError('That does not look like a sign-in token.', {
+            hint: 'Paste either the whole link from the email or just the part after the "#". The token is the URL fragment — following the link in a browser will not reveal it to anything else.',
+        });
+    }
+    return token;
+}
+async function establishSession(client, attributes) {
+    const path = `/sessions/${attributes.type}`;
+    const { document, setCookie } = await client.request(path, {
+        method: 'POST',
+        anonymous: true,
+        body: { data: { type: 'sessions', attributes } },
+    });
+    const data = Array.isArray(document.data) ? document.data[0] : document.data;
+    const status = data?.meta?.status ?? 'unknown';
+    if (status !== 'verified') {
+        throw new McpToolError(`SimplePractice did not accept the sign-in: ${status}.`, {
+            hint: status === 'expired'
+                ? 'Sign-in links last 24 hours. Request a new one.'
+                : 'Sign-in tokens and PINs are single-use. Request a new one rather than reusing the last.',
+        });
+    }
+    const jar = new CookieJar();
+    jar.absorb(setCookie);
+    const cookie = jar.get(SESSION_COOKIE);
+    if (!cookie) {
+        throw new McpToolError('Sign-in verified but no session cookie came back.', {
+            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 };
+}
+export function verifySignInToken(client, linkOrToken) {
+    return establishSession(client, { type: 'token', token: extractToken(linkOrToken) });
+}
+export function verifySignInPin(client, email, pin) {
+    return establishSession(client, { type: 'pin', email, pin });
+}
+export { extractToken as _extractToken };