therapyportal-mcp

therapyportal-mcp

适用于 TherapyPortal 的 MCP 服务。TherapyPortal 是 TherapyNotes 的客户端门户 （https://www.therapyportal.com/p/<practice>/）。它会读取即将进行的治疗预约、诊所发送的文书、诊所的常驻表格、应付余额、付款收据和安全消息，并将已完成的文档和收据下载为 PDF。它还可以发送安全消息，并在确认门禁后上传文件以响应文档请求。

此项目由 AI 开发并维护。请自行斟酌使用。 它会读取心理健康记录，且始终只读取已登录用户本人账户中的记录。

并非只读

大多数工具用于读取。有三个工具会执行写入操作，每个操作都会发送到诊所，且无法通过此服务撤销：

工具	发送内容	先使用以下工具查询
therapyportal_send_message	为一位客户端创建新的安全消息对话，并指定主题	therapyportal_list_message_topics
therapyportal_reply_message	在现有对话中回复（除非设置 mark_thread_read，否则不会更改已读状态）	therapyportal_list_message_threads
therapyportal_upload_document	上传本地文件以响应待处理的文档请求，或上传要求上传的常驻表格	therapyportal_list_documents、therapyportal_list_forms

以上三个工具均标记为 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	一位客户端的安全消息对话（不会标记为已读）
therapyportal_get_thread_messages	一个对话中的消息（不会标记为已读）
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 会返回更多内容。诊所撰写的文本（文档标题、说明、消息）会放在不可信内容信封中返回。

消息工具尚未通过真实消息验证。 用于构建此工具的账号没有消息，因此线程和消息读取工具会原样返回门户的负载，而不是投影后的内容。

写入操作

这三项写入操作均根据门户自身的 JavaScript 推导而来 （SecureMessagingDataService、CreateMessageViewV2、ThreadViewV2、 DocumentsDataService、文档视图控制器和 xhrfileuploader），且未在实际传输中验证：没有自动化运行会发送消息或上传文件，因为每项操作都会触达诊所。之后会在所有者监督下进行实时测试，以确认这些操作。它们首先执行的查询（消息设置、主题、指定临床医生检查、文档和表单列表）已通过实时只读验证。

显示预览之前，每项写入操作都会根据实时读取结果进行检查：客户端是你的客户端之一（therapyportal_list_clients）、诊所已启用安全消息功能、该客户端存在此主题；若要上传，还会检查文档或表单是否存在、是否尚未完成、是否要求上传且不需要签名。

• 消息。 纯文本，长度为 1 至 5000 个字符，发送方式与门户编辑器一致（每行对应一个 HTML 段落）。如果有多条消息尚未得到回复，诊所可能会拒绝新消息；拒绝时会说明原因。已归档的对话无法回复。
• 上传。 文件必须位于 THERAPYPORTAL_UPLOAD_DIR（默认为 ~/Downloads、~/Documents 或 ~/Desktop；托管时为 $MCP_DATA_DIR/uploads）中，且必须是普通文件（不能是符号链接），文件内容必须与扩展名相符。拒绝旧版 .doc 文件（上传前无法检查其格式）；请将其另存为 PDF 或 .docx。文件会分成 100 KB 的片段暂存，经门户验证后才会提交。只有提交操作会触达诊所。
• 只发送一次。 每项写入操作都会且只会提交一次。重新登录后，无论使用哪种传输方式，都不会重放操作。如果门户以 5xx 响应发送请求，或连接中断，则会报告 status: "unknown"，而不是报错；这样模型会先检查对应列表，再决定是否重试，以避免重复发送。

确认门控

每项写入操作都通过 @chrischall/mcp-utils 的 confirmWrite 进行门控，该功能由 defineWrite / registerWrite 调用。首次调用不会发送任何内容，而是返回预览和一个 confirmToken；只有在你批准预览后，第二次调用携带该令牌才会发送。令牌会绑定确切请求（上传时包括文件名、类型、大小和 SHA-256）以及所显示的预览；因此，如果参数、文件或门户状态在预览后发生变化，操作会被拒绝，并返回 DRAFT_CHANGED。每次发送都会变化的值（上传 guid、文档日期）会在发送时生成，不会绑定到令牌。预览或结果中由诊所填写的文本（主题名称、文档标题、返回的对话）会被标记为不可信内容。MCP_CONFIRM_MODE / MCP_CONFIRM_ELICITATION 可调整此门控（参见 Configuration）。

传输方式

	服务（设置凭据时的默认方式）	浏览器桥接
工作方式	使用你的电子邮件和密码自行登录；在内存中保存 Cookie jar	通过 ContextMint Bridge 扩展，将每个请求转发至你已登录的 Chrome 标签页
要求	THERAPYPORTAL_EMAIL、THERAPYPORTAL_PASSWORD（以及门户要求时的 THERAPYPORTAL_DOB）	扩展，以及一个已登录的门户标签页
可托管（claude.ai、手机）	可以	仅限桥接注册
下载	写入 THERAPYPORTAL_OUTPUT_DIR，或以内嵌形式返回	由浏览器保存到其下载文件夹

两种方式可以并行运行。服务端登录不会结束你的浏览器门户会话（已通过实时检查），而门户会在一段时间后自行退出空闲的浏览器标签页；这是桥接报告“not signed in”的常见原因。

密码或出生日期验证失败后，绝不会重试。出生日期检查在输错几次后会锁定，因此服务只会尝试一次。

配置

变量
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 允许具备相应能力的宿主一步确认；无法识别的值会安全拒绝（refuse）
MCP_CONFIRM_ELICITATION	on（默认值）允许宿主交互式确认写入操作；off 强制执行 confirmToken 往返
FETCHPROXY_WS_HOST、FETCHPROXY_IDENTITY_DIR	fetchproxy 绑定地址和身份目录（高级选项）

本地安装时，将 .env.example 复制为 .env。

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

不使用服务端

skills/therapyportal-fpx 可通过已登录的标签页，在 shell 中使用 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。