@chrischall/myatriumhealth-mcp 1.1.0 → 1.2.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Angi — find home-service pros by trade and city, read ratings, reviews and pro profiles. Angi serves its pages only to a real browser, so requests route through the user's own angi.com tab via the fetchproxy browser extension, reusing their existing session. The trade/city taxonomy is read from Angi's public sitemaps directly.",
-    "version": "1.1.0"
+    "version": "1.2.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "MyAtriumHealth",
       "source": "./",
       "description": "Read MyAtriumHealth (Epic MyChart) records — test results, medications, allergies, immunizations, health issues, visits — by relaying requests through the user's signed-in browser tab via the fetchproxy bridge.",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "myatriumhealth-mcp",
   "displayName": "MyAtriumHealth",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MyAtriumHealth (Epic MyChart) access for Claude — test results, medications, allergies, immunizations, visits",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -111,11 +111,13 @@ call prints a pair code — approve it once in the Transporter popup.
 | `MAH_PASSWORD` | — | Portal password. Both are required; setting only one falls back to the bridge (with a warning). |
 | `MAH_DEVICE_FILE` | `~/.myatriumhealth-mcp/device.json` | Session state (0600). Holds the **live cookie jar** as well as the device token — treat as a credential. |
 | `MAH_WS_PORT` | `37149` | fetchproxy concentrator port (bridge mode only). The whole fleet shares this one port; override only when hosting. |
+| `MAH_READ_ONLY` | `false` | `true` refuses `mah_reply_message` sends (previews still work). The tool stays listed either way. |
 
 ## Tools
 
-All read-only except `mah_set_active_patient`, which changes only which patient this
-connector reads — it writes nothing to any chart.
+All read-only except two. `mah_set_active_patient` changes only which patient this
+connector reads — it writes nothing to any chart. `mah_reply_message` **sends a message
+a provider will see**, which cannot be undone: see [Replying](#replying).
 
 Every reading tool returns `{ patient, data }`, so the chart a response belongs to is
 stated rather than inferred.
@@ -132,7 +134,8 @@ stated rather than inferred.
 | `mah_list_goals` | Patient goals |
 | `mah_get_health_summary` | Health-summary header and action plans |
 | `mah_list_message_folders` | Message Center folders with unread counts |
-| `mah_list_messages` | Message Center conversations for a folder |
+| `mah_list_messages` | Message Center conversations for a folder, each with the `conversationId` to reply to |
+| `mah_reply_message` | Reply to a conversation as the active patient — previews unless `confirm: true` *(irreversible)* |
 | `mah_list_insurance` | Insurance coverages on file |
 | `mah_list_care_team` | Care team providers, internal and external |
 | `mah_list_billing_accounts` | Billing accounts and balances (parsed from HTML) |
@@ -186,6 +189,28 @@ local organization returns HTTP 500. The client assembles this from
 
 `api/item-feed/FetchItemFeed` still needs parameters that have not been captured.
 
+## Replying
+
+`mah_reply_message` takes a `conversationId` from `mah_list_messages`, a plain-text
+`body`, and optionally `attachments`. It replies **as whichever patient is active**.
+
+- **It previews by default.** Without `confirm: true` it returns the thread, recipients
+  and body and sends nothing. The send itself is irreversible and provider-visible.
+- **`MAH_READ_ONLY=true` refuses every send.** The tool stays registered — a hosted
+  connector publishes the tool list of a child with no env of its own, so a tool that
+  registered only when writes were allowed would disappear for everyone.
+- **Limits come from the portal**: 500 characters, 3 attachments, 10 MB per document or
+  image (64 MB per video), BMP/DOC/DOCX/JPEG/JPG/PDF/PNG/TIF/TIFF and common video types.
+- **Attachments need bridge-less mode.** fetchproxy relays a request body as text, which
+  a binary upload does not survive, so through the browser bridge a reply with
+  attachments is refused before anything is uploaded.
+- **A send is never retried.** If the session re-authenticates between confirming the
+  patient and sending, nothing is sent: a fresh sign-in serves the account holder, and
+  the reply would go out as them. If the portal's answer to the send cannot be read, the
+  result says the reply *may* have been sent — check the thread before trying again.
+- On success it returns the new message's `wmgId` and `deliveryInstantISO`, found by
+  reading the thread back (the send itself returns only the thread id).
+
 ## Development
 
 ```sh

package/dist/bundle.js

@@ -25177,17 +25177,17 @@ var require_sender = __commonJS({
        */
       ping(data, mask, cb) {
         let byteLength;
-        let readOnly;
+        let readOnly2;
         if (typeof data === "string") {
           byteLength = Buffer.byteLength(data);
-          readOnly = false;
+          readOnly2 = false;
         } else if (isBlob(data)) {
           byteLength = data.size;
-          readOnly = false;
+          readOnly2 = false;
         } else {
           data = toBuffer(data);
           byteLength = data.length;
-          readOnly = toBuffer.readOnly;
+          readOnly2 = toBuffer.readOnly;
         }
         if (byteLength > 125) {
           throw new RangeError("The data size must not be greater than 125 bytes");
@@ -25199,7 +25199,7 @@ var require_sender = __commonJS({
           mask,
           maskBuffer: this._maskBuffer,
           opcode: 9,
-          readOnly,
+          readOnly: readOnly2,
           rsv1: false
         };
         if (isBlob(data)) {
@@ -25224,17 +25224,17 @@ var require_sender = __commonJS({
        */
       pong(data, mask, cb) {
         let byteLength;
-        let readOnly;
+        let readOnly2;
         if (typeof data === "string") {
           byteLength = Buffer.byteLength(data);
-          readOnly = false;
+          readOnly2 = false;
         } else if (isBlob(data)) {
           byteLength = data.size;
-          readOnly = false;
+          readOnly2 = false;
         } else {
           data = toBuffer(data);
           byteLength = data.length;
-          readOnly = toBuffer.readOnly;
+          readOnly2 = toBuffer.readOnly;
         }
         if (byteLength > 125) {
           throw new RangeError("The data size must not be greater than 125 bytes");
@@ -25246,7 +25246,7 @@ var require_sender = __commonJS({
           mask,
           maskBuffer: this._maskBuffer,
           opcode: 10,
-          readOnly,
+          readOnly: readOnly2,
           rsv1: false
         };
         if (isBlob(data)) {
@@ -25282,17 +25282,17 @@ var require_sender = __commonJS({
         let opcode = options.binary ? 2 : 1;
         let rsv1 = options.compress;
         let byteLength;
-        let readOnly;
+        let readOnly2;
         if (typeof data === "string") {
           byteLength = Buffer.byteLength(data);
-          readOnly = false;
+          readOnly2 = false;
         } else if (isBlob(data)) {
           byteLength = data.size;
-          readOnly = false;
+          readOnly2 = false;
         } else {
           data = toBuffer(data);
           byteLength = data.length;
-          readOnly = toBuffer.readOnly;
+          readOnly2 = toBuffer.readOnly;
         }
         if (this._firstFragment) {
           this._firstFragment = false;
@@ -25312,7 +25312,7 @@ var require_sender = __commonJS({
           mask: options.mask,
           maskBuffer: this._maskBuffer,
           opcode,
-          readOnly,
+          readOnly: readOnly2,
           rsv1
         };
         if (isBlob(data)) {
@@ -27298,6 +27298,20 @@ var require_websocket_server = __commonJS({
   }
 });
 
+// node_modules/@chrischall/mcp-utils/dist/cancel/index.js
+import { AsyncLocalStorage } from "node:async_hooks";
+var storage = new AsyncLocalStorage();
+function withCallSignal(signal, fn, request) {
+  return signal ? storage.run({ signal, ...request ? { request } : {} }, fn) : fn();
+}
+
+// node_modules/@chrischall/mcp-utils/dist/caller/index.js
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
+var storage2 = new AsyncLocalStorage2();
+function withCallerCapabilities(capabilities, fn) {
+  return capabilities ? storage2.run(capabilities, fn) : fn();
+}
+
 // node_modules/@modelcontextprotocol/server/dist/chunk-Br0eD_fh.mjs
 var __create2 = Object.create;
 var __defProp2 = Object.defineProperty;
@@ -34838,11 +34852,11 @@ var require_resolve = /* @__PURE__ */ __commonJSMin(((exports) => {
     "enum",
     "const"
   ]);
-  function inlineRef(schema, limit = true) {
+  function inlineRef(schema, limit2 = true) {
     if (typeof schema == "boolean") return true;
-    if (limit === true) return !hasRef(schema);
-    if (!limit) return false;
-    return countKeys(schema) <= limit;
+    if (limit2 === true) return !hasRef(schema);
+    if (!limit2) return false;
+    return countKeys(schema) <= limit2;
   }
   exports.inlineRef = inlineRef;
   const REF_KEYWORDS = /* @__PURE__ */ new Set([
@@ -61759,17 +61773,73 @@ Hint: ${err.hint}`);
   }
   throw err;
 }
