simplepractice-mcp 0.1.0 → 0.3.0

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.

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`