Taiwan-Health-MCP

Taiwan Health MCP Server

Servidor MCP de integração de dados de saúde de Taiwan Integra ICD-10-CM/PCS, SNOMED CT, LOINC, medicamentos da FDA de Taiwan / suplementos de saúde / nutrição alimentar, e ferramentas de autorização e validação de IG FHIR R4

Servidor Node.js construído com o TypeScript MCP SDK oficial (@modelcontextprotocol/sdk), expondo 49 ferramentas em 11 grupos de ferramentas. Projetado para implantação SaaS de produção com alto throughput.

Ambiente de execução do backend: todo o backend (servidor MCP, API REST do painel administrativo, workers em segundo plano, todos os carregadores de dados) é Node.js / TypeScript, com código em node-server/. O frontend (SPA do painel administrativo) é Next.js, em web/. Este projeto não possui mais dependências de runtime Python. As páginas públicas e legais (/, /status, /privacy, /dpa) foram movidas para fora deste projeto, agora fornecidas por um site promocional separado.

Recursos do projeto

• Dados localizados de Taiwan: medicamentos da FDA de Taiwan (incluindo bula / aparência / análise OCR + LLM), suplementos de saúde, nutrição alimentar, TWCore IG.
• Suporte a terminologias internacionais: ICD-10-CM/PCS 2025, SNOMED CT International, LOINC 2.80, FHIR R4.
• Ferramentas de autorização FHIR IG: consulta de perfis / ValueSets de múltiplos IGs (com escopo de pacote), validação de terminologia, geração e validação de recursos com preenchimento de esqueleto (skeleton-fill).
• Busca semântica / híbrida: baseada em modelo de embeddings (padrão Ollama qwen3-embedding), com fallback automático para busca por palavras-chave quando não há embeddings.
• Ativação dinâmica de ferramentas: registra / remove ferramentas MCP disponíveis automaticamente conforme o estado de carregamento de dados de cada módulo.
• Painel administrativo: Admin Console opcional (upload de arquivos de origem, execução / agendamento de importações, gerenciamento de configurações e servidores FHIR externos, monitoramento em tempo real de trabalhos em segundo plano).
• Design para implantação em produção: PostgreSQL 16 (pgvector), pgBouncer, Redis, MinIO, Prometheus, workers em segundo plano, com nginx como ponto único de entrada.

Uma ferramenta exibida como available apenas indica que os dados de origem foram carregados, não que os embeddings estão completos. Verifique a contagem de Embeddings de cada módulo em Admin → Modules; quando incompletos, a busca fará fallback ou misturará keyword/BM25.

Início rápido

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

docker compose up -d iniciará:

Serviço	Descrição
nginx	Ponto único de entrada, padrão :8080 (WEB_PORT)
web	Frontend Next.js: SPA do painel administrativo /admin
app	Servidor MCP Node + API REST do painel administrativo (node dist/server.js; apenas na rede interna, sem expor porta ao host)
admin-worker	Executor de trabalhos em segundo plano (todas as importações e trabalhos de embedding, node dist/admin/adminWorker.js)
postgres	PostgreSQL 16 + pgvector
pgbouncer	Pool de conexões (modo transação)
redis	Cache de respostas
minio + minio-init	Armazenamento de objetos de ativos de medicamentos

Importante: o contêiner app não expõe a porta 8000 ao host; todo o tráfego deve passar pelo nginx. Use sempre http://<host>:8080 (ou o WEB_PORT que você configurou).

Reimplantação após alterações de código:

docker compose build app web && docker compose up -d --no-deps app web

Carregamento de dados (por meio do painel administrativo)

A importação de dados é acionada pelo Admin Console e executada em segundo plano por admin-worker (não há contêiner CLI data-loader separado).

1. Habilite o painel administrativo em .env:

   ADMIN_ENABLED=true
   ADMIN_USERNAME=admin
   # 產生密碼雜湊（Node；本專案已無 Python 相依）：
   #   node -e "console.log('sha256$' + require('crypto').createHash('sha256').update('change-me').digest('hex'))"
   # ⚠️ 在 .env 中，每個 $ 都要寫成 $$（Docker Compose 會把 $ 當變數展開，
   #    當雜湊值以字母開頭時會被靜默截斷）。Compose 會把 $$ 還原成單一 $。
   ADMIN_PASSWORD_HASH=sha256$$...
   ADMIN_SESSION_SECRET=change_this_admin_session_secret
   

   Após reiniciar (docker compose up -d), faça login em http://<host>:8080/admin.

2. Na aba Modules, importe os dados por módulo:

   • Requer upload de arquivos de origem (faça upload em Sources / Modules e depois clique em importar): ICD-10-CM/PCS, LOINC, SNOMED CT, RxNorm, FHIR IG (package.tgz).
   • Busca automática via API (clique em importar diretamente ou configure agendamento): medicamentos (TFDA, três fases: indexação → enriquecimento por rastreamento → análise OCR/LLM), suplementos de saúde, nutrição alimentar.