+function mcpRequestFrom(args) {
+  const ctx = args.at(-1);
+  if (typeof ctx !== "object" || ctx === null)
+    return void 0;
+  const req = ctx.mcpReq;
+  if (typeof req !== "object" || req === null)
+    return void 0;
+  return typeof req.notify === "function" ? req : void 0;
+}
+function callSignalFrom(args) {
+  const ctx = args.at(-1);
+  if (typeof ctx !== "object" || ctx === null)
+    return void 0;
+  const req = ctx.mcpReq;
+  if (typeof req !== "object" || req === null)
+    return void 0;
+  const signal = req.signal;
+  return signal instanceof AbortSignal ? signal : void 0;
+}
+function declaredCapabilitiesFrom(server) {
+  const inner = server.server;
+  if (typeof inner !== "object" || inner === null)
+    return void 0;
+  const read = inner.getClientCapabilities;
+  if (typeof read !== "function")
+    return void 0;
+  try {
+    const declared = read.call(inner);
+    return typeof declared === "object" && declared !== null ? declared : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function surfaceToolHints(server) {
   const register2 = server.registerTool.bind(server);
-  server.registerTool = (name, config2, cb) => register2(name, config2, (...args) => {
-    let result;
-    try {
-      result = cb(...args);
-    } catch (err) {
-      return hintResultOrRethrow(err);
-    }
-    return result instanceof Promise ? result.catch(hintResultOrRethrow) : result;
-  });
+  server.registerTool = (name, config2, cb) => register2(name, config2, (...args) => (
+    // THE CALLER'S CANCELLATION, made ambient for the whole handler
+    // (`cancel/index.ts`). The SDK delivers it and the fleet ignored it:
+    // measured against @modelcontextprotocol/server 2.0.0, a cancelled
+    // call aborts `ctx.mcpReq.signal` with the caller's reason and the
+    // handler runs to completion regardless — so the HTTP request stays
+    // in flight, the child keeps burning metered CPU, and the upstream
+    // keeps being hit for somebody who has gone. claude.ai sent 101
+    // cancellations in the week to 2026-09-20.
+    //
+    // Here because this is the one wrapper every tool already passes
+    // through: threading the signal by hand would mean editing several
+    // hundred handlers and missing exactly the ones nobody edits.
+    withCallSignal(callSignalFrom(args), () => (
+      // WHAT THE CALLER CAN DO, made ambient for the same reason and in
+      // the same place (`caller/index.ts`). Only the 2025-era half needs
+      // the wrapper — a 2026-07-28 request answers for itself off its own
+      // envelope — but a guarded tool that cannot tell whether the caller
+      // can be shown a prompt returns one the SDK then refuses to deliver,
+      // and that refusal reaches the caller as an unexplained protocol
+      // error it had no chance to catch.
+      withCallerCapabilities(declaredCapabilitiesFrom(server), () => {
+        let result;
+        try {
+          result = cb(...args);
+        } catch (err) {
+          return hintResultOrRethrow(err);
+        }
+        return result instanceof Promise ? result.catch(hintResultOrRethrow) : result;
+      })
+    ), mcpRequestFrom(args))
+  ));
 }
 async function createMcpServer(opts) {
   const server = new McpServer({ name: opts.name, version: opts.version }, { supportedProtocolVersions: [...SERVER_PROTOCOL_VERSIONS] });
@@ -61842,6 +61912,20 @@ function readEnvVar(key, opts = {}) {
   }
   return opts.default;
 }
+var TRUE_TOKENS = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+var FALSE_TOKENS = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
+function parseBoolEnv(key, opts = {}) {
+  const fallback = opts.default ?? false;
+  const raw = readEnvVar(key, { env: opts.env });
+  if (raw === void 0)
+    return fallback;
+  const token = raw.toLowerCase();
+  if (TRUE_TOKENS.has(token))
+    return true;
+  if (FALSE_TOKENS.has(token))
+    return false;
+  return fallback;
+}
 function readPortEnv(key, fallback, opts = {}) {
   const raw = readEnvVar(key, { env: opts.env });
   if (raw === void 0)
@@ -61890,6 +61974,7 @@ function toolAnnotations(opts = {}) {
     ...opts.title !== void 0 ? { title: opts.title } : {},
     readOnlyHint: opts.readOnly ?? true,
     ...opts.idempotent !== void 0 ? { idempotentHint: opts.idempotent } : {},
+    ...opts.destructive !== void 0 ? { destructiveHint: opts.destructive } : {},
     ...opts.openWorld !== void 0 ? { openWorldHint: opts.openWorld } : {}
   };
 }
@@ -62383,7 +62468,25 @@ var MyAtriumHealthAuth = class {
   }
 };
 
+// src/transport.ts
+var NotAcceptedError = class extends McpToolError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "NotAcceptedError";
+  }
+};
+
 // src/client.ts
