therapyportal-mcp

therapyportal-mcp

TherapyNotes のクライアントポータルである TherapyPortal （https://www.therapyportal.com/p/<practice>/）向けの MCP サーバーです。今後のセラピーの予約、医療機関から送られた書類、医療機関の常設フォーム、未払い残高、支払いの領収書、安全なメッセージを読み取り、記入済みの書類や領収書を PDF としてダウンロードします。また、それぞれに確認ゲートを設けたうえで、安全なメッセージの送信や、書類の提出依頼への回答としてのファイルのアップロードも行えます。

このプロジェクトは AI によって開発され、保守されています。ご自身の判断でご利用ください。 メンタルヘルスの記録を読み取りますが、読み取るのはサインイン中のユーザー自身のアカウントからのみです。

読み取り専用ではありません

ほとんどのツールは読み取り専用です。3 つは書き込みを行い、いずれも医療機関に送信されるため、このサーバーから取り消すことはできません。

ツール	送信する内容	事前に確認するツール
therapyportal_send_message	クライアント 1 人に対する、新しいトピックの安全なメッセージの会話	therapyportal_list_message_topics
therapyportal_reply_message	既存の会話への返信（mark_thread_read を指定しない限り、既読状態は変更されません）	therapyportal_list_message_threads
therapyportal_upload_document	保留中の書類提出依頼、または常時利用可能なフォームでアップロードが必要な場合に提出するローカルファイル	therapyportal_list_documents、therapyportal_list_forms

3 つすべてに destructive の注釈が付いており、確認ゲートが設けられています（後述）。サーバーがフォームに署名したり、記入したり、支払いを行ったりすることはありません。署名が必要なもの（PatientSignatureRequired）は拒否され、ポータルへの案内が表示されます。ダウンロードは、ポータルでクリックした場合と同様に、医療機関のログに記録されます。

プライバシーについては、therapyportal_list_clients が返すのは氏名と生年月日のみです。ポータルのクライアント記録には住所、電話番号、メールアドレス、SSN 欄、請求に関するメモ、自由記述のコメントも含まれますが、これらがいずれかの view を通じて渡されることはありません。

ツール

