EHR Tools with MCP and FHIR

Pesquise e consulte dados do Prontuário Eletrônico do Paciente (EHR) usando SMART on FHIR.

GitHub
87
Experimente este MCPPatrocinado

Documentação

EHR Tools with MCP and FHIR

EHR Tools Overview

https://youtu.be/K0t6MRyIqZU?si=Mz4d65DcAD3i2YbO

Este projeto atua como um servidor especializado que fornece ferramentas para Modelos de Linguagem de Grande Porte (LLMs) e outros agentes de IA interagirem com Registros Eletrônicos de Saúde (EHRs). Ele utiliza o padrão SMART on FHIR para acesso seguro a dados e o Model Context Protocol (MCP) para expor as ferramentas.

Pense nele como um gateway seguro e um kit de ferramentas que permite que a IA acesse e analise com segurança dados de pacientes de diversos sistemas de EHR.

A Ideia Central

O sistema funciona em três etapas principais:

  1. Cliente SMART on FHIR (Implementado neste projeto): Conecta-se com segurança a um EHR usando o framework padrão SMART App Launch. Ele extrai uma ampla gama de informações do paciente, incluindo tanto dados estruturados (como condições, medicamentos, exames laboratoriais) quanto notas clínicas não estruturadas ou anexos.
  2. Servidor MCP (Este Projeto): Pega os dados extraídos do EHR e os disponibiliza por meio de um conjunto de ferramentas poderosas acessíveis via Model Context Protocol. Essas ferramentas permitem que sistemas externos (como modelos de IA) consultem e analisem os dados sem precisar de acesso direto ao EHR.
  3. Interface de IA / LLM (Consumidor Externo): Um agente de IA ou Modelo de Linguagem de Grande Porte conecta-se ao Servidor MCP e usa as ferramentas fornecidas para "fazer perguntas" sobre o registro do paciente, realizar buscas ou executar análises personalizadas.

Ferramentas Disponíveis

O Servidor MCP oferece várias ferramentas para interagir com os dados de EHR carregados:

  • grep_record: Realiza buscas por texto ou expressões regulares em todas as partes do registro obtido (dados FHIR estruturados + texto de notas/anexos). Ideal para encontrar palavras-chave ou menções específicas (ex.: "diabetes", "aspirina").
  • query_record: Executa consultas SQL SELECT somente leitura diretamente contra os dados FHIR estruturados. Útil para consultas precisas baseadas em estruturas de recursos FHIR conhecidas (ex.: encontrar resultados laboratoriais específicos por código LOINC).
  • eval_record: Executa código JavaScript personalizado diretamente nos dados obtidos (recursos FHIR + anexos). Oferece máxima flexibilidade para cálculos complexos, combinação de dados de múltiplas fontes ou formatação personalizada.

Esta configuração permite que ferramentas de IA aproveitem dados abrangentes de EHR por meio de uma interface padronizada e segura.

(Detalhes de configuração e uso para desenvolvedores podem ser encontrados no código-fonte e na documentação específica dos módulos.)

Componentes e Uso

Este projeto oferece diferentes maneiras de obter dados de EHR e expô-los por meio das ferramentas MCP:

1. Cliente Web SMART on FHIR Autônomo

Este projeto inclui uma aplicação web autônoma que permite aos usuários conectar-se ao seu EHR via SMART on FHIR e obter seus dados.

  • Versão Hospedada: Você pode usar uma versão publicamente hospedada em:
    https://mcp.fhir.me/ehr-connect#deliver-to-opener:$origin
    (Substitua $origin pela origem real da janela que abre este link).
  • Filtragem de Marcas (?brandTags): Você pode filtrar a lista de provedores de EHR exibida na página de conexão adicionando o parâmetro de consulta brandTags à URL. Forneça uma lista de tags separadas por vírgulas. Somente marcas que correspondam a todas as tags fornecidas (a partir de sua configuração em brandFiles) serão exibidas. Suporta lógica OR (separada por vírgulas) e AND (separada por acento circunflexo ^), com AND tendo precedência.
    • ?brandTags=epic,sandbox: Mostra marcas marcadas com epic OU sandbox.
    • ?brandTags=epic^dev: Mostra marcas marcadas com epic E dev.
    • ?brandTags=epic^dev,sandbox^prod: Mostra marcas marcadas com (epic E dev) OU (sandbox E prod).
    • Se o parâmetro for omitido, o padrão é mostrar marcas marcadas com prod.
    • Exemplo: .../ehr-connect?brandTags=hospital^us: Mostra marcas marcadas com hospital E us.
  • Como Funciona: Quando aberta, esta página solicita que o usuário selecione seu provedor de EHR. Em seguida, inicia o fluxo padrão SMART App Launch, redirecionando o usuário para a página de login do seu EHR. Após autenticação e autorização bem-sucedidas, o cliente obtém um conjunto abrangente de recursos FHIR (Patient, Conditions, Observations, Medications, Documents, etc.) e tenta extrair texto simples de quaisquer anexos associados (como PDFs, RTF, HTML encontrados em DocumentReference).
  • Saída de Dados (ClientFullEHR): Quando a obtenção é concluída, o cliente reúne todos os dados em um objeto JSON ClientFullEHR. Este objeto contém:
    • fhir: Um dicionário onde as chaves são tipos de recursos FHIR (ex.: "Patient") e os valores são matrizes dos recursos FHIR correspondentes.
    • attachments: Uma matriz de objetos de anexos processados, cada um incluindo metadados (recurso de origem, caminho, tipo de conteúdo) e o próprio conteúdo (contentBase64 para dados brutos, contentPlaintext para texto extraído).
  • Entrega de Dados: Se aberto com o hash #deliver-to-opener:$origin, o cliente solicitará confirmação do usuário e então enviará o objeto ClientFullEHR de volta para a janela que o abriu usando window.opener.postMessage(data, targetOrigin).

