simplepractice-mcp 0.0.0

package/dist/tools/documents.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { asBoolean } from '../jsonapi.js';
+const PAGE_SIZE_MAX = 50;
+/** Statuses that mean the client has nothing left to do. */
+const SETTLED = new Set(['completed', 'locked']);
+export function registerDocumentTools(server, client) {
+    server.registerTool('simplepractice_list_document_requests', {
+        description: 'Paperwork the practice has sent — consents, questionnaires, contact and insurance forms, Good Faith Estimates, shared files. Use outstandingOnly to see just what still needs the client\'s attention.',
+        annotations: toolAnnotations({ readOnly: true }),
+        inputSchema: {
+            outstandingOnly: z
+                .boolean()
+                .default(false)
+                .describe('Return only requests that are not completed or locked.'),
+            pageSize: z.number().int().positive().max(PAGE_SIZE_MAX).default(PAGE_SIZE_MAX),
+            includeBody: z
+                .boolean()
+                .default(false)
+                .describe('Include the full document body/questions. Off by default — these are long.'),
+        },
+    }, async ({ outstandingOnly, pageSize, includeBody }) => {
+        const { records, meta } = await client.list('/document-requests', {
+            page: { size: pageSize },
+        });
+        const filtered = outstandingOnly
+            ? records.filter((r) => !SETTLED.has(String(r.status)))
+            : records;
+        const items = filtered.map((r) => {
+            const base = {
+                id: r.id,
+                // The subtype IS the type field — documentRequestQuestionnaires etc.
+                kind: r.type,
+                title: r.documentTitle,
+                status: r.status,
+                createdAt: r.createdAt,
+                updatedAt: r.updatedAt,
+                // Arrives as the STRING "true"/"false" on the wire, so a plain
+                // truthiness test would report every row as having a PDF.
+                hasDocumentPdf: asBoolean(r.hasDocumentPdf) ?? false,
+            };
+            if (includeBody) {
+                base.documentBody = r.documentBody;
+                base.templateQuestions = r.templateQuestions;
+                base.userAnswers = r.userAnswers;
+            }
+            return base;
+        });
+        return textResult({
+            count: items.length,
+            outstanding: records.filter((r) => !SETTLED.has(String(r.status))).length,
+            welcomeText: meta?.welcomeText ?? null,
+            documentRequests: items,
+        });
+    });
+    server.registerTool('simplepractice_get_document_request', {
+        description: 'One document request in full, including its body or its questions and the answers already given.',
+        annotations: toolAnnotations({ readOnly: true }),
+        inputSchema: { id: z.string().min(1).describe('The document request id.') },
+    }, async ({ id }) => {
+        const { records } = await client.list(`/document-requests/${encodeURIComponent(id)}`);
+        const record = records[0];
+        if (!record)
+            return textResult({ found: false, id });
+        return textResult({
+            ...record,
+            hasDocumentPdf: asBoolean(record.hasDocumentPdf) ?? false,
+        });
+    });
+    server.registerTool('simplepractice_list_documents', {
+        description: 'Files the practice has shared through the Client Portal.',
+        annotations: toolAnnotations({ readOnly: true }),
+        inputSchema: {
+            pageSize: z.number().int().positive().max(PAGE_SIZE_MAX).default(PAGE_SIZE_MAX),
+        },
+    }, async ({ pageSize }) => {
+        const { records } = await client.list('/documents', { page: { size: pageSize } });
+        return textResult({ count: records.length, documents: records });
+    });
+    server.registerTool('simplepractice_list_announcements', {
+        description: 'Announcements the practice has posted to the Client Portal. readAt is null on unread ones.',
+        annotations: toolAnnotations({ readOnly: true }),
+        inputSchema: {
+            pageSize: z.number().int().positive().max(PAGE_SIZE_MAX).default(PAGE_SIZE_MAX),
+        },
+    }, async ({ pageSize }) => {
+        const { records } = await client.list('/announcements', { page: { size: pageSize } });
+        return textResult({
+            count: records.length,
+            unread: records.filter((r) => r.readAt === null || r.readAt === undefined).length,
+            announcements: records,
+        });
+    });
+}

