protocolos-pcdt-mcp

Servidor MCP local (stdio) que consulta os PCDTs (Protocolos Clínicos e Diretrizes Terapêuticas) do Ministério da Saúde/Conitec e resume a conduta recomendada para um contexto clínico específico, usando um LLM local. Toda resposta traz o link do PDF oficial.

Por padrão o servidor roda por stdio, na sua máquina, sem porta de rede. Há também um modo connector (HTTP), em que ele só consulta: não chama o LLM e, portanto, não gera resumos.

⚠️ Não substitui o protocolo nem o julgamento clínico

• Não é fonte oficial. O projeto lê o que a Conitec publica e guarda uma cópia local, que pode estar defasada em relação ao portal.
• O resumo é gerado por LLM e é uma ajuda de leitura. Protocolos têm exceções, populações específicas e notas de rodapé que um resumo de seis linhas não carrega.
• A citação literal é conferida, mas a interpretação não. Ver Limitações conhecidas: há um exemplo real de citação correta com conclusão clínica errada.
• Sem validação clínica. Não foi avaliado por nenhum órgão e não é dispositivo médico.
• Para conduta, leia o protocolo completo. O link vem em toda resposta.

Requisitos

O quê	Versão	Para quê
Python	3.12+	runtime
uv	recente	dependências e venv
Um LLM local com API OpenAI-compatible	-	resumo direcionado
Espaço em disco	~1 GB	base DuckDB + PDFs cacheados (protocolos são grandes)

Instalação

git clone https://github.com/fabianofilho/protocolos-pcdt-mcp.git
cd protocolos-pcdt-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
DUCKDB_PATH	./data/pcdt.duckdb	base local
COLETA_DELAY_SEGUNDOS	1	intervalo entre downloads de PDF

uv run pcdt-cli llm                 # confirma o LLM local
uv run pcdt-cli sync --max-pdfs 5   # teste rápido, grava direto na base
uv run pcdt-cli sync --publicar     # coleta (20 PDFs por execução) e troca a base no fim
uv run pcdt-cli consultar asma
uv run pcdt-cli resumir "asma" "paciente gestante"

A coleta baixa no máximo --max-pdfs protocolos por execução: são ~130 PDFs grandes, e a ideia é a base completar ao longo de algumas noites em vez de sobrecarregar o portal numa única. O texto já coletado é preservado entre execuções.

Sync diário com systemd

O servidor MCP não agenda nada sozinho. O caminho oficial para manter a base atualizada é o timer systemd de usuário versionado em deploy/systemd/: ele roda pcdt-cli sync --publicar todo dia às 02:40, com até 30 min de atraso aleatório, e recupera o disparo perdido se a máquina estava desligada.

As units supõem o clone em ~/protocolos-pcdt-mcp e o uv em ~/.local/bin/uv. Se os seus caminhos forem outros, edite WorkingDirectory e ExecStart antes de copiar.

mkdir -p ~/.config/systemd/user
cp deploy/systemd/protocolos-pcdt-sync.service deploy/systemd/protocolos-pcdt-sync.timer \
  ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now protocolos-pcdt-sync.timer
systemctl --user list-timers protocolos-pcdt-sync.timer   # próximo disparo
journalctl --user -u protocolos-pcdt-sync.service         # saída dos syncs

Para o timer rodar sem sessão aberta, habilite loginctl enable-linger $USER.

Ligando ao Claude Code

claude mcp add protocolos-pcdt --scope user \
  -e DUCKDB_PATH=/caminho/para/protocolos-pcdt-mcp/data/pcdt.duckdb \
  -e QWEN_ENDPOINT=http://127.0.0.1:8080/v1 \
  -e QWEN_MODEL=local-model \
  -- uv --directory /caminho/para/protocolos-pcdt-mcp run protocolos-pcdt-mcp

Uso

consultar_protocolo(doenca_ou_condicao: str, limite=10)

limite vai de 1 a 100 e vale para a busca pelo nome; acima disso a chamada é recusada.

Busca primeiro no nome dos PCDTs vigentes:

