@chrischall/therapyportal-mcp 0.0.0-stage → 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "therapyportal-mcp",
+  "owner": {
+    "name": "Chris Hall",
+    "email": "chris.c.hall@gmail.com"
+  },
+  "metadata": {
+    "description": "MCP server for TherapyNotes client portals (TherapyPortal) — read appointments, paperwork, forms, balances, receipts and secure messages, and download completed documents and receipts. Signs in server-side with the portal password, or relays requests through the user's signed-in browser tab via the ContextMint Bridge extension.",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "therapyportal-mcp",
+      "displayName": "TherapyPortal",
+      "source": "./",
+      "description": "Read a TherapyNotes client portal (TherapyPortal) — upcoming appointments, paperwork, practice forms, balances, receipts and secure messages, plus document and receipt downloads. Signs in server-side or relays through the user's signed-in browser tab.",
+      "version": "0.1.0",
+      "author": {
+        "name": "Chris Hall"
+      },
+      "homepage": "https://github.com/chrischall/therapyportal-mcp",
+      "repository": "https://github.com/chrischall/therapyportal-mcp",
+      "license": "MIT",
+      "keywords": [
+        "therapyportal",
+        "therapynotes",
+        "patient-portal",
+        "behavioral-health",
+        "therapy",
+        "fetchproxy"
+      ],
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "therapyportal-mcp",
+  "displayName": "TherapyPortal",
+  "version": "0.1.0",
+  "description": "Read a TherapyNotes client portal (TherapyPortal) — upcoming appointments, paperwork, practice forms, balances, receipts and secure messages, plus document and receipt downloads.",
+  "author": {
+    "name": "Chris Hall",
+    "email": "chris.c.hall@gmail.com"
+  },
+  "homepage": "https://github.com/chrischall/therapyportal-mcp",
+  "repository": "https://github.com/chrischall/therapyportal-mcp",
+  "license": "MIT",
+  "keywords": [
+    "therapyportal",
+    "therapynotes",
+    "patient-portal",
+    "behavioral-health",
+    "therapy",
+    "mcp"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "therapyportal": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@chrischall/therapyportal-mcp"
+      ],
+      "env": {
+        "THERAPYPORTAL_WS_PORT": "37149"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Hall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# therapyportal-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for **TherapyPortal**, the client portal of TherapyNotes
+(`https://www.therapyportal.com/p/<practice>/`). It reads upcoming therapy
+appointments, paperwork the practice sent, the practice's standing forms,
+balances due, payment receipts and secure messages, and downloads completed
+documents and receipts as PDFs.
+
+> This project was developed and is maintained by AI. Use at your own discretion.
+> It reads mental-health records, and only ever from the signed-in user's own account.
+
+## Read-only
+
+Every tool is a read. It sends no message, signs no form, uploads nothing and
+makes no payment. A download is logged by the practice, the same way the
+portal logs the click.
+
+On the privacy side, `therapyportal_list_clients` returns names and date of
+birth only. The portal's client record also carries the address, phones,
+email, an SSN field, billing notes and free-text comments, and none of those
+are ever passed through, on any `view`.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `therapyportal_list_clients` | the clients linked to this login (for a parent, each child), with the `patientId` other tools take |
+| `therapyportal_list_appointments` | upcoming appointments: time, clinician, telehealth or location, which client; pending requests; practice phone. The portal shows **no past visits** |
+| `therapyportal_list_documents` | paperwork requests (`pending` / `completed` / `all`) and their documents, with `portalDocumentId` |
+| `therapyportal_list_forms` | the practice's always-available forms (sign or upload as needed) |
+| `therapyportal_get_document_counts` | per client, documents waiting to be completed or approved |
+| `therapyportal_list_balances` | the balance due per client, and whether autopay is on |
+| `therapyportal_list_receipts` | payments, with the dates of service each covered, and `paymentId` |
+| `therapyportal_list_message_threads` | one client's secure-message conversations (does not mark read) |
+| `therapyportal_get_thread_messages` | the messages in one conversation (does not mark read) |
+| `therapyportal_download_document` | a completed form (rendered to PDF) or a file the practice uploaded |
+| `therapyportal_download_receipt` | a payment receipt PDF |
+| `therapyportal_healthcheck` | connectivity, from whichever transport is live |
+
+Read tools take `view`. The default is `compact` (projected to the useful
+fields); `full` and `raw` return more. Text the practice wrote (document
+titles, instructions, messages) comes back inside an untrusted-content
+envelope.
+
+**Message tools are not verified against real messages.** The account this was
+built against had none, so these two return the portal's payload exactly as
+sent rather than a projection.
+
+## Transports
+
+| | Server (default when credentials are set) | Browser bridge |
+|---|---|---|
+| How | signs in itself with your email and password; holds a cookie jar in memory | relays every request through your signed-in Chrome tab via the ContextMint Bridge extension |
+| Needs | `THERAPYPORTAL_EMAIL`, `THERAPYPORTAL_PASSWORD` (and `THERAPYPORTAL_DOB` if the portal asks) | the extension, and a signed-in portal tab |
+| Hostable (claude.ai, phone) | yes | only as a bridged registration |
+| Downloads | written to `THERAPYPORTAL_OUTPUT_DIR`, or inline | saved by the browser to its download folder |
+
+The two can run side by side. A server-side sign-in does **not** end your
+browser's portal session (checked live), and the portal signs out an idle
+browser tab on its own after a while; that is the usual reason the bridge
+reports "not signed in".
+
+A rejected password or date of birth is **never retried**. The date-of-birth
+check locks after a few wrong dates, so the server tries it once.
+
+## Configuration
+
+| Variable | |
+|---|---|
+| `THERAPYPORTAL_PRACTICE` | **required.** The code after `/p/` in your portal URL (a full URL also works) |
+| `THERAPYPORTAL_EMAIL` | the email you sign in with |
+| `THERAPYPORTAL_PASSWORD` | your portal password |
+| `THERAPYPORTAL_DOB` | only if the portal asks for a date of birth at sign-in: `MM/DD/YYYY` (`M/D/YYYY` and `YYYY-MM-DD` are accepted) |
+| `THERAPYPORTAL_TRANSPORT` | `server` or `fetchproxy`. Default: `server` when email and password are set |
+| `THERAPYPORTAL_WS_PORT` | fetchproxy concentrator port, default `37149` (shared by the whole fleet) |
+| `THERAPYPORTAL_OUTPUT_DIR` | where downloads are written (path-delimiter list; `~` expands). Default `~/Downloads` and `~/Documents`; a per-call `dest` must be inside one |
+| `THERAPYPORTAL_INLINE_DOWNLOADS` | `true` returns downloads inline (base64), for a hosted runner |
+| `FETCHPROXY_WS_HOST`, `FETCHPROXY_IDENTITY_DIR` | fetchproxy bind address and identity directory (advanced) |
+
+Copy `.env.example` to `.env` for a local install.
+
+```json
+{
+  "mcpServers": {
+    "therapyportal": {
+      "command": "npx",
+      "args": ["-y", "@chrischall/therapyportal-mcp"],
+      "env": { "THERAPYPORTAL_PRACTICE": "<code>" }
+    }
+  }
+}
+```
+
+## Without the server
+
+`skills/therapyportal-fpx` does the same reads from a shell with the `fpx` CLI,
+through the signed-in tab. See its `SKILL.md`.
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test                 # typecheck + vitest, all mocked
+npm run test:coverage    # 100% threshold
+```
+
+The wire protocol (tokens, sign-in, download jobs) is in
+[`docs/THERAPYPORTAL-API.md`](docs/THERAPYPORTAL-API.md).