@chrischall/myatriumhealth-mcp 0.2.0 → 0.3.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": "0.2.0"
+    "version": "0.3.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": "0.2.0",
+      "version": "0.3.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/README.md

@@ -26,10 +26,44 @@ destinations; you pick one, the portal texts or emails **you**, and `mah_verify_
 resumes the session in place. A pending challenge is remembered, so further tool calls
 report it rather than re-submitting your password each time.
 
+**Where credentials are read from.** A real `MAH_USERNAME` / `MAH_PASSWORD` in the
+environment always wins. Failing that the server reads the first `.env` it finds, in
+this order: `MAH_DOTENV`, then `~/.myatriumhealth-mcp/.env`, then `./.env`.
+
+The middle one exists because MCP clients launch the server from whatever directory
+they happen to be in, so a `.env` sitting in a checkout is invisible to it — and the
+failure is quiet: with no credentials the server falls back to the browser bridge,
+binds a port and waits for a signed-in tab. If you meant to run bridge-less and see the
+bridge start, that is what happened; the startup line now says so.
+
 **How the session persists.** After one verification the cookie jar is stored (0600,
 bound to the account) and reused, so restarts resume the existing session rather than
 signing in again — no browser and no further codes until the session lapses.
 
+**How long that lasts, measured rather than assumed.** Every one of the ten cookies
+MyChart sets is a *session* cookie — none carries an `expires` or `max-age` — so the
+lifetime is the server's alone and cannot be read from the jar. A jar left **idle for
+219 minutes** no longer authenticated: the next call fell through to a fresh sign-in
+and was challenged for a code immediately.
+
+What that does and does not establish: it bounds an **idle** session, and says nothing
+about an active one. The measurement cannot tell an idle timeout from an absolute one,
+and portals of this kind usually expire on inactivity — so a session in steady use may
+outlive 3.6h comfortably, while one left alone will not. Plan re-verification around
+**gaps in use**, not around wall-clock age.
+
+**Why the jar is written back mid-session.** Every response's `Set-Cookie` is absorbed,
+and the jar is re-persisted whenever a value actually changed (`transport-server.ts`
+after each request; a no-op write when nothing rotated). That is not bookkeeping: if
+the portal refreshes its ticket as a session is used, the refreshed one only survives a
+process restart by reaching disk. On a scale-to-zero host — where the child exits
+between tool calls — that write-back is the whole reason an extended session is still
+there on the next call, rather than the copy frozen at sign-in.
+
+Two things none of this changes: a lapse still costs one code rather than a reconnect,
+and detection alone sends nothing — only `mah_sign_in` asks the portal to send
+anything.
+
 > **What does NOT work, measured rather than assumed:** the `RememberDeviceId` this
 > portal returns is *not* a device-tracking id it will accept back. Sending it neither
 > skips verification nor is harmless — it breaks the challenge, leaving the
@@ -80,7 +114,11 @@ call prints a pair code — approve it once in the Transporter popup.
 
 ## Tools
 
-All read-only — this surface exposes no writes.
+All read-only except `mah_set_active_patient`, which changes only which patient this
+connector reads — it writes nothing to any chart.
+
+Every reading tool returns `{ patient, data }`, so the chart a response belongs to is
+stated rather than inferred.
 
 | Tool | What it returns |
 |---|---|
@@ -104,11 +142,26 @@ All read-only — this surface exposes no writes.
 | `mah_sign_in` | Sign in server-side; reports verification channels if a code is needed *(bridge-less only)* |
 | `mah_send_verification_code` | Ask the portal to send a code to the account holder *(bridge-less only)* |
 | `mah_verify_code` | Submit the code the user received *(bridge-less only)* |
-
-Listing tools take `compact` (default `false`). The raw envelopes are large — test
-results ~33 KB, medications ~30 KB — so pass `compact: true` when browsing. If the
-portal's shape drifts, the projection warns to stderr and returns the raw response
-rather than an empty list.
+| `mah_list_patients` | The patients this login can open — the account holder and any proxy subjects |
+| `mah_get_patient_context` | Which patient the readers are serving, confirmed with the portal |
+| `mah_set_active_patient` | Point every reader at one of those patients; survives restarts |
+
+Every reading tool takes `view`: `compact` (the default) or `full`. The raw envelopes
+are large — test results ~33 KB, medications ~30 KB — so `compact` is what you want for
+browsing, and `full` returns MyAtriumHealth's payload untouched.
+
+`compact` always strips image and avatar URLs, which is subtractive and cannot drop a
+field nobody knew about. Ten readers additionally reduce each record to its clinically
+meaningful fields, because their real payloads were captured and a projection derived
+from them: `mah_list_allergies`, `mah_list_health_issues`, `mah_list_immunizations`,
+`mah_list_medications`, `mah_list_care_team`, `mah_list_goals`, `mah_list_test_results`,
+`mah_list_past_visits`, `mah_list_insurance` and `mah_list_messages`.
+
+Every other reader gets the URL strip only. That field list is applied where one was
+actually established and nowhere else — the list above is generated from
+`PROJECTED_ENDPOINTS` and checked against the `project()` call sites by a test, so it
+cannot quietly drift out of step with the code. If the portal's shape drifts, the
+projection warns to stderr and returns the raw response rather than an empty list.
 
 ## Sessions expire, and they do it quietly