simplepractice-mcp 1.1.4 → 1.2.0

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "SimplePractice Client Portal tools for Claude",
-    "version": "1.1.4"
+    "version": "1.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": "1.1.4",
+      "version": "1.2.0",
       "author": {
         "name": "Chris Chall",
         "url": "https://github.com/chrischall"

package/.claude-plugin/plugin.json

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

package/README.md

@@ -64,9 +64,11 @@ 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 }
+simplepractice_request_sign_in_link { email, practice: "achievebalancetherapy" }
 ```
 
+Sending asks you to confirm first (see [Confirmations](#confirmations)).
+
 `practice` can be omitted whenever the server already knows the practice —
 from an earlier sign-in, or from `SIMPLEPRACTICE_PRACTICE`.
 
@@ -79,8 +81,8 @@ 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.
+sending asks for confirmation first: 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
@@ -89,6 +91,21 @@ 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.
 
+## Confirmations
+
+`simplepractice_request_sign_in_link` sends a real email, so it asks you to
+confirm first. On a client that can show a confirmation prompt (Claude Code) you
+get the prompt. On one that cannot (claude.ai, Claude Desktop), the first call
+sends nothing and returns a preview — the address, the practice — plus a
+`confirmToken`; only a repeat call with that token, and the same arguments,
+sends. A token works once, and a changed address or practice is refused.
+
+| variable | default | |
+|---|---|---|
+| `MCP_CONFIRM_MODE` | `ask-user` | What a write does on a client that cannot show a confirmation prompt (claude.ai, Claude Desktop). `ask-user`: two steps — the first call does nothing and returns a preview plus a token, and the model must get your approval in chat before calling again with it. `auto`: the same two steps, but the model may use the token after reviewing the preview itself. `refuse`: writes are refused on such clients. A client that can show prompts (Claude Code) always gets the real prompt. An unrecognised value is treated as `refuse`. |
+| `MCP_CONFIRM_TTL_SECONDS` | `600` | How long a token stays valid. |
+| `MCP_CONFIRM_SECRET` | random per process | Signing key; set it only if tokens must survive a server restart. |
+
 ## Without the server
 
 `skills/simplepractice-fpx` does the same reads with `curl`, either signing in

package/dist/bundle.js

@@ -19,6 +19,33 @@ var storage2 = new AsyncLocalStorage2();
 function withCallerCapabilities(capabilities, fn) {
   return capabilities ? storage2.run(capabilities, fn) : fn();
 }
+function currentCallerCapabilities() {
+  return storage2.getStore();
+}
+var ENVELOPE_CAPABILITIES_KEY = "io.modelcontextprotocol/clientCapabilities";
+var ELICITATION_MODES = ["form", "url"];
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function callerCapabilities(ctx) {
+  const envelope = isRecord(ctx) && isRecord(ctx.mcpReq) ? ctx.mcpReq.envelope : void 0;
+  if (isRecord(envelope)) {
+    const declared = envelope[ENVELOPE_CAPABILITIES_KEY];
+    if (isRecord(declared))
+      return declared;
+  }
+  return currentCallerCapabilities();
+}
+function callerAcceptsFormElicitation(ctx) {
+  const capabilities = callerCapabilities(ctx);
+  if (!capabilities)
+    return void 0;
+  const elicitation = capabilities.elicitation;
+  if (!isRecord(elicitation))
+    return false;
+  const namedModes = ELICITATION_MODES.filter((mode) => mode in elicitation);
+  return namedModes.length === 0 || namedModes.includes("form");
+}
 
 // node_modules/@modelcontextprotocol/server/dist/chunk-Br0eD_fh.mjs
 var __create = Object.create;
@@ -24083,6 +24110,37 @@ var inputRequired = Object.assign(buildInputRequired, {
     return { method: "roots/list" };
   }
 });
+function acceptedContent(responses, key, schema) {
+  const view = inputResponse(responses, key);
+  if (view.kind !== "elicit" || view.action !== "accept" || view.content === void 0) return void 0;
+  if (schema === void 0) return view.content;
+  const outcome = schema["~standard"].validate(view.content);
+  if (outcome instanceof Promise) throw new TypeError("acceptedContent(responses, key, schema) requires a synchronously-validating schema");
+  return outcome.issues === void 0 ? outcome.value : void 0;
+}
+function inputResponse(responses, key) {
+  if (responses === void 0 || typeof responses !== "object" || responses === null) return { kind: "missing" };
+  const entry = responses[key];
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return { kind: "missing" };
+  const candidate = entry;
+  if (candidate["action"] === "accept" || candidate["action"] === "decline" || candidate["action"] === "cancel") {
+    const content = candidate["content"];
+    return {
+      kind: "elicit",
+      action: candidate["action"],
+      ...content !== null && typeof content === "object" && !Array.isArray(content) && { content }
+    };
+  }
+  if (Array.isArray(candidate["roots"])) return {
+    kind: "roots",
+    roots: candidate["roots"]
+  };
+  if (typeof candidate["role"] === "string" && candidate["content"] !== void 0) return {
+    kind: "sampling",
+    result: candidate
+  };
+  return { kind: "missing" };
+}
 var REQUEST_STATE_ONLY_LEG_PACING_MS = 250;
 function inputRequiredRoundsExceededMessage(method, maxRounds) {
   return `Multi-round-trip request '${method}' still required input after ${maxRounds} rounds (inputRequired.maxRounds)`;
@@ -34130,14 +34188,14 @@ function serveStdio(factory, options = {}) {
     return false;
   };
   const answerLegacyRejection = (request, reason, requestedVersion) => {
-    const rejection2 = modernOnlyStrictRejection({
+    const rejection3 = modernOnlyStrictRejection({
       kind: "legacy",
       reason,
       ...requestedVersion !== void 0 && { requestedVersion }
     }, SUPPORTED_MODERN_PROTOCOL_VERSIONS);
-    if (rejection2 === void 0) return Promise.resolve();
-    reportError(/* @__PURE__ */ new Error(`Rejected 2025-era request on a modern-only stdio connection (${rejection2.cell}): ${rejection2.message}`));
-    return writeErrorResponse(request.id, rejection2.code, rejection2.message, rejection2.data);
+    if (rejection3 === void 0) return Promise.resolve();
+    reportError(/* @__PURE__ */ new Error(`Rejected 2025-era request on a modern-only stdio connection (${rejection3.cell}): ${rejection3.message}`));
+    return writeErrorResponse(request.id, rejection3.code, rejection3.message, rejection3.data);
   };
   const onInstanceClosed = (channel) => {
     if (closing || channel === discarding) return;
@@ -34474,6 +34532,11 @@ function walk(value, keep, drop) {
 }
 
 // node_modules/@chrischall/mcp-utils/dist/response/index.js
+function textResult(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
 function errorResult(message) {
   return {
     content: [{ type: "text", text: redactSecrets(message) }],
@@ -34481,6 +34544,402 @@ function errorResult(message) {
   };
 }
 
+// node_modules/@chrischall/mcp-utils/dist/server/confirmation.js
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+
+// node_modules/@chrischall/mcp-utils/dist/server/canonical.js
+function canonicalJson(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean")
+    return JSON.stringify(value);
+  if (value === void 0)
+    return "null";
+  if (typeof value === "number")
+    return Number.isFinite(value) ? JSON.stringify(value) : `{"$num":"${String(value)}"}`;
+  if (typeof value === "bigint")
+    return `{"$bigint":"${value.toString()}"}`;
+  if (typeof value === "function" || typeof value === "symbol") {
+    throw new TypeError(`confirmation: cannot bind a ${typeof value} argument value.`);
+  }
+  if (Array.isArray(value))
+    return `[${value.map(canonicalJson).join(",")}]`;
+  if (value instanceof Date) {
+    return `{"$date":${JSON.stringify(Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString())}}`;
+  }
+  if (ArrayBuffer.isView(value)) {
+    const bytes = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    return `{"$bytes":${JSON.stringify(bytes.toString("base64"))}}`;
+  }
+  if (value instanceof ArrayBuffer)
+    return `{"$bytes":${JSON.stringify(Buffer.from(value).toString("base64"))}}`;
+  if (value instanceof Map) {
+    const entries2 = [...value.entries()].map(([k, v]) => `[${canonicalJson(k)},${canonicalJson(v)}]`).sort();
+    return `{"$map":[${entries2.join(",")}]}`;
+  }
+  if (value instanceof Set) {
+    return `{"$set":[${[...value].map(canonicalJson).sort().join(",")}]}`;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) {
+    throw new TypeError("confirmation: cannot bind a non-plain object argument value (class instance).");
+  }
+  const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return `{${entries.map(([k, v]) => `${JSON.stringify(escapeKey(k))}:${canonicalJson(v)}`).join(",")}}`;
+}
+function escapeKey(key) {
+  return key.startsWith("$") ? `$${key}` : key;
+}
+
+// node_modules/@chrischall/mcp-utils/dist/server/confirmation.js
+var DEFAULT_REQUEST_KEY = "confirmation";
+var DEFAULT_CONFIRMATION_LABEL = "Confirm this action should proceed.";
+var UNSUPPORTED_NOTE = "Nothing was done because this client cannot show a confirmation prompt (it declares no MCP elicitation capability), and this action is never taken without one";
+var STATE_PREFIX = "mcpu.confirm.v1.";
+function bindingKey(binding) {
+  if (binding.ttlSeconds !== void 0 && !(Number.isFinite(binding.ttlSeconds) && binding.ttlSeconds > 0)) {
+    throw new RangeError("requireConfirmation: binding.ttlSeconds must be a finite number greater than 0.");
+  }
+  const key = typeof binding.key === "string" ? Buffer.from(binding.key, "utf8") : Buffer.from(binding.key);
+  if (key.length < 32) {
+    throw new RangeError("requireConfirmation: binding.key must be at least 32 bytes.");
+  }
+  return key;
+}
+function commitment(action, args) {
+  return createHash("sha256").update(`${action}\0${canonicalJson(args)}`).digest("base64url");
+}
+function mintState(key, action, binding) {
+  const exp = Math.floor(Date.now() / 1e3) + (binding.ttlSeconds ?? 600);
+  const body = Buffer.from(JSON.stringify({ c: commitment(action, binding.args), exp })).toString("base64url");
+  const mac3 = createHmac("sha256", key).update(`${STATE_PREFIX}${body}`).digest("base64url");
+  return `${STATE_PREFIX}${body}.${mac3}`;
+}
+function verifyState(key, action, binding, state) {
+  if (typeof state !== "string" || !state.startsWith(STATE_PREFIX))
+    return false;
+  const rest = state.slice(STATE_PREFIX.length);
+  const dot = rest.indexOf(".");
+  if (dot < 0)
+    return false;
+  const body = rest.slice(0, dot);
+  const mac3 = Buffer.from(rest.slice(dot + 1), "base64url");
+  const expected = createHmac("sha256", key).update(`${STATE_PREFIX}${body}`).digest();
+  if (mac3.length !== expected.length || !timingSafeEqual(mac3, expected))
+    return false;
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+  } catch {
+    return false;
+  }
+  if (typeof payload.exp !== "number" || payload.exp * 1e3 <= Date.now())
+    return false;
+  const want = Buffer.from(commitment(action, binding.args));
+  const got = Buffer.from(typeof payload.c === "string" ? payload.c : "");
+  return got.length === want.length && timingSafeEqual(got, want);
+}
+function echoedState(ctx) {
+  const accessor = ctx.mcpReq.requestState;
+  return typeof accessor === "function" ? accessor() : void 0;
+}
+function requireConfirmation(ctx, options) {
+  const requestKey = options.requestKey ?? DEFAULT_REQUEST_KEY;
+  const key = options.binding ? bindingKey(options.binding) : void 0;
+  const confirmationSchema = external_exports.object({
+    confirmed: external_exports.boolean().describe(options.confirmationLabel ?? DEFAULT_CONFIRMATION_LABEL)
+  });
+  const ask = () => {
+    const preview = {
+      action: options.action,
+      ...options.details === void 0 ? {} : { details: options.details }
+    };
+    return inputRequired({
+      inputRequests: {
+        [requestKey]: inputRequired.elicit({
+          message: `${options.message}
+${JSON.stringify(preview, null, 2)}`,
+          requestedSchema: confirmationSchema
+        })
+      },
+      ...key && options.binding ? { requestState: mintState(key, options.action, options.binding) } : {}
+    });
+  };
+  const response = inputResponse(ctx.mcpReq.inputResponses, requestKey);
+  const accepted = acceptedContent(ctx.mcpReq.inputResponses, requestKey, confirmationSchema);
+  if (response.kind === "missing") {
+    if (callerAcceptsFormElicitation(ctx) === false) {
+      return textResult({
+        confirmed: false,
+        dispatched: false,
+        action: options.action,
+        reason: "confirmation-unsupported",
+        note: options.unsupportedNote ? `${UNSUPPORTED_NOTE}. ${options.unsupportedNote}` : `${UNSUPPORTED_NOTE}.`
+      });
+    }
+    return ask();
+  }
+  if (response.kind === "elicit" && response.action === "accept" && accepted?.confirmed === true) {
+    if (key && options.binding) {
+      const state = echoedState(ctx);
+      if (state === void 0 || state === null) {
+        return errorResult(`Confirmation for ${options.action} was accepted, but the retry carried no requestState, so it cannot be checked against the prompt that was shown. Nothing was done. The likely cause is that the MCP client or host does not round-trip requestState (it must echo the requestState from the input_required result back on the retry); asking again would loop.`);
+      }
+      if (!verifyState(key, options.action, options.binding, state))
+        return ask();
+    }
+    return void 0;
+  }
+  return textResult({
+    confirmed: false,
+    cancelled: true,
+    action: options.action,
+    note: "Nothing was changed because the confirmation was declined, cancelled, or left unchecked."
+  });
+}
+
+// node_modules/@chrischall/mcp-utils/dist/server/confirm-token.js
+import { createHash as createHash2, createHmac as createHmac2, randomBytes, timingSafeEqual as timingSafeEqual2 } from "node:crypto";
+function createSpentTokenStore() {
+  const spent = /* @__PURE__ */ new Map();
+  return {
+    has: (nonce) => spent.has(nonce),
+    add: (nonce, exp) => {
+      spent.set(nonce, exp);
+    },
+    prune: (now) => {
+      for (const [nonce, exp] of spent)
+        if (exp < now)
+          spent.delete(nonce);
+    },
+    clear: () => spent.clear(),
+    get size() {
+      return spent.size;
+    }
+  };
+}
+var PROCESS_SPENT = createSpentTokenStore();
+var PREFIX = "mcpu.token.v1.";
+var DEFAULT_TTL_SECONDS = 600;
+function tokenKey(key) {
+  const bytes = typeof key === "string" ? Buffer.from(key, "utf8") : Buffer.from(key);
+  if (bytes.length < 32)
+    throw new RangeError("confirm token: key must be at least 32 bytes.");
+  return bytes;
+}
+function ttlOf(ttlSeconds) {
+  if (ttlSeconds === void 0)
+    return DEFAULT_TTL_SECONDS;
+  if (!(Number.isFinite(ttlSeconds) && ttlSeconds > 0)) {
+    throw new RangeError("confirm token: ttlSeconds must be a finite number greater than 0.");
+  }
+  return ttlSeconds;
+}
+function sign(key, body) {
+  return createHmac2("sha256", key).update(`${PREFIX}${body}`).digest();
+}
+function hashConfirmPayload(payload) {
+  return createHash2("sha256").update(canonicalJson(payload)).digest("base64url");
+}
+function issueConfirmToken(key, binding, options = {}) {
+  const k = tokenKey(key);
+  const now = options.now ?? Date.now();
+  const exp = now + ttlOf(options.ttlSeconds) * 1e3;
+  const claims = {
+    t: binding.tool,
+    ...binding.account === void 0 ? {} : { a: binding.account },
+    g: binding.target,
+    ...binding.revision === void 0 ? {} : { r: binding.revision },
+    h: binding.payloadHash,
+    exp,
+    n: randomBytes(16).toString("base64url")
+  };
+  const body = Buffer.from(JSON.stringify(claims), "utf8").toString("base64url");
+  return { token: `${PREFIX}${body}.${sign(k, body).toString("base64url")}`, expiresAt: new Date(exp).toISOString() };
+}
+function parseClaims(body) {
+  try {
+    const claims = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+    return claims && typeof claims === "object" ? claims : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function verifyConfirmToken(key, token, binding, options = {}) {
+  const k = tokenKey(key);
+  const now = options.now ?? Date.now();
+  const spent = options.spent ?? PROCESS_SPENT;
+  spent.prune(now);
+  if (!token.startsWith(PREFIX))
+    return { ok: false, error: "TOKEN_INVALID" };
+  const rest = token.slice(PREFIX.length);
+  const dot = rest.indexOf(".");
+  const body = dot < 0 ? "" : rest.slice(0, dot);
+  const mac3 = Buffer.from(dot < 0 ? "" : rest.slice(dot + 1), "base64url");
+  const expected = sign(k, body);
+  if (!body || mac3.length !== expected.length || !timingSafeEqual2(mac3, expected))
+    return { ok: false, error: "TOKEN_INVALID" };
+  const claims = parseClaims(body);
+  if (!claims)
+    return { ok: false, error: "TOKEN_INVALID" };
+  if (claims.t !== binding.tool || claims.a !== binding.account || claims.g !== binding.target) {
+    return { ok: false, error: "TOKEN_INVALID" };
+  }
+  if (spent.has(claims.n))
+    return { ok: false, error: "TOKEN_REUSED" };
+  if (now > claims.exp)
+    return { ok: false, error: "TOKEN_EXPIRED" };
+  if (claims.r !== binding.revision)
+    return { ok: false, error: "DRAFT_CHANGED", reason: "revision-changed" };
+  if (claims.h !== binding.payloadHash)
+    return { ok: false, error: "DRAFT_CHANGED", reason: "payload-changed" };
+  spent.add(claims.n, claims.exp);
+  return { ok: true };
+}
+var CONFIRM_TOKEN_INSTRUCTION = "Show this preview to the user verbatim and proceed only after they explicitly approve in chat. Then call again with confirmToken.";
+var confirmTokenParam = external_exports.string().optional().describe(`ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat \u2014 never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.`);
+var TOKEN_ERROR_NOTE = {
+  TOKEN_EXPIRED: "Nothing was sent or changed: the confirmToken expired. Call again WITHOUT confirmToken for a fresh preview, and ask the user to approve it again.",
+  TOKEN_REUSED: "Nothing was sent or changed by this call: this confirmToken was already used, and one approval acts once. If doing it again is really intended, call again WITHOUT confirmToken and get a new approval.",
+  TOKEN_INVALID: "Nothing was sent or changed: this confirmToken was not issued by this server for this tool, account and target (or the server has restarted since). Call again WITHOUT confirmToken for a fresh preview and approval."
+};
+var CHANGED_NOTE = {
+  "revision-changed": "Nothing was sent or changed: the target was edited since the user approved it (its version rotated), so what would happen is not what they saw.",
+  "payload-changed": "Nothing was sent or changed: what would happen no longer matches what the user approved."
+};
+function isToolResult(value) {
+  return Array.isArray(value.content);
+}
+function rejection2(data) {
+  return { ...textResult({ status: "confirmation-rejected", confirmed: false, dispatched: false, ...data }), isError: true };
+}
+async function tokenConfirmation(action, fb) {
+  const subject = await fb.subject();
+  if (isToolResult(subject))
+    return subject;
+  const binding = {
+    tool: fb.tool,
+    ...fb.account === void 0 ? {} : { account: fb.account },
+    target: subject.target,
+    ...subject.revision === void 0 ? {} : { revision: subject.revision },
+    payloadHash: hashConfirmPayload(subject.payload)
+  };
+  const phaseOne = () => {
+    const { token, expiresAt } = issueConfirmToken(fb.key, binding, { ttlSeconds: fb.ttlSeconds });
+    return {
+      action,
+      preview: subject.preview,
+      confirmToken: token,
+      expiresAt,
+      ttlSeconds: ttlOf(fb.ttlSeconds),
+      instruction: fb.instruction ?? CONFIRM_TOKEN_INSTRUCTION
+    };
+  };
+  if (!fb.confirmToken) {
+    return textResult({ status: "confirmation-required", confirmed: false, dispatched: false, ...phaseOne() });
+  }
+  const verdict = verifyConfirmToken(fb.key, fb.confirmToken, binding, { spent: fb.spent });
+  if (verdict.ok)
+    return void 0;
+  if (verdict.error === "DRAFT_CHANGED") {
+    return rejection2({
+      error: "DRAFT_CHANGED",
+      reason: verdict.reason,
+      note: `${CHANGED_NOTE[verdict.reason]} The current preview and a fresh confirmToken are below.`,
+      ...phaseOne()
+    });
+  }
+  return rejection2({ error: verdict.error, action, note: TOKEN_ERROR_NOTE[verdict.error] });
+}
+async function requireConfirmationWithFallback(ctx, options) {
+  const { tokenFallback, ...confirmation } = options;
+  if (tokenFallback && callerAcceptsFormElicitation(ctx) === false) {
+    return tokenConfirmation(options.action, tokenFallback);
+  }
+  return requireConfirmation(ctx, confirmation);
+}
+
+// node_modules/@chrischall/mcp-utils/dist/server/confirm-env.js
+import { createHash as createHash3, randomBytes as randomBytes2 } from "node:crypto";
+
+// node_modules/@chrischall/mcp-utils/dist/config/index.js
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+var PLACEHOLDER_RE = /^\$\{[^}]*\}$/;
+function readEnvVar(key, opts = {}) {
+  const env = opts.env ?? process.env;
+  const raw = env[key];
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (trimmed.length > 0 && trimmed !== "undefined" && trimmed !== "null" && !PLACEHOLDER_RE.test(trimmed)) {
+      return trimmed;
+    }
+  }
+  return opts.default;
+}
+function expandPath(p) {
+  let expanded = p;
+  if (p === "~") {
+    expanded = homedir();
+  } else if (p.startsWith("~/")) {
+    expanded = join(homedir(), p.slice(2));
+  }
+  return isAbsolute(expanded) ? expanded : resolve(expanded);
+}
+
+// node_modules/@chrischall/mcp-utils/dist/server/confirm-env.js
+var MODES = /* @__PURE__ */ new Set(["ask-user", "auto", "refuse"]);
+var DEFAULT_TTL_SECONDS2 = 600;
+var warned = /* @__PURE__ */ new Set();
+function readConfirmMode(env = process.env) {
+  const raw = readEnvVar("MCP_CONFIRM_MODE", { env })?.trim().toLowerCase();
+  if (!raw)
+    return "ask-user";
+  if (MODES.has(raw))
+    return raw;
+  if (!warned.has(raw)) {
+    warned.add(raw);
+    process.stderr.write(`MCP_CONFIRM_MODE="${raw}" is not one of ask-user, auto, refuse; treating it as refuse.
+`);
+  }
+  return "refuse";
+}
+function confirmTtlFromEnv(env = process.env) {
+  const raw = readEnvVar("MCP_CONFIRM_TTL_SECONDS", { env })?.trim();
+  return raw && /^[1-9]\d*$/.test(raw) ? Number(raw) : DEFAULT_TTL_SECONDS2;
+}
+var processKey;
+function confirmKeyFromEnv(env = process.env) {
+  const secret = readEnvVar("MCP_CONFIRM_SECRET", { env });
+  if (secret)
+    return createHash3("sha256").update(secret, "utf8").digest();
+  processKey ??= randomBytes2(32);
+  return processKey;
+}
+var CONFIRM_TOKEN_AUTO_INSTRUCTION = "Nothing has been done yet. Review this preview; if it is what was intended, call again with the same arguments plus confirmToken. (This server runs with MCP_CONFIRM_MODE=auto, so the user's approval in chat is not required.)";
+var REFUSE_HINT = "Set MCP_CONFIRM_MODE=ask-user on the server to allow two-step confirmation instead.";
+function confirmationFromEnv(options) {
+  const { tool, account, confirmToken, subject, instruction, spent, env = process.env, ...confirmation } = options;
+  const mode = readConfirmMode(env);
+  if (mode === "refuse") {
+    return {
+      ...confirmation,
+      unsupportedNote: confirmation.unsupportedNote ? `${confirmation.unsupportedNote} ${REFUSE_HINT}` : REFUSE_HINT
+    };
+  }
+  return {
+    ...confirmation,
+    tokenFallback: {
+      key: confirmKeyFromEnv(env),
+      tool,
+      ...account === void 0 ? {} : { account },
+      ...confirmToken === void 0 ? {} : { confirmToken },
+      subject,
+      ttlSeconds: confirmTtlFromEnv(env),
+      instruction: mode === "auto" ? CONFIRM_TOKEN_AUTO_INSTRUCTION : instruction ?? CONFIRM_TOKEN_INSTRUCTION,
+      ...spent === void 0 ? {} : { spent }
+    }
+  };
+}
+
 // node_modules/@chrischall/mcp-utils/dist/server/index.js
 var SERVER_PROTOCOL_VERSIONS = Object.freeze([
   "2026-07-28",
@@ -34656,31 +35115,6 @@ function runMcp(opts) {
   return handle;
 }
 
-// node_modules/@chrischall/mcp-utils/dist/config/index.js
-import { homedir } from "node:os";
-import { isAbsolute, join, resolve } from "node:path";
-var PLACEHOLDER_RE = /^\$\{[^}]*\}$/;
-function readEnvVar(key, opts = {}) {
-  const env = opts.env ?? process.env;
-  const raw = env[key];
-  if (typeof raw === "string") {
-    const trimmed = raw.trim();
-    if (trimmed.length > 0 && trimmed !== "undefined" && trimmed !== "null" && !PLACEHOLDER_RE.test(trimmed)) {
-      return trimmed;
-    }
-  }
-  return opts.default;
-}
-function expandPath(p) {
-  let expanded = p;
-  if (p === "~") {
-    expanded = homedir();
-  } else if (p.startsWith("~/")) {
-    expanded = join(homedir(), p.slice(2));
-  }
-  return isAbsolute(expanded) ? expanded : resolve(expanded);
-}
-
 // node_modules/@chrischall/mcp-utils/dist/http/index.js
 var MAX_AGE_RE = /(?:^|;)\s*Max-Age\s*=\s*(-?\d+)\s*(?:;|$)/i;
 var EXPIRES_RE = /(?:^|;)\s*Expires\s*=\s*([^;]+)/i;
@@ -34782,7 +35216,7 @@ function toolAnnotations(opts = {}) {
 }
 
 // src/version.ts
-var VERSION = "1.1.4";
+var VERSION = "1.2.0";
 
 // node_modules/@chrischall/mcp-utils/dist/session/index.js
 import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync, unlinkSync } from "node:fs";
@@ -35112,7 +35546,7 @@ var SimplePracticeClient = class {
    * through, so a link outside `*.clientsecure.me` cannot redirect a token.
    *
    * Separate from {@link adoptPracticeHost} so a caller that only wants to
-   * *name* the practice — a dry run reporting what it would do — can do that
+   * *name* the practice — a preview reporting what it would do — can do that
    * without the side effect. Answering a question should not move the server.
    */
   validatePracticeHost(raw) {
@@ -35381,29 +35815,42 @@ function registerAuthTools(server, client2) {
   server.registerTool(
     "simplepractice_request_sign_in_link",
     {
-      description: "Ask SimplePractice to email a sign-in link to a Client Portal address. The portal has no password \u2014 this is how you sign in. Sends a real email and is rate-limited per email address AND per IP, so it requires confirm:true. A success does not prove the address has an account: the API answers identically for unknown addresses by design.",
+      description: "Ask SimplePractice to email a sign-in link to a Client Portal address. The portal has no password \u2014 this is how you sign in. Sends a real email and is rate-limited per email address AND per IP, so it asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). A success does not prove the address has an account: the API answers identically for unknown addresses by design.",
       annotations: toolAnnotations({ readOnly: false, idempotent: false, destructive: true }),
       inputSchema: external_exports.object({
         email: external_exports.string().email().describe("The email address the Client Portal is registered to."),
         practice: external_exports.string().min(1).optional().describe(
           'The practice whose portal to sign in to \u2014 the slug ("achievebalancetherapy"), the host, or the portal URL. Only needed when this server does not know the practice yet; signing in with an emailed link teaches it, and it then remembers.'
         ),
-        confirm: schemaConfirm
+        confirmToken: confirmTokenParam
       })
     },
-    async ({ email: email3, practice, confirm }) => {
-      if (!confirm) {
-        return minifiedResult({
-          dryRun: true,
-          wouldSend: "a Client Portal sign-in email",
-          to: email3,
-          // Named, not adopted. A dry run sends nothing, so it must not move
-          // the server either — silently overriding a SIMPLEPRACTICE_PRACTICE
-          // pin is not something an inert preview gets to do.
-          practiceHost: practice ? client2.validatePracticeHost(practice) : client2.portalHost(),
-          note: "Re-run with confirm:true to actually send it. Do not retry a failed send \u2014 SimplePractice locks out repeated sign-in requests."
-        });
-      }
+    async ({ email: email3, practice, confirmToken }, ctx) => {
+      const practiceHost = practice ? client2.validatePracticeHost(practice) : client2.portalHost();
+      const gate = await requireConfirmationWithFallback(
+        ctx,
+        confirmationFromEnv({
+          action: "sign_in.request_link",
+          message: "Review and confirm sending this Client Portal sign-in email:",
+          details: { to: email3, practiceHost },
+          tool: "simplepractice_request_sign_in_link",
+          account: practiceHost,
+          confirmToken,
+          subject: () => ({
+            // Nothing existing is acted on: the address is bound through the payload,
+            // so editing it between the calls is a DRAFT_CHANGED with a fresh preview.
+            target: "",
+            payload: { email: email3, practiceHost },
+            preview: {
+              wouldSend: "a Client Portal sign-in email",
+              to: email3,
+              practiceHost,
+              note: "Do not retry a failed send \u2014 SimplePractice locks out repeated sign-in requests."
+            }
+          })
+        })
+      );
+      if (gate) return gate;
       const send = async () => {
         const { expiresIn } = await requestSignInLink(client2, email3);
         return minifiedResult({

package/dist/client.js

@@ -110,7 +110,7 @@ export class SimplePracticeClient {
      * through, so a link outside `*.clientsecure.me` cannot redirect a token.
      *
      * Separate from {@link adoptPracticeHost} so a caller that only wants to
-     * *name* the practice — a dry run reporting what it would do — can do that
+     * *name* the practice — a preview reporting what it would do — can do that
      * without the side effect. Answering a question should not move the server.
      */
     validatePracticeHost(raw) {

package/dist/tools/auth.js

@@ -1,11 +1,11 @@
 import { z } from 'zod';
-import { minifiedResult, schemaConfirm, toolAnnotations } from '@chrischall/mcp-utils';
+import { confirmationFromEnv, confirmTokenParam, minifiedResult, requireConfirmationWithFallback, toolAnnotations, } from '@chrischall/mcp-utils';
 import { requestSignInLink, verifySignInPin, verifySignInToken } from '../auth.js';
 /**
  * No `view` here, deliberately.
  *
  * Nothing in this file answers with a SimplePractice record: every response is
- * a small object this server builds — local session state, a dry-run preview,
+ * a small object this server builds — local session state, a send preview,
  * the result of a sign-in exchange. There is no upstream payload to project or
  * strip, and none of these are reads a caller pages through, so the rung would
  * have nothing to switch between.
@@ -33,7 +33,7 @@ export function registerAuthTools(server, client) {
         });
     });
     server.registerTool('simplepractice_request_sign_in_link', {
-        description: 'Ask SimplePractice to email a sign-in link to a Client Portal address. The portal has no password — this is how you sign in. Sends a real email and is rate-limited per email address AND per IP, so it requires confirm:true. A success does not prove the address has an account: the API answers identically for unknown addresses by design.',
+        description: 'Ask SimplePractice to email a sign-in link to a Client Portal address. The portal has no password — this is how you sign in. Sends a real email and is rate-limited per email address AND per IP, so it asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). A success does not prove the address has an account: the API answers identically for unknown addresses by design.',
         annotations: toolAnnotations({ readOnly: false, idempotent: false, destructive: true }),
         inputSchema: z.object({
             email: z.string().email().describe('The email address the Client Portal is registered to.'),
@@ -42,21 +42,36 @@ export function registerAuthTools(server, client) {
                 .min(1)
                 .optional()
                 .describe('The practice whose portal to sign in to — the slug ("achievebalancetherapy"), the host, or the portal URL. Only needed when this server does not know the practice yet; signing in with an emailed link teaches it, and it then remembers.'),
-            confirm: schemaConfirm,
+            confirmToken: confirmTokenParam,
         }),
-    }, async ({ email, practice, confirm }) => {
-        if (!confirm) {
-            return minifiedResult({
-                dryRun: true,
-                wouldSend: 'a Client Portal sign-in email',
-                to: email,
-                // Named, not adopted. A dry run sends nothing, so it must not move
-                // the server either — silently overriding a SIMPLEPRACTICE_PRACTICE
-                // pin is not something an inert preview gets to do.
-                practiceHost: practice ? client.validatePracticeHost(practice) : client.portalHost(),
-                note: 'Re-run with confirm:true to actually send it. Do not retry a failed send — SimplePractice locks out repeated sign-in requests.',
-            });
-        }
+    }, async ({ email, practice, confirmToken }, ctx) => {
+        // Resolved, not adopted. The preview sends nothing, so it must not move
+        // the server either — silently overriding a SIMPLEPRACTICE_PRACTICE pin
+        // is not something an inert preview gets to do. It still refuses a
+        // non-portal address or an unknown practice before anything is asked.
+        const practiceHost = practice ? client.validatePracticeHost(practice) : client.portalHost();
+        const gate = await requireConfirmationWithFallback(ctx, confirmationFromEnv({
+            action: 'sign_in.request_link',
+            message: 'Review and confirm sending this Client Portal sign-in email:',
+            details: { to: email, practiceHost },
+            tool: 'simplepractice_request_sign_in_link',
+            account: practiceHost,
+            confirmToken,
+            subject: () => ({
+                // Nothing existing is acted on: the address is bound through the payload,
+                // so editing it between the calls is a DRAFT_CHANGED with a fresh preview.
+                target: '',
+                payload: { email, practiceHost },
+                preview: {
+                    wouldSend: 'a Client Portal sign-in email',
+                    to: email,
+                    practiceHost,
+                    note: 'Do not retry a failed send — SimplePractice locks out repeated sign-in requests.',
+                },
+            }),
+        }));
+        if (gate)
+            return gate;
         const send = async () => {
             const { expiresIn } = await requestSignInLink(client, email);
             return minifiedResult({

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 = '1.1.4'; // x-release-please-version
+export const VERSION = '1.2.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simplepractice-mcp",
-  "version": "1.1.4",
+  "version": "1.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)",
@@ -34,7 +34,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.4.0",
+    "@chrischall/mcp-utils": "^2.6.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "dotenv": "^18.0.0",
     "zod": "^4.6.5"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/simplepractice-mcp",
     "source": "github"
   },
-  "version": "1.1.4",
+  "version": "1.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "simplepractice-mcp",
-      "version": "1.1.4",
+      "version": "1.2.0",
       "transport": {
         "type": "stdio"
       },

package/skills/simplepractice/SKILL.md

@@ -26,10 +26,13 @@ The portal has **no password**. SimplePractice emails a one-time link (or a
    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. If the server
+3. `simplepractice_request_sign_in_link` with the user's portal email. It asks
+   for confirmation 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. Where the client cannot show a prompt, the
+   first call sends nothing and returns a preview plus a `confirmToken`: show
+   the user the preview, and only after they approve call again with the same
+   arguments and that `confirmToken`. 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