2. Servidor MCP Local via Stdio (src/cli.ts)

Este modo é ideal para executar o servidor MCP localmente, frequentemente usado com ferramentas como Cursor ou outros clientes de IA de linha de comando.

  • Processo em Duas Etapas:
    1. Obter Dados para o Banco de Dados: Primeiro, execute a interface de linha de comando com os flags --create-db e --db. Isso inicia um servidor web temporário e usa a mesma lógica do cliente web SMART on FHIR descrita acima para obter dados. Em vez de enviar os dados via postMessage, ele salva os dados ClientFullEHR em um arquivo de banco de dados SQLite local. 
      # Example: Fetch data and save to data/my_record.sqlite
bun run src/cli.ts --create-db --db ./data/my_record.sqlite
      Siga as instruções (abrindo um link no seu navegador) para conectar-se ao seu EHR.
    2. Executar o Servidor MCP: Depois que o arquivo de banco de dados for criado, execute a CLI novamente, apontando apenas para o arquivo de banco de dados. Isso carrega os dados na memória e inicia o servidor MCP, escutando comandos na entrada/saída padrão. 
      # Example: Start the MCP server using the saved data
bun run src/cli.ts --db ./data/my_record.sqlite
    • Configuração (config.*.json): Este processo depende de um arquivo de configuração (ex.: config.epicsandbox.json) que define as marcas/endpoints de EHR disponíveis em uma matriz brandFiles. Cada entrada nesta matriz especifica os detalhes da marca, incluindo:
      • url: Caminho/URL para o arquivo de definição da marca (como static/brands/epic-sandbox.json).
      • tags: Uma matriz de strings (ex.: ["epic", "sandbox"]) usada para categorização ou filtragem.
      • vendorConfig: Contém detalhes do cliente SMART on FHIR (clientId, scopes).
  • Configuração do Cliente (ex.: Cursor): Configure seu cliente MCP para executar este comando. Crucialmente, use caminhos absolutos tanto para src/cli.ts quanto para o arquivo de banco de dados. 
    {
  "mcpServers": {
    "local-ehr": {
      "name": "Local EHR Search",
      "command": "bun", // Or the absolute path to bun
      "args": [
          "/home/user/projects/smart-mcp/src/cli.ts", // Absolute path to cli.ts
          "--db",
          "/home/user/projects/smart-mcp/data/my_record.sqlite" // Absolute path to DB file
        ]
    }
  }
}

3. Servidor MCP Completo via SSE (src/sse.ts / index.ts)

Este modo executa um servidor persistente adequado para cenários onde múltiplos clientes podem se conectar pela rede. Ele usa Server-Sent Events (SSE) para o canal de comunicação MCP.

  • Autenticação: A autenticação do cliente depende de OAuth 2.1, conforme especificado pelo Model Context Protocol. O servidor fornece endpoints padrão (/authorize, /token, /register, etc.).
  • Obtenção de Dados: Quando um cliente inicia uma conexão OAuth, o servidor lida com o fluxo SMART on FHIR ele mesmo, obtém os dados ClientFullEHR durante o processo de autorização e os mantém em memória (ou em uma sessão persistida) durante a conexão do cliente.
  • Status: Embora funcional, a especificação MCP para interação com clientes OAuth 2.1 ainda está em evolução. O suporte do cliente para este método de autenticação é extremamente limitado atualmente, tornando difícil testar este modo com clientes padrão fora de ferramentas especializadas de desenvolvimento ou depuração. Este modo SSE deve ser considerado experimental.