Projeto IA.med Licença Apache-2.0 Nada sai da máquina

revisor-notas-mcp

Servidor MCP que confere notas clínicas no formato SOAP: regras determinísticas mais uma checagem de coerência por LLM local. O texto da nota não sai do seu computador.

Ver no GitHub Como funciona

Não substitui o julgamento clínico

  • Não é software de apoio à decisão clínica: não foi validado clinicamente, não passou por órgão regulador e não é dispositivo médico.
  • A checagem semântica é probabilística, feita por um LLM lendo texto livre. Erra dos dois lados: ausência de aviso não atesta que a nota está correta, e um aviso pode ser falso positivo.
  • A responsabilidade pela nota continua de quem assina. A ferramenta aponta o que pode ter faltado; não sabe do paciente nada além do que está escrito.
  • As regras foram escritas para um template específico de telemedicina. Para outro formato, é preciso ajustá-las.

O problema

Por que este projeto existe

Formalmente completa, clinicamente incoerente

Uma nota pode ter todos os campos preenchidos e mesmo assim ter uma conduta que não fecha com a queixa. Regra de preenchimento não pega esse tipo de erro.

Revisar à mão é caro e inconstante

Conferir campo a campo, mais coerência clínica e sinais de alarme esperados, em cada nota, cansa e falha. É o tipo de checagem que uma máquina faz sem se distrair.

Nota clínica não pode sair da máquina

Mandar o texto de uma nota para um serviço externo é risco de privacidade. Por isso a checagem tem que rodar localmente, sem gravar nada.

Como funciona

Duas camadas sobre a mesma nota

  1. 01

    Parser SOAP

    Lê a nota no formato F/S/O/A/P, tolerando variação de formatação (marcador, caixa, espaço).

  2. 02

    Regras determinísticas

    Rodam sempre, sem LLM: cabeçalho, as cinco seções, CID em formato válido, itens do plano, sinais de alarme, rodapé e os campos do subjetivo.

  3. 03

    Checagem semântica

    Um LLM local aponta incoerência entre queixa, exame e conduta, e sinais de alarme do diagnóstico que não aparecem investigados.

  4. 04

    Problemas com origem

    Cada achado sai com seção, severidade, sugestão e a origem: regra ou semantica.

Privacidade em código, não só em texto: o cliente do LLM recusa com exceção qualquer endpoint que não seja localhost, e nada é gravado (sem banco, sem cache, sem log do conteúdo). Se o LLM local estiver fora do ar, as regras respondem sozinhas e a resposta diz que a parte semântica não rodou.

As ferramentas

Duas tools MCP expostas ao modelo

Cada problema traz a seção, a severidade e a origem (regra ou semantica). O exemplo abaixo é a saída real de uma nota sintética de teste: sem erros de formato, mas com um alerta clínico que só a camada semântica pega.

validar_nota_soap

Lista os problemas encontrados, cada um com seção, severidade, sugestão e a origem. 

validar_nota_soap(texto_nota: str)
{
  "total_erros": 0,
  "total_avisos": 2,
  "checagem_semantica_feita": true,
  "problemas": [
    {
      "secao": "F, S, A, P",
      "severidade": "aviso",
      "descricao": "A queixa é dor torácica irradiando para o braço esquerdo, com hipertensão e tabagismo, o que sugere etiologia cardíaca. A hipótese final é dor muscular e a conduta é analgésico simples.",
      "origem": "semantica"
    },
    {
      "secao": "S",
      "severidade": "aviso",
      "descricao": "Sinais de alarme esperados que não aparecem como investigados: sudorese, dispneia, náuseas.",
      "origem": "semantica"
    }
  ]
}
Saída real de uma nota sintética de teste

sugerir_correcoes

A mesma nota com linhas <<AVISO: ...>> inseridas abaixo de cada seção. Não reescreve o texto original: quem decide o que mudar é quem assina. 

sugerir_correcoes(texto_nota: str)

A - Hipótese: dor muscular
<<AVISO: queixa sugere etiologia cardíaca; revisar a hipótese>>
P - Analgésico simples
<<AVISO: sinais de alarme não investigados: sudorese, dispneia>>

Ilustração do formato de anotação inline.

Como rodar

Roda na sua máquina

Não é um serviço hospedado e não tem banco de dados. Você clona, aponta para o seu LLM local (obrigatoriamente localhost) e o servidor MCP roda ali. Sem LLM, a validação por regras responde sozinha. 

# 1. clonar e instalar
git clone https://github.com/fabianofilho/revisor-notas-mcp.git
cd revisor-notas-mcp
uv sync
cp .env.example .env

# 2. o endpoint do LLM PRECISA ser localhost (outro host é recusado)
uv run revisor-cli llm                        # confirma o LLM local

# 3. validar uma nota
uv run revisor-cli validar nota.txt           # ou cole a nota no stdin
uv run revisor-cli validar nota.txt --sem-llm # só as regras determinísticas
uv run revisor-cli anotar nota.txt            # nota com anotações inline

# 4. subir o servidor MCP e conectar ao seu cliente
uv run revisor-notas-mcp
Confira variáveis e opções no README do projeto.

O que sai da sua máquina: nada. O texto da nota vai só para o seu LLM local, pelo localhost. Um endpoint apontando para fora estoura com exceção em vez de degradar em silêncio, e há teste conferindo que nenhum trecho da nota aparece em log, mesmo quando a chamada ao LLM falha.