3. O embedding (busca semântica) é um trabalho independente de *_embed, executável nas páginas de cada módulo. Os endpoints de embedding / OCR / LLM de análise são configurados na aba Settings (armazenados em admin.llm_profiles, não por meio de variáveis de ambiente).

O progresso da importação, a linha do tempo das etapas e os logs em tempo real podem ser visualizados na aba Tasks. Consulte a documentação do painel administrativo e trabalhos em segundo plano e agendamento.

Grupos de ferramentas

Grupo	Ferramentas
ICD-10	search_medical_codes, infer_complications, get_nearby_codes, check_medical_conflict, browse_icd_category
Medicamentos / TFDA	search_drug, identify_unknown_pill, get_drug_details, get_drug_asset_links
Exames / LOINC	search_loinc, query_loinc, interpret_lab_result, batch_interpret_lab_results
SNOMED CT	search_snomed_concept, query_snomed_concept, get_snomed_relationships, query_snomed_mapping
FHIR Condition	query_fhir_condition, validate_fhir_condition
FHIR Medication	query_fhir_medication, validate_fhir_medication
FHIR IG (autorização / validação)	fhir_list_igs, fhir_get_ig, fhir_list_artifacts, fhir_search_artifacts, fhir_list_resource_profiles, fhir_rank_resource_profiles, fhir_get_profile, fhir_get_profile_elements, fhir_get_valueset, fhir_expand_valueset, fhir_lookup_code, fhir_validate_code, fhir_normalize_code, fhir_resolve_reference, fhir_build_bundle, fhir_validate_resource, fhir_validate_bundle, fhir_get_resource_skeleton, fhir_finalize_resource
Suplementos de saúde	search_health_supplements
Nutrição alimentar	query_food_nutrition, query_food_ingredient, search_foods_by_nutrient, analyze_meal_nutrition
Servidor FHIR	list_fhir_servers, get_fhir_server_status, crud_fhir_server
Sistema	health_check

As ferramentas relacionadas a módulos são habilitadas / desabilitadas automaticamente conforme o estado de carregamento de dados; as ferramentas de servidor FHIR e de sistema são sempre registradas.

Exceto crud_fhir_server, todas as ferramentas são somente leitura. crud_fhir_server pode executar operações de escrita (create / update / patch / delete) em servidores FHIR externos registrados pelo administrador, desde que o allow-list do servidor permita e o chamador inclua confirm_write=true.

Conexão de clientes

Ambas as interfaces são fornecidas pelo front-end nginx (padrão :8080):

Interface	Endpoint	Clientes compatíveis
MCP (streamable-http)	http://<host>:8080/mcp	Clientes MCP nativos (Claude Desktop, conexões MCP do Open WebUI v0.6.31+ etc.)
OpenAPI bridge	GET http://<host>:8080/openapi.json, POST http://<host>:8080/tools/<工具名>	Clientes que suportam apenas servidores de ferramentas OpenAPI (como External Tools / tipo OpenAPI do Open WebUI)

/openapi.json gera dinamicamente a especificação OpenAPI 3.1 com base nas "ferramentas atualmente habilitadas"; cada ferramenta corresponde a POST /tools/<工具名>, chamada com corpo JSON como parâmetros. O cliente só precisa preencher a URL base http://<host>:8080 e buscará automaticamente /openapi.json.

Nota: ambas as interfaces atualmente não exigem autenticação (consistente com o design existente); ao expor publicamente, adicione um proxy reverso ou token na frente.

Schema do banco de dados

audit | admin | icd | drug | health_supplements | food_nutrition | loinc | fhir (multi-IG) | snomed | rxnorm

Definições completas em db/schema.sql (aplicadas automaticamente na primeira inicialização do contêiner PostgreSQL); alterações incrementais em db/migrations/.

Painel administrativo (opcional)

Desabilitado por padrão. Após configurar ADMIN_ENABLED=true em .env e fornecer ADMIN_USERNAME / ADMIN_PASSWORD_HASH / ADMIN_SESSION_SECRET, pode ser acessado em /admin para upload de arquivos de origem, execução e agendamento de importações de dados, gerenciamento de configurações e servidores FHIR externos, e monitoramento de trabalhos em segundo plano executados por admin-worker. Consulte docs/admin/.

Desenvolvimento

# 後端（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）
cd web
npm install
npm run build
npm run typecheck

Consulte o guia de desenvolvimento e o guia de testes.

Documentação

Documentação completa em docs/; a versão online é publicada por MkDocs em GitHub Pages (configuração em mkdocs.yml).

Agradecimentos

• Ministério da Saúde e Bem-Estar de Taiwan, TFDA
• Regenstrief Institute (LOINC)
• SNOMED International
• National Library of Medicine (RxNorm / UMLS)
• HL7 International (FHIR)
• WHO