Skip to main content
Glama
fabianofilho

revisor-notas

by fabianofilho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

revisor-notas-mcp

Servidor MCP que confere notas clínicas no formato SOAP (F/S/O/A/P): checa se os campos obrigatórios estão preenchidos e usa um LLM local para apontar incoerências entre queixa, exame e conduta. Roda inteiramente na sua máquina — o texto da nota não sai dela.

⚠️ Não substitui o julgamento clínico

  • Isto não é um software de apoio à decisão clínica. Não foi validado clinicamente, não foi avaliado por nenhum órgão regulador e não é um dispositivo médico.

  • A checagem semântica é probabilística. Ela é feita por um LLM lendo texto livre: erra para os dois lados. Ausência de avisos não atesta que a nota está correta, e um aviso pode ser falso positivo.

  • A responsabilidade pela nota continua sendo de quem assina. A ferramenta aponta o que pode ter faltado; ela não sabe do paciente nada além do que está escrito.

  • O projeto foi escrito em torno de um template específico de telemedicina. Se o seu formato for outro, as regras determinísticas precisam ser ajustadas.

Requisitos

O quê

Versão

Para quê

Python

3.12+

runtime

uv

recente

dependências e venv

Um LLM local com API OpenAI-compatible

—

checagem semântica (opcional)

Sem banco de dados: este projeto não persiste nada.

Related MCP server: Konsilium

Instalação

git clone https://github.com/fabianofilho/revisor-notas-mcp.git
cd revisor-notas-mcp
uv sync
cp .env.example .env

Configuração

Variável

Padrão

Observação

QWEN_ENDPOINT

http://127.0.0.1:8080/v1

llama.cpp. Ollama: :11434/v1. LM Studio: :1234/v1

QWEN_MODEL

local-model

llama.cpp e LM Studio aceitam qualquer nome

TIMEOUT_CHECAGEM_SEMANTICA_SEGUNDOS

15

curto de propósito: a checagem não pode travar a resposta

O endpoint precisa ser localhost. Qualquer outro host é recusado com exceção, não com aviso — ver Privacidade.

uv run revisor-cli llm                        # confirma o LLM local
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

Ligando ao Claude Code

claude mcp add revisor-notas --scope user \
  -e QWEN_ENDPOINT=http://127.0.0.1:8080/v1 \
  -e QWEN_MODEL=local-model \
  -- uv --directory /caminho/para/revisor-notas-mcp run revisor-notas-mcp

Uso

validar_nota_soap(texto_nota: str)

Lista os problemas encontrados, cada um com seção, severidade, sugestão e a origem (regra ou semantica).

{
  "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"
    }
  ]
}

Esse exemplo é a saída real de uma nota sintética de teste. Note que total_erros é zero: a nota está formalmente correta — as regras determinísticas passam limpo. O que a camada semântica aponta é clínico, e é exatamente o que regra não pega.

sugerir_correcoes(texto_nota: str)

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.

As duas camadas

Regras determinísticas (rules/) — rodam sempre, sem LLM: cabeçalho, as cinco seções, CID em formato válido, itens numerados do plano, item de sinais de alarme, rodapé fixo, e os campos do subjetivo (medicações em uso, antecedentes, alergia, hábitos).

Checagem semântica (llm/) — coerência entre queixa, exame e conduta; e sinais de alarme típicos do diagnóstico que não aparecem como investigados (negativa explícita conta como investigado).

Se o LLM local estiver fora do ar, a validação por regras responde sozinha e a resposta diz que a parte semântica não rodou. As regras nunca ficam bloqueadas pelo modelo.

Limitações conhecidas

O parser espera um template específico. Ele tolera variação de formatação (marcador com ou sem hífen, caixa baixa, espaço sobrando), mas as regras de conteúdo — quais campos são obrigatórios, qual rodapé, quais itens no plano — foram escritas para um template de telemedicina. Adaptar para outro formato significa mexer em rules/checklist.py.

A checagem semântica depende de um modelo pequeno. Rodando local, ela custa alguns segundos e a qualidade varia com o modelo. Um modelo fraco vai gerar falso positivo.

A validação de CID é sintática, não semântica. Ela confere o formato (letra + dois dígitos, com subcategoria opcional), não se o código corresponde ao diagnóstico escrito.

Nada é cacheado. Cada chamada reprocessa a nota do zero, porque cachear significaria guardar o texto — e isso o projeto não faz.

Privacidade

Este é o ponto central do projeto, e ele está em código e em teste, não só aqui:

  • Nenhuma chamada de rede além de localhost. O cliente do LLM recusa com exceção (EndpointNaoLocal) um endpoint que aponte para qualquer outro host. Configuração perigosa estoura em vez de degradar em silêncio.

  • Nada é gravado. Sem banco, sem cache em disco, sem log do conteúdo. O processamento é em memória, por chamada. Há um teste que confere que nenhum trecho da nota aparece em log, inclusive quando a chamada ao LLM falha.

  • Fixtures de teste são sintéticas, nunca dado real, nem anonimizado.

  • Sem telemetria, sem analytics.

O que sai da sua máquina: nada. O que vai para o seu LLM local: o texto da nota, pelo localhost.

