healsens-fhirmcp

Servidor MCP de código aberto e com conformidade para FHIR R4 e R5.

GitHub
1
Experimente este MCPPatrocinado

Documentação

healsens-fhirmcp

Servidor MCP de código aberto e ciente de conformidade para FHIR R4 e R5.

healsens-fhirmcp é a implementação MCP da Healsens para sistemas de saúde que já expõem FHIR e desejam tornar esses dados utilizáveis por agentes de IA de forma segura, previsível e com consciência de esquema muito melhor do que um proxy fino pode oferecer. Ele fica à frente de uma URL base FHIR configurada e expõe uma superfície MCP focada e somente leitura para leitura de recursos, busca tipada, descoberta de conformidade e operações seguras somente leitura.

A ideia central é simples: os modelos têm melhor desempenho quando o servidor os ajuda a entender a API FHIR alvo. Este projeto incorpora artefatos de conformidade FHIR com versão correspondente e os combina com o CapabilityStatement ao vivo do servidor conectado, para que as chamadas de ferramentas permaneçam fundamentadas na forma, semântica e capacidades do endpoint real.

Por Que Este Projeto Existe

A maioria das integrações de IA em saúde falha de maneiras previsíveis: wrappers HTTP genéricos expõem área de superfície demais, modelos adivinham parâmetros de busca e diferenças de FHIR entre servidores transformam tarefas simples em engenharia de prompt frágil. O healsens-fhirmcp foi projetado para resolver esse problema diretamente.

Ele oferece às equipes uma camada MCP prática que é:

  • ciente de FHIR em vez de agnóstico de endpoint
  • fundamentado em metadados reais de conformidade em vez de suposições baseadas apenas em prompt
  • seguro por design com um conjunto de ferramentas somente leitura e um servidor alvo fixo
  • utilizável em fluxos de integração de produção via stdio ou SSE nativo

Este repositório é de código aberto para dar aos implementadores uma base concreta e confiável para implantações MCP em saúde, não apenas um exemplo de brinquedo.

Acesso à Demonstração

Uma demonstração ao vivo está disponível para equipes que avaliam o projeto. Para solicitar acesso, envie um e-mail para contact[at]healsens[dot]com.

O Que Ele Oferece

  • Servidor alvo FHIR único configurado
  • Superfície de ferramentas MCP somente leitura
  • Suporte a FHIR R4 e R5
  • Registros principais incorporados de StructureDefinition e OperationDefinition
  • Busca ao vivo de CapabilityStatement com cache
  • Leitura tipada e busca tipada
  • Invocação conservadora de operações somente leitura
  • Recursos de descoberta e esquema sob o esquema de URI fhirmcp://
  • Modos de hospedagem nativos stdio e SSE

Ferramentas MCP

  • fhir_read
  • fhir_search
  • fhir_capability_statement
  • fhir_structure_definition
  • fhir_operation_definition
  • fhir_invoke_operation

Recursos MCP

  • fhirmcp://server/guide
  • fhirmcp://server/overview
  • fhirmcp://server/capability-statement
  • fhirmcp://schema/structure-definitions
  • fhirmcp://schema/structure-definition/{selector}
  • fhirmcp://schema/operation-definitions
  • fhirmcp://schema/operation-definition/{selector}
  • fhirmcp://server/search-guide

Princípios de Design

  • Conformidade em primeiro lugar: o servidor usa artefatos FHIR incorporados juntamente com o CapabilityStatement alvo ao vivo para moldar o comportamento das ferramentas.
  • Somente leitura por design: esta implementação é intencionalmente focada em recuperação segura, descoberta e operações somente leitura suportadas.
  • Superfície de integração previsível: um alvo configurado, esquemas explícitos, comportamento limitado.
  • Interoperabilidade no mundo real: suporta FHIR R4 e R5, incluindo descoberta de capacidades específicas do servidor na inicialização.

O projeto deliberadamente não tenta ser um SDK FHIR completo, um proxy genérico ou uma camada de orquestração com capacidade de escrita.

Início Rápido

  1. Copie examples/config.yaml e defina target.base_url para o seu servidor FHIR R4 ou R5.
  2. Exporte a variável de ambiente do token de portador nomeada na configuração se o seu servidor exigir autenticação.
  3. Sincronize os artefatos de conformidade fornecidos.
  4. Compile e execute o servidor via stdio ou SSE.
./scripts/sync_fhir_core_defs.sh
go mod tidy
go build -o bin/healsens-fhirmcp ./cmd/healsens-fhirmcp
FHIRMCP_CONFIG=./examples/config.yaml ./bin/healsens-fhirmcp

Com server.transport: stdio, o binário se comporta como um servidor MCP de subprocesso tradicional via stdin e stdout. Com server.transport: sse, ele expõe um endpoint MCP SSE nativo em http://127.0.0.1:8081/sse por padrão.

Modo SSE

Defina o bloco de transporte em examples/config.yaml:

server:
	transport: sse
	listen_address: 127.0.0.1:8081
	sse_path: /sse
	cors:
		enabled: true
		allowed_origins:
			- http://localhost:8788

Em seguida, inicie o servidor:

go build -o bin/healsens-fhirmcp ./cmd/healsens-fhirmcp
FHIRMCP_CONFIG=./examples/config.yaml ./bin/healsens-fhirmcp

Seu endpoint MCP SSE será:

http://127.0.0.1:8081/sse

Se o cliente for executado em um contexto de navegador, server.cors controla o acesso entre origens para o endpoint SSE e seu endpoint de mensagens POST. allowed_origins deve conter as origens exatas do navegador em que você confia.

Desenvolvimento

  • make sync-core atualiza os artefatos FHIR R4 e R5 fornecidos.
  • make build compila o binário do servidor para o modo stdio ou SSE.
  • make test executa testes unitários e de integração.