package/dist/version.js

@@ -0,0 +1,5 @@
+/**
+ * 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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "simplepractice-mcp",
+  "version": "0.0.0",
+  "license": "MIT",
+  "mcpName": "io.github.chrischall/simplepractice-mcp",
+  "description": "SimplePractice Client Portal MCP server for Claude — developed and maintained by AI (Claude Code)",
+  "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrischall/simplepractice-mcp.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "bin": {
+    "simplepractice-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    ".claude-plugin",
+    "skills",
+    ".mcp.json",
+    "server.json"
+  ],
+  "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:watch": "vitest"
+  },
+  "dependencies": {
+    "@chrischall/mcp-utils": "^0.15.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "@vitest/coverage-v8": "^4.1.7",
+    "esbuild": "^0.28.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.7"
+  }
+}

package/server.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.chrischall/simplepractice-mcp",
+  "description": "SimplePractice Client Portal — appointments, billing, documents, announcements",
+  "repository": {
+    "url": "https://github.com/chrischall/simplepractice-mcp",
+    "source": "github"
+  },
+  "version": "0.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "simplepractice-mcp",
+      "version": "0.0.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,
+          "format": "string"
+        },
+        {
+          "name": "SIMPLEPRACTICE_SESSION_FILE",
+          "description": "Where to persist the signed-in session (default ~/.simplepractice-mcp/session.json, written 0600).",
+          "isRequired": false,
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}

package/skills/simplepractice/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: simplepractice
+description: >-
+  Read a SimplePractice Client Portal through the simplepractice-mcp server —
+  upcoming appointments, invoices/statements/superbills/receipts, balance and
+  saved cards, paperwork waiting to be signed, and practice announcements.
+  Use when the user asks about their therapy or healthcare appointments,
+  what they owe a practice, a superbill for insurance, or forms their
+  provider has sent them.
+---
+
+# SimplePractice Client Portal
+
+`simplepractice-mcp` reads the Client Portal a practice gives its clients —
+the patient side, not the clinician side. It is **read-only**: nothing here
+cancels an appointment, signs a form, or pays a bill.
+
+## Signing in
+
+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
+   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
+   `simplepractice_verify_sign_in_token` — it takes the token out of the
+   fragment itself. 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.
+
+There is no refresh token. When a session lapses the tools say to sign in
+again; that means another email.
+
+## Reading
+
+- `simplepractice_get_account` — the practice, the current client, and the
+  clients this login covers. **Start here**: one portal login can act for
+  several people (a parent for two children), so confirm *whose* record you
+  are about to report on before you report on it. It also returns the
+  practice's real cancellation policy and the client's feature permissions.
+- `simplepractice_list_appointments` — `status: "scheduled"` for confirmed and
+  upcoming, `"requested"` for ones the practice has not confirmed yet.
+- `simplepractice_list_document_requests` — paperwork. `outstandingOnly: true`
+  answers "is anything waiting for me?", which is the usual question.
+- `simplepractice_get_billing_overview` — balance due and per-category counts.
+  Cheaper than listing the billing collections to find out they are empty.
+- `simplepractice_list_billing_items` — invoices, statements, **superbills**
+  (the receipt to claim out-of-network insurance), receipts, or account
+  history. Pages by cursor: pass the returned `nextCursor` back as `before`.
+- `simplepractice_list_payment_methods`, `simplepractice_list_documents`,
+  `simplepractice_list_announcements`.
+
+## Reading the results honestly
+
+- **An empty billing list is a real answer.** Plenty of practices invoice
+  entirely outside the portal. "No invoices in the portal" is the true
+  statement; "you owe nothing" is not one you can make from it.
+- **Do not tell someone they can cancel an appointment.** `isCancellable` and
+  the practice's `clientMayCancelAppointments` / `cancellationNoticeHours`
+  are what govern it, and cancelling has to happen in the portal anyway.
+- **This is medical information.** Report what was asked. Don't volunteer
+  diagnoses, session notes, or a family member's records into a conversation
+  that wasn't about them.
+
+## The shell alternative
+
+`simplepractice-fpx` does the same reads with `curl` and no server, for
+scripts or a machine without the MCP installed.

package/skills/simplepractice-fpx/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: simplepractice-fpx
+description: >-
+  Read a SimplePractice Client Portal (`<practice>.clientsecure.me`) from a
+  shell — appointments, invoices/statements/superbills/receipts, documents to
+  sign, announcements, practice and clinician info — with plain `curl` against
+  its JSON:API, instead of running the simplepractice-mcp server. Sign in
+  headlessly with an emailed magic link, or capture the session cookie from an
+  already-signed-in browser tab with `fpx`. Use when you want Client Portal
+  data without the MCP, in a script, or on a machine where the MCP isn't
+  installed.
+---
+
+# SimplePractice Client Portal via curl (+ optional fpx)
+
+The Client Portal is an Ember app whose backend is a plain **JSON:API** at
+`https://<practice>.clientsecure.me/client-portal-api`. It has **no bot wall**
+— every endpoint below answers ordinary server-side `curl` once you hold a
+session cookie. So this skill is curl-first; `fpx` appears only as an optional
+one-time way to lift the cookie out of a browser you're already signed into.
+
+There is **no password**. Sign-in is passwordless: SimplePractice emails you
+either a magic link or a 6-digit PIN, and you trade that for a session cookie.
+That flow carries **no captcha** (reCAPTCHA guards only the new-client request,
+waitlist and contact forms), so §1 below works headlessly with nothing but
+`curl` and access to your inbox.
+
+> This is protected health information — your own therapy/medical record.
+> Treat the cookie jar as a credential: it is a full-access bearer token for
+> the portal. Keep it `chmod 600`, out of git, and off shared machines.
+
+## Your practice subdomain
+
+Every URL is scoped to one practice. Take the host from the portal link your
+provider sent you and export it once:
+
+```sh
+export SP_HOST='achievebalancetherapy.clientsecure.me'   # <-- yours
+export SP_API="https://$SP_HOST/client-portal-api"
+export SP_JAR="$HOME/.simplepractice-cookies"
+
+# curl creates a cookie jar world-readable (644). This one holds a live
+# session for a medical record, so create it 0600 BEFORE curl ever writes it.
+[ -e "$SP_JAR" ] || ( umask 077; : > "$SP_JAR" )
+chmod 600 "$SP_JAR"
+```
+
+## The four headers — all of them, on every call
+
+```sh
+sp() { curl -s -b "$SP_JAR" -c "$SP_JAR" \
+  -H 'Api-Version: 2026-05-25' \
+  -H 'Application-Build-Version: 0.0.0' \
+  -H 'Application-Platform: web' \
+  -H 'Accept: application/vnd.api+json' "$@"; }
+```
+
+Omit `Application-Build-Version` and the API rejects the call with
+`400 {"errors":[{"title":"Application build version is missing"}]}` — verified.
+`Api-Version` is the API's own dated contract version, unrelated to any package
+version; send it as-is.
+
+## 1. Sign in with a magic link (no browser)
+
+**a. Request the link.** One call, to your own portal address:
+
+```sh
+sp -X POST "$SP_API/sign-in-tokens" \
+  -H 'Content-Type: application/vnd.api+json' \
+  --data '{"data":{"type":"sign-in-tokens","attributes":{"email":"you@example.com","expiresIn":"15 minutes"}}}'
+```
+
+`202 Accepted` means it was sent. The response echoes `expiresIn: "24 hours"`
+regardless of what you asked for — that is the real token lifetime, and it is
+also what the API returns for an *unknown* email, deliberately, so that a 202
+never reveals whether an address has an account.
+
+**Do not retry a failed sign-in.** `429` is a real limit with two distinct
+titles — `Email request limit reached` and `IP request limit reached` — and
+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>
+```
+
+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.
+
+**c. Trade it for a session cookie.**
+
+```sh
+sp -X POST "$SP_API/sessions/token" \
+  -H 'Content-Type: application/vnd.api+json' \
+  --data '{"data":{"type":"sessions","attributes":{"type":"token","token":"'"$TOKEN"'"}}}' \
+  | jq '.data.meta.status'
+```
+
+`"verified"` means the cookie jar is now authenticated. The other statuses are
+`"expired"` and `"merged"`; a `401`/`422` means the token was already used —
+they are single-use.
+
+**PIN variant.** If your portal mails a 6-digit code instead of a link, post it
+to `sessions/pin` with the address it was sent to:
+
+```sh
+sp -X POST "$SP_API/sessions/pin" \
+  -H 'Content-Type: application/vnd.api+json' \
+  --data '{"data":{"type":"sessions","attributes":{"type":"pin","email":"you@example.com","pin":"123456"}}}'
+```
+
+## 2. Or lift the cookie from a signed-in browser tab (fpx)
+
+Only worth it if you're already signed in and would rather not wait on an
+email. Requires the **Transporter** extension and `npm i -g @fetchproxy/cli`.
+
+```sh
+fpx profile add simplepractice --domain clientsecure.me
+fpx profile declare simplepractice \
+  --cookie simplepractice-session --cookie client-portal-session \
+  --local-storage client-portal-session --local-storage stored-email \
+  --capture-header cookie@$SP_HOST
+fpx get "https://$SP_HOST/" -p simplepractice >/dev/null   # prints a pair code → approve in Transporter
+```
+
+Declare **every** scope before that first pairing. Widening it afterwards
+leaves fetches working on the old grant while the new capability errors
+`capability "read_cookies" not granted`, and the fix is to remove the profile
+and re-pair from scratch.
+
+Then seed the jar from the browser's cookie:
+
+```sh
+SESSION=$(fpx cookies simplepractice-session -p simplepractice \
+            --storage-subdomain "${SP_HOST%%.*}" | jq -r '.["simplepractice-session"]')
+printf '#HttpOnly_%s\tFALSE\t/\tTRUE\t0\tsimplepractice-session\t%s\n' "$SP_HOST" "$SESSION" > "$SP_JAR"
+chmod 600 "$SP_JAR"
+```
+
+`fpx` exit codes: `2` bridge unavailable, `3` bot wall, `4` upstream non-2xx.
+
+## 3. Who am I, and which client am I looking at
+
+```sh
+sp "$SP_API/environment?include=currentPractice,currentClient,currentClientOptions" | jq '{
+  practice: (.included[] | select(.type=="practices") | .attributes.fullName),
+  timeZone: (.included[] | select(.type=="practices") | .attributes.timeZone),
+  clients:  [.included[] | select(.type=="clients") | {id, name: (.attributes.firstName+" "+.attributes.lastName)}]
+}'
+```
+
+One portal login is a **client access**, and it can cover more than one client
+— a parent seeing two children, say. `currentClientOptions` is always an array;
+`currentClient` is the one whose data the other endpoints return. Don't assume
+there is exactly one. (On a login that acts for someone else, the client
+record's own `email` is `null` — the sign-in address lives on the access, not
+the client, so don't reach for `clients[].email` to find out who you are.)
+
+`401 {"title":"You have no access to this client"}` on any endpoint below means
+the cookie is stale or absent — go back to §1.
+
+## 4. Reads
+
+All of these are verified live. Collections are JSON:API, so records live under
+`.data[]` with fields under `.attributes`; `include=` pulls related records into
+a sibling `.included[]` array that you join on
+`.relationships.<name>.data.id`.
+
+```sh
+# Upcoming appointments (and the requested-but-unconfirmed ones)
+sp "$SP_API/appointments?include=clinician,office,client&filter[hasPendingConfirmation]=false&page[size]=50&page[number]=1"
+sp "$SP_API/appointments?include=clinician,office,client&filter[hasPendingConfirmation]=true&page[size]=50&page[number]=1"
+
+# Billing — one endpoint, switched by filter[thisType]
+sp "$SP_API/billing-items?filter[thisType]=invoice&page[size]=50"
+sp "$SP_API/billing-items?filter[thisType]=statement&page[size]=50"
+sp "$SP_API/billing-items?filter[thisType]=superbill&page[size]=50"
+sp "$SP_API/billing-items?filter[thisType]=receipt&page[size]=50"
+sp "$SP_API/billing-items?filter[thisType]=billable-item,payment&filter[thisTypeCondition]=unallocated&page[size]=50"
+
+# Documents to review or sign, and files shared with you
+sp "$SP_API/document-requests?page[size]=50"
+sp "$SP_API/documents?page[size]=50"
+
+# Practice announcements
+sp "$SP_API/announcements?page[size]=50"
+
+# Balance summary and saved cards hang off the CLIENT record, not collections
+# of their own — see the warning below.
+CLIENT_ID=$(sp "$SP_API/environment?include=currentClient" \
+            | jq -r '.data.relationships.currentClient.data.id')
+sp "$SP_API/clients/$CLIENT_ID?include=clientBillingOverview,cards" \
+| jq '{balance: (.included[] | select(.type=="clientBillingOverviews") | .attributes),
+       cards:  [.included[] | select(.type=="cards")
+                | {brand: .attributes.brand, last4: .attributes.last4,
+                   expiry: .attributes.expiry, isDefault: .attributes.isDefault}]}'
+```
+
+> **A 200 is not proof an endpoint exists.** The portal is a single-page app,
+> so *any* path it does not define comes back as `200 text/html` with the app
+> shell (a constant ~7.5 KB) rather than a 404. `/cards` and
+> `/client-billing-overviews` are the obvious guesses for the two above, and
+> both answer 200 that way — they are not API paths at all. Check the
+> `content-type`, not the status:
+>
+> ```sh
+> sp -o /dev/null -w '%{http_code} %{content_type}\n' "$SP_API/whatever"
+> ```
+>
+> Anything other than `application/vnd.api+json` means the path is wrong.
+
+A readable next-appointment line:
+
+```sh
+sp "$SP_API/appointments?include=clinician,office&filter[hasPendingConfirmation]=false&page[size]=1&page[number]=1" \
+| jq -r '.data[0] as $a
+  | (.included[]? | select(.type=="clinicians")) as $c
+  | "\($a.attributes.startTime)  \($a.attributes.serviceDescription // "—")  with \($c.attributes.firstName) \($c.attributes.lastName)"'
+```
+
+## Pagination — two schemes, don't mix them
+
+- **Appointments** page by number: `page[number]=1&page[size]=50`. You're on
+  the last page when a page comes back shorter than `page[size]`.
+- **Billing items** page by *cursor*, backwards: `page[size]=50` and then
+  `page[before]=<cursorId of the last row you saw>`. The row's `cursorId` is
+  the cursor, not its `id`.
+
+`50` is the server's max page size; asking for more does not get you more.
+
+## Notes
+
+- Times come back ISO-8601 with an offset. The practice's own `timeZone`
+  (§3) is what its staff schedule in — use it when a date matters.
+- **`permissions` on the client is a JSON string, not an object.** It parses
+  to the portal features this client actually has —
+  `{"messaging":…,"selfScheduling":…,"billingDocuments":…,"payments":…,"appointments":…}`.
+  Read it with `.attributes.permissions | fromjson`; used raw it is a string of
+  characters. `billingDocuments` is what gates the whole billing tab.
+- **`hasDocumentPdf` is a string, not a boolean.** It arrives as `"true"` or
+  `"false"` — both seen live — so `if (hasDocumentPdf)` and
+  `jq 'select(.attributes.hasDocumentPdf)'` are BOTH true for `"false"`.
+  Compare against the string: `select(.attributes.hasDocumentPdf == "true")`.
+  A card's `isDefault` is the same — so do not assume a JSON boolean anywhere
+  in this API without checking the value you actually get back.
+- `billing-items` is polymorphic: `.data[].type` tells you which of
+  invoice / statement / superbill / receipt / payment a row actually is, and
+  the attribute set differs per type. `.meta.endBalance` accompanies every
+  billing query.
+- An empty `.data[]` is a real answer, not a failure — plenty of practices
+  bill outside the portal entirely and every billing endpoint returns `200`
+  with nothing in it.
+- Everything here is a **read**. Cancelling an appointment, submitting a
+  signed document, or paying an invoice are writes this skill deliberately
+  does not cover — do those in the portal, where you can see what you're
+  agreeing to.
+- This project is developed and maintained by AI (Claude).