ツール	返される内容
therapyportal_list_clients	このログインに紐づくクライアント（保護者の場合は各子ども）と、他のツールが使用する patientId
therapyportal_list_appointments	今後の予約：日時、担当者、遠隔診療か所在地か、対象のクライアント、保留中のリクエスト、診療所の電話番号。ポータルには過去の受診履歴は表示されません
therapyportal_list_documents	書類の依頼（pending／completed／all）とその書類。portalDocumentId` と、それぞれにアップロードまたは署名が必要かどうか
therapyportal_list_forms	診療所で常時利用できるフォーム（必要に応じて署名またはアップロード）と libraryDocumentId
therapyportal_get_document_counts	クライアントごとの、記入または承認待ちの書類数
therapyportal_list_balances	クライアントごとの未払い残高と、自動支払いが有効かどうか
therapyportal_list_receipts	支払いと、それぞれが対象とする診療日、paymentId
therapyportal_list_message_threads	1 人のクライアントのセキュアメッセージの会話（既読にはしません）
therapyportal_get_thread_messages	1 つの会話内のメッセージ（既読にはしません）
therapyportal_download_document	記入済みのフォーム（PDF に変換）または診療所がアップロードしたファイル
therapyportal_download_receipt	支払い領収書の PDF
therapyportal_list_message_topics	クライアントがメッセージを送れるトピック（topicId と、それぞれが臨床、請求、管理のどのスタッフに届くか）、メッセージ機能が有効かどうか、クライアントに担当者が割り当てられているかどうか
therapyportal_send_message	書き込み。 新しい会話を開始します（確認が必要）
therapyportal_reply_message	書き込み。 会話に返信します（確認が必要）
therapyportal_upload_document	書き込み。 アップロードが必要な書類として、PDF、JPG、JPEG、PNG、HEIC、DOCX をアップロードします（最大 25 MB、確認が必要）
therapyportal_healthcheck	現在使用可能なトランスポートからの接続状態

読み取りツールでは view を指定します。デフォルトは compact（有用なフィールドに絞り込み）です。full と raw では、より多くの情報が返されます。診療所が記載したテキスト（書類のタイトル、説明、メッセージ）は、信頼できないコンテンツを示すエンベロープ内に返されます。

メッセージツールは、実際のメッセージを使って検証されていません。 このツールの作成時に使用したアカウントにはメッセージがなかったため、スレッドとメッセージの読み取りでは、ポータルのペイロードが投影されず、そのまま返されます。

書き込み

3 つの書き込み機能は、ポータル独自の JavaScript （SecureMessagingDataService、CreateMessageViewV2、ThreadViewV2、 DocumentsDataService、ドキュメントビューコントローラー、xhrfileuploader） から導き出したもので、通信上では未検証です。いずれも医療機関に到達するため、 自動実行でメッセージを送信したり、ファイルをアップロードしたりすることはありません。 その後、オーナーの監督下で行う実環境テストで確認します。事前に行う検索 （メッセージ設定、トピック、担当臨床家の確認、ドキュメントとフォームの一覧）は、 読み取り専用で実環境にて検証済みです。

プレビューを表示する前に、各書き込み機能は実環境での読み取り結果を照合します。 クライアントがご自身のクライアントの 1 人であること （therapyportal_list_clients）、医療機関でセキュアメッセージが有効になっていること、 そのクライアントにトピックが存在すること、さらにアップロードの場合は、ドキュメント またはフォームが存在し、未完了で、アップロードを求めており、署名が不要であることを 確認します。

• メッセージ。 1～5000 文字のプレーンテキストを、ポータルのエディターと同じ形式 （1 行につき 1 つの HTML 段落）で送信します。未返信のメッセージが複数あると、 医療機関が新しいメッセージを拒否する場合があります。その場合は、拒否されたことが 通知されます。アーカイブ済みの会話には返信できません。
• アップロード。 ファイルは THERAPYPORTAL_UPLOAD_DIR（既定値は ~/Downloads、~/Documents、~/Desktop。ホスト環境では $MCP_DATA_DIR/uploads） の中にあり、通常のファイル（シンボリックリンクではない）で、内容が拡張子と一致して いる必要があります。旧形式の .doc はアップロード前に形式を確認できないため拒否 されます。PDF または .docx として保存してください。ファイルは 100 KB ずつに 分割してステージングされ、ポータルによる検証後にのみ送信されます。医療機関に届くのは 送信のみです。
• 送信は 1 回のみ。 書き込みは正確に 1 回だけ送信されます。どちらのトランスポートでも、 再サインイン後に再送されることはありません。ポータルが 5xx を返した送信、または接続が 切断された送信は、エラーではなく status: "unknown" として報告されます。そのため、 モデルは二重送信を避けるため、再試行する前に該当する一覧を確認します。

確認ゲート

すべての書き込みは、defineWrite / registerWrite を通じた @chrischall/mcp-utils の confirmWrite によって制御されます。最初の呼び出しでは何も 送信されず、プレビューと confirmToken が返されます。プレビューを確認して承認した 後、そのトークンを含めて 2 回目の呼び出しを行った場合にのみ送信されます。正確な リクエスト（アップロードの場合はファイル名、種類、サイズ、SHA-256）と表示された プレビューはトークンに紐付けられます。そのため、プレビュー後に引数、ファイル、または ポータルの状態が変わると、DRAFT_CHANGED として拒否されます。送信ごとに変化する値 （アップロードの GUID、ドキュメントの日付）は送信時に生成され、紐付けの対象には なりません。医療機関が入力したプレビューまたは結果内のテキスト（トピック名、ドキュメント タイトル、返された会話）は、信頼できないコンテンツとしてラップされます。 MCP_CONFIRM_MODE / MCP_CONFIRM_ELICITATION でゲートを調整できます （「Configuration」を参照）。

トランスポート

	サーバー（認証情報が設定されている場合の既定値）	ブラウザーブリッジ
方式	メールアドレスとパスワードで自らサインインし、Cookie jar をメモリ内に保持します	サインイン済みの Chrome タブを介して、ContextMint Bridge 拡張機能経由ですべてのリクエストを中継します
必要なもの	THERAPYPORTAL_EMAIL、THERAPYPORTAL_PASSWORD（ポータルから求められる場合は THERAPYPORTAL_DOB も必要です）	拡張機能と、サインイン済みのポータルタブ
ホスト可能（claude.ai、スマートフォン）	はい	ブリッジ経由で登録した場合のみ
ダウンロード	THERAPYPORTAL_OUTPUT_DIR に保存するか、インラインで返します	ブラウザーがダウンロードフォルダーに保存します

2 つは並行して実行できます。サーバー側でサインインしても、ブラウザーのポータルセッションは 終了しません（実環境で確認済み）。また、ポータルはしばらく操作のないブラウザータブから 自動的にサインアウトします。ブリッジが「not signed in」と報告するのは、通常これが原因です。

拒否されたパスワードや生年月日が再試行されることはありません。生年月日の確認は、 誤った日付を何度か入力するとロックされるため、サーバーは 1 回だけ試行します。

設定

変数
THERAPYPORTAL_PRACTICE	必須。 ポータルの URL 内にある /p/ の後ろのコードです（URL 全体も使用できます）
THERAPYPORTAL_EMAIL	サインインに使用するメールアドレスです
THERAPYPORTAL_PASSWORD	ポータルのパスワードです
THERAPYPORTAL_DOB	サインイン時にポータルから生年月日を求められる場合のみ指定します：MM/DD/YYYY（M/D/YYYY と YYYY-MM-DD も使用できます）
THERAPYPORTAL_TRANSPORT	server または fetchproxy です。デフォルトは、メールアドレスとパスワードが設定されている場合は server です
THERAPYPORTAL_WS_PORT	fetchproxy コンセントレーターのポートです。デフォルトは 37149 です（フリート全体で共有されます）
THERAPYPORTAL_OUTPUT_DIR	ダウンロードの保存先です（パス区切り文字で区切ったリスト。~ は展開されます）。デフォルトは ~/Downloads と ~/Documents です。呼び出しごとに指定する dest は、いずれかのディレクトリ内である必要があります
THERAPYPORTAL_INLINE_DOWNLOADS	true にすると、ホスト型ランナー向けにダウンロードをインライン（base64）で返します
THERAPYPORTAL_UPLOAD_DIR	アップロードの file_path を配置する場所です（パス区切り文字で区切ったリスト。~ は展開されます）。デフォルトは ~/Downloads、~/Documents、~/Desktop です。ホスト型の場合は $MCP_DATA_DIR/uploads です
MCP_CONFIRM_MODE	すべての書き込みに適用される確認ゲートのモードです。ask-user（デフォルト）では、プレビューと confirmToken のやり取りが必要です。auto では、対応するホストが1ステップで確認できます。認識できない値が指定された場合は、フェイルクローズ（refuse）になります
MCP_CONFIRM_ELICITATION	on（デフォルト）にすると、ホストが対話的に書き込みを確認できます。off にすると、confirmToken のやり取りが必須になります
FETCHPROXY_WS_HOST、FETCHPROXY_IDENTITY_DIR	fetchproxy のバインドアドレスと ID ディレクトリです（上級者向け）

ローカルインストールでは、.env.example を .env にコピーしてください。

{
  "mcpServers": {
    "therapyportal": {
      "command": "npx",
      "args": ["-y", "@chrischall/therapyportal-mcp"],
      "env": { "THERAPYPORTAL_PRACTICE": "<code>" }
    }
  }
}

サーバーを使用しない場合

skills/therapyportal-fpx は、サインイン済みのタブを通じて、シェルから fpx CLI を使って同じ読み取り操作（書き込みを除く）を行います。詳細は SKILL.md を参照してください。

開発

npm install
npm run build
npm test                 # typecheck + vitest, all mocked
npm run test:coverage    # 100% threshold

ワイヤープロトコル（トークン、サインイン、ダウンロードジョブ、書き込みの形式）については、docs/THERAPYPORTAL-API.md を参照してください。