• sem acento e sem caixa, com as palavras em qualquer ordem, sempre no começo de uma palavra ("asma" não casa com "citoplasma");
• trocando algumas siglas pelo nome por extenso (HAS, DPOC, DM1, DM2, TDAH, LES, ELA, IC, DRC, entre outras em nomes.py);
• aceitando "diabetes"/"diabete" e "mellitus"/"melito", porque a Conitec escreve "Diabete Melito Tipo 1".

Devolve até 10 protocolos pelo nome, com origem: "nome". Se o nome não casar, procura o termo no texto completo e devolve até 5 com origem: "texto" e um aviso: esses só citam o termo e muitas vezes não são o PCDT da condição (por exemplo, "depressão" traz Alzheimer e Parkinson, que mencionam depressão).

O identificador é o nome da condição em minúsculas. Quando o portal pendura uma nota de revisão no nome, como "Asma (anexo alterado em 04/09/2026)", ela vai para nota_atualizacao e fica fora do identificador. Saída real, da base local em 24/09/2026:

{
  "termo": "acidentes ofídicos",
  "total": 1,
  "resultados": [
    {
      "identificador": "acidentes ofídicos",
      "condicao": "Acidentes Ofídicos",
      "status": "Conitec",
      "portaria": "Portaria SECTICS/MS nº 83 - 07/10/2025 (Publicada em 09/10/2025 )",
      "data_portaria": "2025-10-07",
      "nota_atualizacao": null,
      "url_pdf": "https://www.gov.br/conitec/pt-br/midias/protocolos/pcdt_acidentes_ofidicos_final.pdf/@@display-file/file",
      "url_resumido": "https://www.gov.br/conitec/pt-br/midias/protocolos/2026/pcdt-resumido/pcdt-resumido-acidentes-ofidicos/@@display-file/file",
      "vigente": true,
      "secoes_disponiveis": ["introducao", "diagnostico", "classificacao", "monitoramento", "tratamento"],
      "texto_completo_disponivel": true,
      "extracao_incompleta": false,
      "origem": "nome"
    }
  ],
  "aviso": null
}

status vem do CSV de dados abertos do Ministério da Saúde e é parcial: em 24/09/2026, só 43 dos 132 PCDTs da listagem tinham status, porque boa parte dos nomes do CSV não existe na tabela do portal. status: null não quer dizer que o protocolo não está aprovado; a listagem da Conitec só traz PCDTs vigentes.

resumir_conduta(pcdt_id: str, contexto_clinico: str)

Extrai do protocolo a parte que responde ao contexto, em vez de devolver o documento inteiro. Aceita o identificador de consultar_protocolo ou o nome da condição sem a nota de revisão (por exemplo, asma). Precisa do LLM local e do texto completo já coletado; sem um dos dois, devolve só o link do PDF e um aviso dizendo o que faltou. No modo connector o LLM nunca é chamado e a resposta vem sempre com resumo: null (ver abaixo).

{
  "condicao": "Acidentes Ofídicos",
  "resumo": {
    "resumo": "O paciente deve receber soroterapia antiveneno específica para o tipo de envenenamento.",
    "secao_origem": "1.3. Acesso a soroterapia antiveneno",
    "citacao_literal": "é necessário utilizar a soroterapia antiveneno específica, correspondente ao tipo de envenenamento",
    "citacao_confere": true,
    "fracao_citacao_verificada": 1.0
  },
  "url_pdf": "https://www.gov.br/conitec/..."
}

A citação é conferida, não só pedida

O prompt exige a citação literal do trecho que sustenta o resumo. Um modelo pequeno às vezes "cita" parafraseando, ou, pior, costura frases reais de partes diferentes do documento num único bloco de aspas. Então o código confere:

Campo	O que significa
citacao_confere	a citação existe inteira e contígua no protocolo
fracao_citacao_verificada	quanto dela existe, frase a frase (0 a 1)

Fração alta com citacao_confere: false é o caso mais traiçoeiro: parece legítimo na leitura e não é. Marcadores de omissão ("[...]", "(...)", reticências) nas pontas da citação são ignorados; no meio, significam que algo foi pulado, e a citação deixa de contar como contígua. Isso aconteceu no primeiro teste real deste projeto, com o PCDT de Acidentes Ofídicos, e é por isso que os dois campos existem.

Modo connector (servidor HTTP)

