Taiwan-Health-MCP

https://github.com/user-attachments/assets/13527dd9-72ac-4e36-9868-7967399d4041

以官方 TypeScript MCP SDK（@modelcontextprotocol/sdk）建構的 Node.js 伺服器，對外提供 63 個工具，涵蓋 12 個工具群組。專為高吞吐量的生產級 SaaS 部署設計。

快速連線

不想自己架設，可以直接連官方端點 https://tw-health-mcp.healthymind-tech.com/mcp（MCP streamable-http）。

Claude Code

claude mcp add --transport http taiwan-health https://tw-health-mcp.healthymind-tech.com/mcp

Claude Desktop / claude.ai：在「設定 → 連接器」新增自訂連接器，貼上上面的端點網址。

其他支援 MCP streamable-http 的客戶端，填入同一個網址即可。要在自己的環境部署，請看自行部署。

六大面向

FHIR Box 連接 · 3 個工具

管理者登錄院內 FHIR Box 或任何 FHIR R4 伺服器後，AI agent 就能查詢與讀取資源

crud_fhir_serverget_fhir_server_status

文件 →

TW IG 驗證與 grounding · 26 個工具

多 IG 剖面與 ValueSet、骨架填值產生資源、對齊 HL7 validator_cli 7.0.1 的驗證，以及不靠 LLM 的病歷忠實度檢查

fhir_validate_resourcefhir_check_grounding

文件 →

台灣藥品與營養 · 9 個工具

TFDA 藥品許可證、仿單 OCR、依刻字 / 顏色 / 外型辨識藥丸，加上健康食品與食品營養成分

identify_unknown_pillquery_food_nutrition

文件 →

國際語彙 · 13 個工具

ICD-10-CM / PCS（CMS 2026-04-01）、SNOMED CT International、LOINC 2.80 與 RxNorm：查碼、跨語彙映射、解讀檢驗值

search_medical_codesinterpret_lab_result

文件 →

臨床計算器 · 11 個工具

CHA₂DS₂-VASc、Wells、HAS-BLED、CURB-65、qSOFA、GCS、eGFR、DAS28、CDAI、BMI（台灣切點）；確定性計算，不讓 LLM 自己算

calculate_egfrcalculate_chads2_vasc

文件 →

語意搜尋 · 跨模組

ICD-10、LOINC、SNOMED CT 與 IG CodeSystem 以 pgvector 嵌入（預設 Ollama qwen3-embedding）做混合搜尋；沒有嵌入時自動退回關鍵字搜尋

search_loincfhir_normalize_code

文件 →

• 模組相關工具會依資料載入狀態自動啟用 / 停用（例如健康補充品、食品營養未載入時，/openapi.json 只會列出 58 個）；FHIR 伺服器、臨床計算器與系統工具則永遠註冊。管理後台「MCP 工具」頁（/admin/mcp）列出全部 63 個工具、未註冊的原因，並可線上試呼叫。
• 除 crud_fhir_server 外，所有工具皆為唯讀。crud_fhir_server 可對已由管理者登錄的外部 FHIR 伺服器執行寫入（create / update / patch / delete），且必須該伺服器的 allow-list 允許、呼叫端並帶入 confirm_write=true。
• 工具顯示為 available 只代表來源資料已載入，不代表 embedding 已完整。請在管理後台各模組頁（如「醫療術語」底下的 ICD-10 / LOINC / SNOMED）檢查 Embeddings 計數；未完成時搜尋會退回或混用 keyword/BM25（回應會標 search_mode: "keyword_only"）。
• 術語範圍：ICD-10-CM（CMS 2026-04-01 完整碼表，含第 7 碼）/ ICD-10-PCS、WHO ICD-10（選用）、SNOMED CT International（含 inactive 內容與歷史關聯）、LOINC 2.80（含 answer / part / panel）、RxNorm、FHIR R4；內建 validator 另支援 CVX、ISO 3166、UCUM。Validator 稽核見 node-server/scripts/validator-audit/。

架構