+var UPLOAD_CONTEXT = (organizationId) => ({
+  form: {
+    AddDCSToCache: "true",
+    IsPending: "true",
+    DCSSource: "820",
+    OrganizationId: organizationId,
+    EncryptDCSOnRemote: ""
+  },
+  context: { isPending: true, addDCSToCache: true, dcsSource: "820", organizationId }
+});
 var TOKEN_PAGE = "Home";
 var TOKEN_RE = /name="__RequestVerificationToken"[^>]*value="([^"]+)"/;
 var NONCE_RE = /id=['"]cspScripts['"][^>]*nonce=['"]([0-9a-f]{32})['"]/;
@@ -62402,7 +62505,7 @@ function emptyBody(what) {
   );
 }
 function notSignedIn() {
-  return new McpToolError(
+  return new NotAcceptedError(
     "Not signed in to MyAtriumHealth \u2014 the portal returned a sign-in or verification page.",
     {
       hint: "Open https://my.atriumhealth.org/ in Chrome and sign in, completing any verification prompt, then retry. MyChart sessions are short-lived, so this recurs between uses."
@@ -62475,7 +62578,7 @@ var MyAtriumHealthClient = class {
   parse(body, endpoint) {
     const trimmed = body.trimStart();
     if (trimmed === "") throw emptyBody(endpoint);
-    if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("[") && !trimmed.startsWith('"')) {
       if (isAuthWall(body)) throw notSignedIn();
       const oops = /<title>([^<]*)</.exec(body)?.[1]?.trim();
       throw new McpToolError(
@@ -62496,22 +62599,90 @@ var MyAtriumHealthClient = class {
     return this.parse(res.body, endpoint);
   }
   /** POST a modern `api/<area>/<Action>` endpoint. Body defaults to `{}`. */
-  async api(endpoint, body = {}) {
+  async api(endpoint, body = {}, opts = {}) {
+    return this.postJson(`api/${endpoint.replace(/^\/+/, "")}`, body, endpoint, opts);
+  }
+  /** POST a JSON body to any path under the app root, as the web app does. */
+  async postJson(path, body, endpoint, opts = {}) {
     const token = await this.getToken();
     return this.send(
       {
         method: "POST",
-        path: `api/${endpoint.replace(/^\/+/, "")}`,
+        path,
         headers: {
           __RequestVerificationToken: token,
           Accept: "application/json",
           "Content-Type": "application/json"
         },
-        body: typeof body === "string" ? body : JSON.stringify(body)
+        body: typeof body === "string" ? body : JSON.stringify(body),
+        ...opts.replay === false ? { replay: false } : {}
       },
       endpoint
     );
   }
+  /**
+   * One conversation with its messages, viewers and reply flags. The thread id
+   * is the `hthId` from GetConversationList; the body is what the app sends
+   * when a thread is opened.
+   */
+  async conversationDetails(id, organizationId = "") {
+    return this.api("conversations/GetConversationDetails", {
+      id,
+      messageId: "",
+      organizationId,
+      PageNonce: await this.pageNonce()
+    });
+  }
+  /**
+   * Upload one file for a message, exactly as the composer does. The file is
+   * held PENDING: it reaches nobody until a send names its DocumentId, and
+   * {@link deleteDocument} discards it.
+   *
+   * Multipart, so it needs a transport that carries binary — the browser bridge
+   * refuses it.
+   */
+  async uploadDocument(file2, organizationId = "") {
+    const token = await this.getToken();
+    const form = new FormData();
+    form.append("__file__[]", new Blob([file2.bytes], { type: file2.mimeType }), file2.filename);
+    for (const [k, v] of Object.entries(UPLOAD_CONTEXT(organizationId).form)) form.append(k, v);
+    form.append("__RequestVerificationToken", token);
+    const res = await this.send(
+      {
+        method: "POST",
+        path: "DocumentUpload/UploadFile",
+        headers: { __RequestVerificationToken: token },
+        body: form
+      },
+      "DocumentUpload/UploadFile"
+    );
+    const doc = res.Success === true ? res.Data?.[0] : void 0;
+    if (doc?.DocumentId === void 0) {
+      throw new McpToolError(`MyAtriumHealth did not accept the upload of ${file2.filename}.`, {
+        hint: "Nothing was sent. Check the file type and size against the portal limits."
+      });
+    }
+    return {
+      documentId: doc.DocumentId,
+      filename: doc.FileDisplayName ?? file2.filename,
+      fileExtension: doc.FileExtension ?? ""
+    };
+  }
+  /** Discard a pending upload, with the context the composer sends. */
+  async deleteDocument(doc, organizationId = "") {
+    await this.postJson(
+      "DocumentUpload/DeleteFile",
+      {
+        DocumentId: doc.documentId,
+        ContextData: UPLOAD_CONTEXT(organizationId).context,
+        FileDisplayName: doc.filename,
+        FileExtension: doc.fileExtension.replace(/^\./, ""),
+        FileReference: "",
+        AllowPreview: false
+      },
+      "DocumentUpload/DeleteFile"
+    );
+  }
   /**
    * List Message Center conversations for a folder tag.
    *
@@ -62634,6 +62805,12 @@ var ServerTransport = class {
     this.auth.persistIfDirty();
     if (/<title>[^<]*Login Page/i.test(out.body)) {
       this.loggedIn = false;
+      if (init.replay === false) {
+        throw new NotAcceptedError(
+          "The MyAtriumHealth session expired before this was accepted, so nothing was sent.",
+          { hint: "Retry the call; it signs in again first. A verification code may be required." }
+        );
+      }
       await this.ensureSession();
       out = await send();
       this.auth.persistIfDirty();
@@ -62842,6 +63019,31 @@ var PatientContext = class {
       { hint: "Run mah_get_patient_context, then retry the read." }
     );
   }
+  /**
+   * Run a WRITE as the selected patient — once, never retried.
+   *
+   * {@link readAs} recovers from a mid-flight sign-in by reading again. A write
+   * cannot: repeating it could send twice, and the fresh session serves the
+   * account holder, so the repeat would go out as someone else. Instead the
+   * write gets `assertUnchanged`, to call immediately before its irreversible
+   * step; it throws if any sign-in has happened since the patient was
+   * confirmed, while nothing has been sent yet.
+   */
+  async writeAs(client2, write) {
+    const patient = await this.ensure(client2);
+    const generation = this.generation;
+    return write({
+      patient,
+      assertUnchanged: () => {
+        if (this.generation !== generation) {
+          throw new McpToolError(
+            `MyAtriumHealth re-authenticated after ${patient} was confirmed, so nothing was sent: the new session may be serving a different patient.`,
+            { hint: "Retry the call; it confirms the patient again before sending." }
+          );
+        }
+      }
+    });
+  }
 };
 
 // src/tools/patients.ts
@@ -62877,7 +63079,7 @@ function registerPatientTools(server, client2, patients2) {
     "mah_set_active_patient",
     {
       description: "Point every reading tool at one of the patients from mah_list_patients. The switch is confirmed with the portal before it is stored, and it survives restarts. Select the account holder to return to the default.",
-      annotations: toolAnnotations({ readOnly: false, idempotent: true }),
+      annotations: toolAnnotations({ readOnly: false, idempotent: true, destructive: false }),
       inputSchema: external_exports.object({
         patient_id: external_exports.string().min(1).describe("id from mah_list_patients")
       })
@@ -68246,6 +68448,14 @@ var FetchproxyTransport = class {
     return this.inner.status();
   }
   async fetch(init) {
+    if (init.body !== void 0 && typeof init.body !== "string") {
+      throw new McpToolError(
+        "File uploads cannot go through the browser bridge \u2014 it relays a request body as text, and a binary upload would arrive corrupted.",
+        {
+          hint: "Send without attachments, or set MAH_USERNAME and MAH_PASSWORD so this server signs in itself; uploads work on that path."
+        }
+      );
+    }
     const response = await this.inner.fetch({
       method: init.method,
       path: `/${APP_ROOT}/${init.path.replace(/^\/+/, "")}`,
@@ -68346,7 +68556,7 @@ function registerAccountTools(server, client2, patients2) {
   server.registerTool(
     "mah_list_messages",
     {
-      description: "List Message Center conversations for a folder. Folder tags come from mah_list_message_folders (1 = Conversations/inbox, 2 = Archive).",
+      description: "List Message Center conversations for a folder. Folder tags come from mah_list_message_folders (1 = Conversations/inbox, 2 = Archive). Each carries the conversationId that mah_reply_message takes.",
       annotations: toolAnnotations({ readOnly: true }),
       inputSchema: external_exports.object({
         folder: external_exports.number().int().default(1).describe("Folder tag, from mah_list_message_folders."),
@@ -68364,14 +68574,17 @@ function registerAccountTools(server, client2, patients2) {
             "conversations/GetConversationList",
             (r) => r.conversations?.map((c) => {
               const msgs = c["messages"] ?? [];
-              const first = msgs[0] ?? {};
+              const last = msgs.at(-1) ?? {};
               const participants = (c["userKeys"] ?? []).map((k) => r.users?.[k]?.name).filter((n) => typeof n === "string" && n !== "");
               return tidy({
+                // The id mah_reply_message takes.
+                conversationId: c["hthId"],
                 subject: c["subject"],
                 participants: participants.length > 0 ? participants : void 0,
                 preview: c["previewText"],
                 messageType: c["messageType"],
-                date: first["deliveryInstantISO"],
+                date: last["deliveryInstantISO"],
+                lastMessageId: last["wmgId"],
                 unread: msgs.some((m) => m["isUnread"] === true),
                 hasAttachments: c["hasAttachments"],
                 urgent: c["hasUrgentMsgs"],
@@ -68500,7 +68713,7 @@ function registerAuthTools(server, auth2) {
     "mah_sign_in",
     {
       description: "Sign in to MyAtriumHealth server-side. If the portal requires a verification code, this reports the available channels \u2014 ask the user which they want.",
-      annotations: toolAnnotations({ readOnly: false }),
+      annotations: toolAnnotations({ readOnly: false, destructive: true }),
       inputSchema: external_exports.object({})
     },
     async () => {
@@ -68524,7 +68737,7 @@ function registerAuthTools(server, auth2) {
     "mah_send_verification_code",
     {
       description: "Ask MyAtriumHealth to send a verification code to the account holder on the channel they chose. The code goes to them, not to this server.",
-      annotations: toolAnnotations({ readOnly: false }),
+      annotations: toolAnnotations({ readOnly: false, destructive: true }),
       inputSchema: external_exports.object({
         channel: external_exports.enum(["sms", "email", "totp"]).describe(
           "Channel the user chose, from the list mah_sign_in reported. 'totp' is an authenticator app \u2014 nothing is sent; read the code from the app."
@@ -68545,7 +68758,7 @@ function registerAuthTools(server, auth2) {
     "mah_verify_code",
     {
       description: "Submit the verification code the user received. On success the session is stored so restarts resume without signing in again, until it lapses.",
-      annotations: toolAnnotations({ readOnly: false }),
+      annotations: toolAnnotations({ readOnly: false, destructive: true }),
       inputSchema: external_exports.object({
         code: external_exports.string().min(4).describe("The code the USER received. Never guess or generate it."),
         rememberDevice: external_exports.boolean().default(true).describe(
@@ -69797,10 +70010,10 @@ function prepend(elem, prev) {
   prev.next = elem;
   elem.prev = prev;
 }
-function filter(test, node2, recurse = true, limit = Infinity) {
-  return find(test, Array.isArray(node2) ? node2 : [node2], recurse, limit);
+function filter(test, node2, recurse = true, limit2 = Infinity) {
+  return find(test, Array.isArray(node2) ? node2 : [node2], recurse, limit2);
 }
-function find(test, nodes, recurse, limit) {
+function find(test, nodes, recurse, limit2) {
   const result = [];
   const nodeStack = [Array.isArray(nodes) ? nodes : [nodes]];
   const indexStack = [0];
@@ -69814,7 +70027,7 @@ function find(test, nodes, recurse, limit) {
     const elem = nodeStack[0][indexStack[0]++];
     if (test(elem)) {
       result.push(elem);
-      if (--limit <= 0) return result;
+      if (--limit2 <= 0) return result;
     }
     if (recurse && hasChildren(elem) && elem.children.length > 0) {
       indexStack.unshift(0);
@@ -69892,22 +70105,22 @@ function testElement(options, node2) {
   const test = compileTest(options);
   return test ? test(node2) : true;
 }
-function getElements(options, nodes, recurse, limit = Infinity) {
+function getElements(options, nodes, recurse, limit2 = Infinity) {
   const test = compileTest(options);
-  return test ? filter(test, nodes, recurse, limit) : [];
+  return test ? filter(test, nodes, recurse, limit2) : [];
 }
 function getElementById(id, nodes, recurse = true) {
   if (!Array.isArray(nodes)) nodes = [nodes];
   return findOne$1(getAttribCheck("id", id), nodes, recurse);
 }
-function getElementsByTagName(tagName, nodes, recurse = true, limit = Infinity) {
-  return filter(Checks["tag_name"](tagName), nodes, recurse, limit);
+function getElementsByTagName(tagName, nodes, recurse = true, limit2 = Infinity) {
+  return filter(Checks["tag_name"](tagName), nodes, recurse, limit2);
 }
-function getElementsByClassName(className, nodes, recurse = true, limit = Infinity) {
-  return filter(getAttribCheck("class", className), nodes, recurse, limit);
+function getElementsByClassName(className, nodes, recurse = true, limit2 = Infinity) {
+  return filter(getAttribCheck("class", className), nodes, recurse, limit2);
 }
-function getElementsByTagType(type, nodes, recurse = true, limit = Infinity) {
-  return filter(Checks["tag_type"](type), nodes, recurse, limit);
+function getElementsByTagType(type, nodes, recurse = true, limit2 = Infinity) {
+  return filter(Checks["tag_type"](type), nodes, recurse, limit2);
 }
 function removeSubsets$1(nodes) {
   let idx = nodes.length;
@@ -72794,6 +73007,262 @@ function registerBillingTools(server, client2, patients2) {
   );
 }
 
+// src/reply.ts
+var MIME = {
+  BMP: "image/bmp",
+  DOC: "application/msword",
+  DOCX: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  JPEG: "image/jpeg",
+  JPG: "image/jpeg",
+  PDF: "application/pdf",
+  PNG: "image/png",
+  TIF: "image/tiff",
+  TIFF: "image/tiff",
+  "3GP": "video/3gpp",
+  "3GPP": "video/3gpp",
+  AVI: "video/x-msvideo",
+  MOV: "video/quicktime",
+  MP4: "video/mp4",
+  MPEG: "video/mpeg",
+  MPG: "video/mpeg",
+  WMV: "video/x-ms-wmv"
+};
+function toParagraphs(body) {
+  return body.split(/\r\n|[\r\n]/);
+}
+function paragraphsOf(html) {
+  const root = parse3(html);
+  for (const s of root.querySelectorAll("style")) s.remove();
+  return root.querySelectorAll("[data-paragraph]").map((p) => p.text);
+}
+var sameText = (a, b) => {
+  const norm = (x) => x.join("\n").replace(/\s+/g, " ").trim();
+  return norm(a) === norm(b);
+};
+function limit(value, what) {
+  if (typeof value === "number") return value;
+  throw new McpToolError(`MyAtriumHealth did not report its ${what}, so the reply cannot be checked against it.`, {
+    hint: "Nothing was sent. GetComposeSettings may have changed shape; see docs/MYATRIUMHEALTH-API.md."
+  });
+}
+function prepareAttachments(files, settings) {
+  if (files.length === 0) return [];
+  const a = settings.attachmentSettings ?? {};
+  if (a.canAttach !== true) {
+    throw new McpToolError("MyAtriumHealth does not allow attachments on this reply.");
+  }
+  const max = limit(a.maxNumberOfAttachments, "attachment count limit");
+  if (files.length > max) {
+    throw new McpToolError(`MyAtriumHealth allows at most ${max} attachments per message.`);
+  }
+  return files.map((f) => {
+    const ext = /\.([^.]+)$/.exec(f.filename)?.[1]?.toUpperCase() ?? "";
+    const kind = a.docAndImageSettings?.allowedFileExtensions?.includes(ext) ? a.docAndImageSettings : a.videoSettings?.allowedFileExtensions?.includes(ext) ? a.videoSettings : void 0;
+    if (kind === void 0 || MIME[ext] === void 0) {
+      const allowed = [
+        ...a.docAndImageSettings?.allowedFileExtensions ?? [],
+        ...a.videoSettings?.allowedFileExtensions ?? []
+      ];
+      throw new McpToolError(`MyAtriumHealth does not accept ${ext || "extension-less"} files (${f.filename}).`, {
+        hint: `Accepted: ${allowed.join(", ")}.`
+      });
+    }
+    if (!/^[A-Za-z0-9+/\s]*={0,2}\s*$/.test(f.contentBase64)) {
+      throw new McpToolError(`${f.filename}: contentBase64 is not valid base64.`);
+    }
+    const bytes = new Uint8Array(Buffer.from(f.contentBase64, "base64"));
+    if (bytes.length === 0) throw new McpToolError(`${f.filename} is empty.`);
+    const maxKb = limit(kind.maxFileSize, "file size limit");
+    if (bytes.length > maxKb * 1024) {
+      throw new McpToolError(
+        `${f.filename} is too large: ${bytes.length} bytes, over the portal limit of ${maxKb} KB.`
+      );
+    }
+    return { filename: f.filename, mimeType: MIME[ext], bytes };
+  });
+}
+async function prepare(client2, input2) {
+  const details = await client2.conversationDetails(input2.conversationId);
+  if (details?.hthId !== input2.conversationId) {
+    throw new McpToolError(`No conversation ${input2.conversationId} for the current patient.`, {
+      hint: "conversationId is the conversationId from mah_list_messages. Threads belong to one patient \u2014 check mah_get_patient_context."
+    });
+  }
+  if (details.replyFlags?.canReply !== true) {
+    throw new McpToolError(
+      `This conversation cannot be replied to (portal reason code ${details.replyFlags?.cannotReplyReason ?? "unknown"}).`,
+      { hint: "Start a new message in the portal instead." }
+    );
+  }
+  const selves = Object.values(details.viewers ?? {}).filter((v) => v.isSelf === true && v.wprId);
+  if (selves.length !== 1) {
+    throw new McpToolError(
+      `Expected exactly one viewer marked as you on this conversation, found ${selves.length}.`,
+      { hint: "Reply in the portal instead; this case has not been observed." }
+    );
+  }
+  const organizationId = details.organizationId ?? "";
+  const settings = await client2.api("conversations/GetComposeSettings", {
+    organizationId
+  });
+  if (input2.body.trim() === "") throw new McpToolError("The reply body is empty.");
+  const maxLen = limit(settings.maxMessageLength, "message length limit");
+  if (input2.body.length > maxLen) {
+    throw new McpToolError(
+      `The reply is ${input2.body.length} characters; MyAtriumHealth allows ${maxLen}.`,
+      { hint: "Shorten it, or split it across more than one reply." }
+    );
+  }
+  const files = prepareAttachments(input2.attachments ?? [], settings);
+  const recipients = (details.userKeys ?? []).map((k) => details.users?.[k]?.name).filter((n) => typeof n === "string" && n !== "");
+  return {
+    details,
+    organizationId,
+    selfWprId: selves[0].wprId,
+    paragraphs: toParagraphs(input2.body),
+    files,
+    recipients
+  };
+}
+var UNCERTAIN_HINT = "Check the thread with mah_list_messages before retrying \u2014 sending again may post it twice.";
+async function replyToConversation(client2, patients2, input2, opts) {
+  return patients2.writeAs(client2, async ({ patient, assertUnchanged }) => {
+    const p = await prepare(client2, input2);
+    const summary = {
+      patient,
+      conversationId: input2.conversationId,
+      subject: p.details.subject,
+      recipients: p.recipients,
+      body: input2.body,
+      attachments: p.files.map((f) => ({ filename: f.filename, bytes: f.bytes.length }))
+    };
+    const readOnlyReason = "MAH_READ_ONLY is set on this server, so replies are refused. Unset it (or set it to false) and restart to allow sending.";
+    const bridgeReason = "Attachments need the credential transport: this server relays through the browser bridge, which cannot carry a file upload.";
+    const blocked = opts.readOnly ? readOnlyReason : p.files.length > 0 && !opts.attachmentsSupported ? bridgeReason : void 0;
+    if (input2.confirm !== true) {
+      return {
+        sent: false,
+        ...summary,
+        ...blocked !== void 0 ? { sendBlocked: blocked } : {},
+        nextStep: "Nothing was sent. Show this to the user; if they approve, call mah_reply_message again with the same arguments and confirm: true. Sending is irreversible."
+      };
+    }
+    if (opts.readOnly) throw new McpToolError(readOnlyReason);
+    if (p.files.length > 0 && !opts.attachmentsSupported) {
+      throw new McpToolError(bridgeReason, {
+        hint: "Send without attachments, or set MAH_USERNAME and MAH_PASSWORD so the server signs in itself."
+      });
+    }
+    assertUnchanged();
+    const composeId = await client2.api("conversations/GetComposeId", {});
+    const uploaded = [];
+    const cleanUp = async () => {
+      for (const d of uploaded) await client2.deleteDocument(d, p.organizationId).catch(() => {
+      });
+      await client2.api("conversations/RemoveComposeId", { composeId }).catch(() => {
+      });
+    };
+    const payload = () => ({
+      conversationId: input2.conversationId,
+      organizationId: p.organizationId,
+      viewers: [{ wprId: p.selfWprId }],
+      messageBody: p.paragraphs,
+      documentIds: uploaded.map((d) => d.documentId),
+      includeOtherViewers: false,
+      composeId
+    });
+    try {
+      assertUnchanged();
+      for (const f of p.files) uploaded.push(await client2.uploadDocument(f, p.organizationId));
+      assertUnchanged();
+      const draft = await client2.api(
+        "conversations/SaveReplyDraft",
+        payload()
+      );
+      if (draft?.conversationId !== input2.conversationId || draft.error !== 0) {
+        throw new McpToolError("MyAtriumHealth refused the reply draft, so nothing was sent.", {
+          hint: `The portal answered ${JSON.stringify(draft).slice(0, 120)}.`
+        });
+      }
+      assertUnchanged();
+    } catch (e) {
+      await cleanUp();
+      throw e;
+    }
+    let answer;
+    try {
+      answer = await client2.api("conversations/SendReply", payload(), { replay: false });
+    } catch (e) {
+      if (e instanceof NotAcceptedError) {
+        await cleanUp();
+        throw e;
+      }
+      throw new McpToolError(
+        `The reply may have been sent \u2014 the portal's answer could not be read (${e.message}).`,
+        { hint: UNCERTAIN_HINT }
+      );
+    }
+    const echoed = answer === input2.conversationId;
+    if (echoed) await client2.api("conversations/RemoveComposeId", { composeId }).catch(() => {
+    });
+    const seen = new Set((p.details.messages ?? []).map((m) => m.wmgId));
+    let message;
+    try {
+      const after = await client2.conversationDetails(input2.conversationId, p.organizationId);
+      message = (after.messages ?? []).filter(
+        (m) => !seen.has(m.wmgId) && m.author?.wprKey === p.selfWprId && sameText(paragraphsOf(m.body ?? ""), p.paragraphs)
+      ).at(-1);
+    } catch {
+      message = void 0;
+    }
+    if (!echoed && message === void 0) {
+      throw new McpToolError("MyAtriumHealth did not confirm the reply; it may have been sent.", {
+        hint: UNCERTAIN_HINT
+      });
+    }
+    if (!echoed) await client2.api("conversations/RemoveComposeId", { composeId }).catch(() => {
+    });
+    return {
+      sent: true,
+      verified: message !== void 0,
+      ...summary,
+      ...message !== void 0 ? {
+        message: {
+          wmgId: message.wmgId,
+          deliveryInstantISO: message.deliveryInstantISO,
+          isUnread: message.isUnread,
+          attachments: message.attachments ?? []
+        }
+      } : {
+        note: "MyAtriumHealth confirmed the send, but the new message could not be read back from the thread. Check it with mah_list_messages; do not resend."
+      }
+    };
+  });
+}
+
+// src/tools/messages.ts
+function registerMessageTools(server, client2, patients2, opts) {
+  server.registerTool(
+    "mah_reply_message",
+    {
+      description: "Reply to a Message Center conversation as the active patient. The provider sees the reply; sending is IRREVERSIBLE. Without confirm: true this only previews (thread, recipients, body) and sends nothing. Plain-text body, max 500 characters; each line becomes a paragraph. Optional attachments (PDF, image, Word or video, at most 3) need the server to sign in itself; the browser bridge cannot upload. Refused when MAH_READ_ONLY is set.",
+      annotations: toolAnnotations({ readOnly: false, destructive: true }),
+      inputSchema: external_exports.object({
+        conversationId: external_exports.string().min(1).describe("The conversationId of the thread, from mah_list_messages."),
+        body: external_exports.string().min(1).describe("Reply text. Line breaks start new paragraphs."),
+        attachments: external_exports.array(
+          external_exports.object({
+            filename: external_exports.string().min(1).describe("File name with extension, e.g. scan.pdf."),
+            contentBase64: external_exports.string().min(1).describe("The file content, base64-encoded.")
+          })
+        ).optional().describe("Files to attach. Uploaded only when confirm is true."),
+        confirm: external_exports.boolean().default(false).describe("Must be true to send. Otherwise the tool returns a preview and sends nothing.")
+      })
+    },
+    async (args) => minifiedResult(await replyToConversation(client2, patients2, args, opts))
+  );
+}
+
 // src/tools/healthcheck.ts
 var HOST = "my.atriumhealth.org";
 function registerMahHealthcheckTool(server, client2, arms) {
@@ -73170,7 +73639,7 @@ function registerVisitTools(server, client2, patients2) {
 }
 
 // src/version.ts
-var VERSION = "1.1.0";
+var VERSION = "1.2.0";
 
 // src/index.ts
 var dotenvCandidates = [
@@ -73197,6 +73666,7 @@ if (!bridgeless && (username !== void 0 || password !== void 0)) {
     "[myatriumhealth-mcp] No MAH_USERNAME / MAH_PASSWORD found, so requests will relay through your signed-in my.atriumhealth.org tab. Set both (env, or a .env beside the server / MAH_DOTENV) for bridge-less sign-in, which needs no tab."
   );
 }
+var readOnly = parseBoolEnv("MAH_READ_ONLY", { default: false });
 var port = readPortEnv("MAH_WS_PORT", DEFAULT_PORT);
 var transport;
 var auth;
@@ -73239,6 +73709,8 @@ await runMcp({
     (server) => registerVisitTools(server, client, patients),
     (server) => registerAccountTools(server, client, patients),
     (server) => registerBillingTools(server, client, patients),
+    // Uploads need a transport that carries binary — only the credential one.
+    (server) => registerMessageTools(server, client, patients, { readOnly, attachmentsSupported: bridgeless }),
     (server) => registerPatientTools(server, client, patients),
     // Unconditional, in both modes. What varies is what they DO, not whether
     // they exist — see registerAuthTools for why a tool surface that follows

package/mint.yaml

@@ -31,6 +31,11 @@ env:
       Override the session-state file path. Defaults to device.json under the
       data directory, which is where it belongs when hosted — and with
       per-user children each caller gets their own.
+  - name: MAH_READ_ONLY
+    required: false
+    help: >-
+      true refuses mah_reply_message sends; previews still work. Default false —
+      every send already requires confirm: true.
   - name: MAH_WS_PORT
     required: false
     help: >-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/myatriumhealth-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP server for MyAtriumHealth (Atrium Health's Epic MyChart patient portal) via the fetchproxy browser bridge.",
   "type": "module",
   "bin": {
@@ -42,7 +42,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^1.0.0",
+    "@chrischall/mcp-utils": "^2.2.0",
     "@fetchproxy/server": "^3.0.1",
     "@modelcontextprotocol/server": "^2.0.0",
     "dotenv": "^17.4.2",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/myatriumhealth-mcp",
     "source": "github"
   },
-  "version": "1.1.0",
+  "version": "1.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/myatriumhealth-mcp",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "transport": {
         "type": "stdio"
       },
@@ -21,6 +21,12 @@
           "description": "Override the fetchproxy WebSocket port (default 37149).",
           "isRequired": false,
           "format": "string"
+        },
+        {
+          "name": "MAH_READ_ONLY",
+          "description": "true refuses mah_reply_message sends (previews still work). Default false.",
+          "isRequired": false,
+          "format": "boolean"
         }
       ]
     }