Por padrão o servidor fala stdio: o cliente sobe o processo na máquina de quem usa. Com TRANSPORTE=streamable-http, ele vira um servidor alcançável pela rede, que é o que o Claude aceita como custom connector.

TRANSPORTE=streamable-http HTTP_PORTA=8000 uv run protocolos-pcdt-mcp

Variável	Padrão	Observação
TRANSPORTE	stdio	streamable-http liga o modo connector
HTTP_HOST / HTTP_PORTA / HTTP_PATH	127.0.0.1 / 8000 / /mcp
HTTP_STATELESS	true	cada requisição independente; escala melhor
HTTP_LIMITE_GLOBAL_POR_MINUTO	1200	o teto que protege a máquina
HTTP_LIMITE_POR_MINUTO	600	por origem, contra chamada direta
HTTP_HOSTS_PUBLICOS	vazio	nomes públicos aceitos no Host, separados por vírgula

Por que dois limites. Quando o Claude chama um connector remoto, as requisições chegam dos IPs da Anthropic, não do usuário final. Limitar só por IP colocaria todos os usuários no mesmo balde: ou derruba todo mundo junto, ou não protege nada. O teto global é o que vale para esse tráfego; o por origem serve contra quem chama o servidor direto. X-Forwarded-For só é considerado quando a conexão vem do loopback (o proxy local), e vale a entrada mais à direita, a que o proxy acrescentou.

No modo connector, resumir_conduta não resume

O servidor HTTP não chama o LLM. Resumir sob demanda faria quem hospeda pagar inferência para qualquer pessoa que chame o connector. Não existe cache de resumos neste projeto (cada resumo depende do contexto clínico perguntado), então, nesse modo, a tool devolve o identificador, a condição, o link do PDF, resumo: null e um aviso dizendo que nenhum resumo foi gerado. Nada é inventado no lugar. consultar_protocolo funciona igual nos dois modos.

Atrás de um proxy ou túnel, declare o nome público

O SDK do MCP valida o cabeçalho Host e responde 421 Invalid Host ao que não reconhece. É proteção contra DNS rebinding, um ataque em que um site qualquer faz o navegador da vítima conversar com um servidor que só deveria ser local. Atrás de um túnel, o Host que chega é o nome público, então ele precisa ser declarado:

HTTP_HOSTS_PUBLICOS=mcp.exemplo.ts.net

O loopback continua valendo junto, porque é assim que se testa o servidor de dentro da máquina.

Rodar como serviço

deploy/systemd/protocolos-pcdt-connector.service é a unit de usuário do servidor HTTP. Ela escuta só em 127.0.0.1:8104; expor para fora é uma camada à parte (proxy reverso com TLS ou túnel) que aponta para essa porta. Ajuste HTTP_HOSTS_PUBLICOS para o seu nome público antes de habilitar.

cp deploy/systemd/protocolos-pcdt-connector.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now protocolos-pcdt-connector.service

O sync não interrompe quem está lendo

pcdt-cli sync --publicar constrói a base nova ao lado e troca as duas por rename no fim. O servidor abre a base somente para leitura a cada requisição; quem já abriu continua no arquivo antigo até fechar, e quem abrir depois pega o novo. É o modo que o timer usa, e por dois motivos.

O primeiro é a concorrência: o DuckDB não aceita leitor e escritor de processos diferentes ao mesmo tempo. Sem a troca, as consultas durante a coleta (até uma hora, com os downloads de PDF) recebiam o aviso de base travada em vez de resultado, e um sync que começasse no instante de uma consulta falhava.

O segundo é o tamanho. O DuckDB não devolve o espaço das páginas antigas, e a coleta reescreve o texto completo dos protocolos todo dia: em 11/10/2026, depois de semanas de syncs diários, o arquivo estava em 1.062 MB para 132 protocolos, contra 49 MB compactado. A base nova é clonada da servida com COPY FROM DATABASE, e a cópia já sai compactada.

Sem --publicar, o sync grava direto em DUCKDB_PATH, que é o que se quer num teste rápido com --max-pdfs. A troca recusa publicar uma base que encolheu mais de 10% em número de protocolos, para coleta interrompida não substituir a base boa em silêncio; quando a queda é real, --forcar publica.