flowchart LR
  subgraph clients["客戶端"]
    agent["AI agent<br/>Claude · ChatGPT · Cursor"]
    openapi["OpenAPI 客戶端<br/>Open WebUI"]
    admin["管理者"]
  end
  subgraph stack["docker compose"]
    nginx["nginx :8080<br/>單一入口"]
    app["app<br/>MCP server + 管理 API"]
    web["web-v2<br/>管理後台 SPA"]
    worker["admin-worker<br/>匯入與嵌入"]
    pg[("PostgreSQL 16 + pgvector<br/>經 pgBouncer")]
    redis[("Redis<br/>即時事件")]
    minio[("MinIO<br/>來源檔與藥品資產")]
    nginx --> app
    nginx --> web
    app --> pg
    worker --> pg
    app <--> redis
    worker <--> redis
    worker --> minio
  end
  agent -- "/mcp" --> nginx
  openapi -- "/openapi.json · /tools/*" --> nginx
  admin -- "/admin" --> nginx
  worker -.-> ext["嵌入模型 · OCR · Analysis LM<br/>TFDA Open Data"]
  app -.-> fhir["外部 FHIR 伺服器"]

• 後端全部是 Node.js / TypeScript（node-server/）：app 提供 MCP 與管理 API，admin-worker 執行所有匯入與嵌入工作。本專案已無 Python 執行期相依。
• 管理後台是 Vite + React + Mantine 的 SPA（web-v2/）；舊的 Next.js web/ 只留在 compose profile legacy-web 供回滾。
• 工具依各模組資料載入狀態自動註冊；嵌入模型無法連線時，搜尋自動退回關鍵字。
• 指標以 Prometheus 格式輸出（METRICS_PORT，預設只綁 localhost）。
• 宣傳頁與法務頁（/、/status、/privacy、/dpa）由獨立的官網提供，不在本專案。

自行部署

git clone https://github.com/healthymind-tech/Taiwan-Health-MCP.git
cd Taiwan-Health-MCP
cp .env.example .env                          # 設定 POSTGRES_PASSWORD、ADMIN_* 等
docker compose up -d

啟動後 MCP 端點是 http://<host>:8080/mcp，到 http://<host>:8080/admin 登入管理後台匯入資料。完整說明見部署指南。

舊的 Next.js web 服務屬於 compose profile legacy-web，docker compose up -d 不會啟動它（僅供回滾）。

重要：app 容器不對主機開放 8000 埠，所有流量都必須經過 nginx。請一律使用 http://<host>:8080（或你設定的 WEB_PORT）。

程式碼變更後重新部署：

docker compose build app admin-worker web-v2 && docker compose up -d --no-deps app admin-worker web-v2

admin-worker 是另一個映像（Dockerfile.worker），只重建 app 會讓 worker 繼續跑舊的匯入程式碼。要讓 health_check 回報 git sha，建置時設定環境變數：BUILD_SHA=$(git rev-parse --short HEAD) docker compose build app admin-worker（compose.yaml 會把它當 build arg 傳入，未設定時為 dev）。

資料匯入由 Admin Console 觸發、交由 admin-worker 背景執行（無獨立的 CLI data-loader 容器）。

1. 管理後台預設啟用（ADMIN_ENABLED=true）。在 .env 設定登入資訊：

   ADMIN_USERNAME=admin
   # 首次啟動時以此明文密碼建立帳密（雜湊後存入 admin.admin_credentials，之後不再覆寫；
   # 建立後請刪除這行，改密碼請到管理後台「帳號安全」）。
   ADMIN_INITIAL_PASSWORD=change-me
   # 必改：仍為範例值時伺服器拒絕啟動（openssl rand -hex 32）
   ADMIN_SESSION_SECRET=...
   

   也可改用 ADMIN_PASSWORD_HASH（sha256$<hex> 或 pbkdf2_sha256$<iterations>$<salt>$<hex>；在 .env 中每個 $ 要寫成 $$）。啟動後（docker compose up -d），於 http://<host>:8080/admin 登入。

2. 在各模組頁（側邊欄「醫療術語」、「藥品」、「健康食品」、「食品營養」、「IG 套件庫」）匯入資料：

   • **需上傳來源檔