Taiwan-Health-MCP

• 模組相關工具會依資料載入狀態自動啟用 / 停用（例如健康補充品、食品營養未載入時，/openapi.json 只會列出 58 個）；FHIR 伺服器、臨床計算器與系統工具則永遠註冊。管理後台「MCP 工具」頁（/admin/mcp）列出全部 70 個工具、未註冊的原因，並可線上試呼叫。
• 除 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/。

舊的 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 套件庫」）匯入資料：

   • 需上傳來源檔（上傳後按匯入）：ICD-10-CM（CMS order file zip）/ ICD-10-PCS、WHO ICD-10（選用）、LOINC、SNOMED CT、RxNorm；FHIR IG 可由套件 registry 安裝或上傳 package.tgz（缺少的相依套件會自動下載）。
   • 由 API 自動抓取（直接按匯入或設定排程）：藥品（TFDA，三階段：索引 → 爬取豐富 → OCR/LLM 分析）、健康補充品、食品營養。

3. 嵌入（語意搜尋）為獨立的 *_embed 工作，可於各模組頁面執行。嵌入與分析 LLM 的端點在「模型端點」頁設定（provider 帳號 + 路由，存於 admin.llm_providers / admin.llm_routes 等表），OCR（MinerU）在「外部服務」頁設定；兩者都不透過環境變數。

匯入進度、步驟時間軸與即時日誌可在「背景工作」頁查看。管理後台也用於瀏覽術語、管理外部 FHIR 伺服器、檢視 MCP 工具與備份設定；資料載入完成後可設 ADMIN_ENABLED=false 縮小公開部署的攻擊面，MCP 工具、worker 與排程匯入照常運作。詳見管理後台文件與背景工作與排程。

兩種介面都經由 nginx 前門提供（預設 :8080）：

/openapi.json 依「目前已啟用的工具」動態產生 OpenAPI 3.1 規格；每個工具對應 POST /tools/<工具名>，以 JSON body 當參數呼叫。客戶端只要填基底網址 http://<host>:8080，即會自動抓取 /openapi.json。

驗證：預設 PUBLIC_TOOLS_AUTH_MODE=none（不驗證，僅適合可信網路）。對外開放時設 PUBLIC_TOOLS_AUTH_MODE=bearer 與 PUBLIC_TOOLS_BEARER_TOKEN，三個端點（/mcp、/openapi.json、/tools/*）會一起要求 Authorization: Bearer <token>；PUBLIC_TOOLS_CORS_ORIGINS 在 bearer 模式下不可含 *。

audit | admin | icd | drug | health_supplements | food_nutrition | loinc | fhir（multi-IG）| snomed | rxnorm

完整定義見 db/schema.sql（PostgreSQL 容器首次啟動、資料卷為空時自動套用），增量變更見 db/migrations/。沒有 migration runner：既有資料庫須依檔名日期順序手動套用（例如 psql -U mcp -d taiwan_health -f db/migrations/20261020_loinc_structure.sql）。

# 後端（MCP + admin REST + worker）
cd node-server
npm install
npm run build          # tsc -> dist/
npm run typecheck      # tsc --noEmit
npm test               # node --test（node-server/src/**/*.test.ts）

# 管理後台 SPA（Vite）
cd web-v2
npm install
npm run dev            # http://localhost:5173/admin/，API 代理到 ADMIN_BACKEND（預設 http://127.0.0.1:8090）
npm run build          # tsc -b && vite build -> dist/
npm run typecheck

詳見開發指南與測試指南。