Limitações conhecidas

Conferir a citação não pega erro de interpretação. Num teste com "paciente picado por cascavel", o modelo local devolveu uma citação real e contígua do protocolo e mesmo assim classificou o caso como envenenamento botrópico, quando cascavel é crotálico. A citação estava certa; o raciocínio em cima dela, errado. Esta é a limitação mais importante do projeto.

O protocolo é truncado antes de ir para o modelo. Protocolos passam de 200 mil caracteres; o recorte prioriza a vizinhança das palavras do contexto perguntado, mas pode cortar fora a parte relevante.

A segmentação por seções é heurística. A estrutura dos PCDTs varia entre protocolos antigos e novos. Quando os títulos não são reconhecíveis, secoes_disponiveis vem vazio e só o texto corrido fica disponível, de propósito, para não inventar estrutura.

A base começa quase vazia. Por causa do teto de PDFs por execução, os primeiros syncs trazem a listagem completa mas pouco texto. texto_completo_disponivel diz quais já têm. Na instância do mantenedor, em 24/09/2026, eram 64 de 132 com texto; no ritmo de 20 PDFs por noite, a base deve completar em cerca de 4 syncs (estimativa). Até lá, PCDTs como hipertensão arterial sistêmica e os de HIV aparecem na consulta, mas resumir_conduta responde que o texto ainda não foi coletado. pcdt-cli schema mostra a contagem.

Quando o PCDT muda, o texto antigo é descartado. Se a URL do PDF, a data da portaria ou a nota de revisão mudarem, o sync reextrai o texto, com prioridade na cota da noite. Se não couber na cota, ou se o download falhar, o protocolo fica sem texto até um sync conseguir baixar o PDF novo, em vez de resumir a versão velha com o link da nova. Quando só a nota ou a portaria mudam e a URL continua a mesma, o PDF velho sai do cache em disco na hora, para não ser reextraído depois.

O status é parcial. Ver a seção de consultar_protocolo.

A busca no texto é um último recurso. Ela acha protocolos que citam o termo, não o PCDT da condição. Siglas fora da lista de nomes.py também caem nela.

Listagem parcial não despromove ninguém. Se a listagem do portal trouxer menos de 80% dos PCDTs vigentes na base, o sync não tira ninguém de vigente e deixa um aviso no journal.

PDFs digitalizados não têm camada de texto. Nesses casos o registro fica com extracao_incompleta: true e só os metadados.

As URLs das fontes podem mudar. Estão em coleta/listagem.py, confirmadas em 20/09/2026. Observação prática: os links .csv que o portal de dados abertos exibe estão desatualizados e devolvem 403; os que funcionam terminam em .zip.

Privacidade

• Sai da máquina: requisições ao gov.br/conitec e ao bucket de dados abertos do Ministério da Saúde, para a listagem e os PDFs públicos.
• Não sai: a condição e o contexto clínico que você consulta ficam entre a base local e o seu LLM local.
• Sem telemetria, sem analytics.
• No modo connector, o que você consulta passa pela máquina que hospeda o servidor (e pelo túnel ou proxy na frente dela). O contexto clínico não vai para LLM nenhum, porque nesse modo o LLM não é chamado.

Atenção: o contexto_clinico que você digita vai para o seu LLM. Se ele estiver hospedado fora da sua máquina, o texto vai junto, este projeto não impede isso, ao contrário do revisor-notas-mcp.

Atualizando de uma base anterior

A versão 0.1.0 tira a nota de revisão do identificador e cria a coluna nota_atualizacao. A migração roda no próximo pcdt-cli sync (ou em qualquer abertura da base para escrita, como pcdt-cli schema), preserva o texto já extraído e refaz o índice FTS. Até lá, o servidor continua lendo a base antiga: os identificadores aparecem com a nota, e resumir_conduta aceita o nome sem ela.

Segurança

Ver SECURITY.md. Mudanças por versão em CHANGELOG.md.

Contribuindo

Veja CONTRIBUTING.md. Não rode a coleta em loop contra o portal.

Licença e atribuição

Apache License 2.0: escolhida por o projeto tocar em conduta clínica.

Construído no contexto do IA.med.