Contribuindo

Veja CONTRIBUTING.md. A regra mais importante e sem exceção: nenhuma fixture pode conter dado real de paciente, nem anonimizado.

Licença e atribuição

Apache License 2.0 — escolhida por o projeto tocar em dado de paciente, onde a cláusula explícita de patente é mais protetiva.

Construído no contexto do IA.med.

Available Tools

2 tools
sugerir_correcoesA

Devolve a nota com anotações inline do que precisa ser ajustado.

Não reescreve o texto original: cada problema vira uma linha <<AVISO: ...>> logo abaixo da seção correspondente, para o médico decidir o que mudar.

Args: texto_nota: a nota completa a ser anotada.

ParametersJSON Schema
NameRequiredDescriptionDefault
texto_notaYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
avisoNo
nota_anotadaYes
total_anotacoesYes
checagem_semantica_feitaYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavior. It clearly discloses that the tool returns the note with inline annotations, each problem marked as a line '<<AVISO: ...>>' below the section, and explicitly states it does not rewrite the original text. It does not cover error handling or edge cases, but for a simple transformation tool, this is solid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a first sentence stating the core behavior, a second sentence detailing the output format and non-rewriting guarantee, and a brief Args line. Every sentence earns its place, with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single parameter and an output schema (though not shown), the description adequately explains the output format (the inline <<AVISO>> annotations) and the main behavior. It does not mention edge cases like no corrections, but given the simplicity, it is sufficiently complete for an agent to call correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides no description for the parameter (coverage 0%), but the description includes an Args section that fully explains 'texto_nota' as 'a nota completa a ser anotada'. This adds essential meaning beyond the schema, making the parameter's purpose clear and complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('Devolve a nota com anotações inline') and a specific resource (the nota), and explicitly clarifies that it does NOT rewrite the original text. This distinguishes it from an editing tool and is consistent with its name, making its purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies its use case (suggesting corrections for the doctor to decide) but does not explicitly mention when to prefer it over the sibling 'validar_nota_soap' or when not to use it. The context suggests it is for corrective suggestions rather than validation, but this is not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validar_nota_soapA

Valida uma nota clínica no formato #TELEMEDICINA# (F/S/O/A/P).

Checa campos obrigatórios, CID, numeração do plano e rodapé por regras determinísticas, e usa o LLM local para conferir coerência entre queixa, exame e conduta, além de sinais de alarme não investigados. A parte do LLM é probabilística e vem marcada como tal; se ele estiver fora do ar, as regras respondem sozinhas.

O texto processado não sai da máquina nem é gravado em lugar nenhum.

Args: texto_nota: a nota completa, como seria colada no prontuário.

ParametersJSON Schema
NameRequiredDescriptionDefault
texto_notaYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
avisoNo
problemasYes
total_errosYes
total_avisosYes
motivo_semantica_puladaNo
checagem_semantica_feitaYesFalse quando o LLM local não respondeu; as regras valeram assim mesmo

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the hybrid deterministic/LLM nature, that the LLM part is probabilistic and marked as such, that rules take over if the LLM is down, and that the text does not leave the machine or get stored. This goes beyond typical descriptions and addresses privacy and failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: it opens with the core purpose, then explains the validation logic and LLM behavior, includes a privacy note, and ends with the Args section. It is more than two sentences but every sentence carries relevant information; it is efficient without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists (not shown but indicated), the description need not explain return values. It covers the validation scope, the probabilistic LLM component, fallback behavior, and privacy. It does not mention prerequisites or limitations, but for a single-parameter validation tool, the information provided is sufficient for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has a single parameter 'texto_nota' with no description coverage (0%). The tool description adds meaning by specifying it is 'a nota completa, como seria colada no prontuário', clarifying that the entire note is expected as it would be pasted in the medical record. This compensates for the schema's lack of description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool validates a clinical note in the #TELEMEDICINA# format (F/S/O/A/P), which is a specific verb and resource. It does not explicitly distinguish from the sibling tool 'sugerir_correcoes', but the purpose is unambiguous and distinct in function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description details what the tool checks (required fields, CID, plan numbering, footer, and LLM coherence) and mentions fallback behavior when the LLM is offline. However, it never explains when to use this tool versus the sibling 'sugerir_correcoes', nor does it state any conditions for when not to use it. Usage is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedsugerir_correcoes
    • First observedvalidar_nota_soap
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 2 tools

Disambiguation4/5

The two tools have distinct outputs: one returns a validation verdict, the other returns inline annotations. They overlap in that both identify problems, but their purposes and return formats are clearly separated.

Naming Consistency4/5

Both names follow a snake_case verb_noun pattern (validar_nota_soap, sugerir_correcoes), which is consistent. The 'soap' qualifier on one name is a minor deviation but does not break the overall style.

Tool Count3/5

Only two tools exist, which feels thin for a general-purpose note-review server. However, the narrow scope of validating and suggesting corrections makes the count acceptable, though barely.

Completeness4/5

The surface covers the core workflow: validate and get inline suggestions. There is no automatic rewrite tool, but the description explicitly states that is intentional, so no obvious dead ends exist.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers