conformidade-pbtr-mcp

Automated compliance analysis of Basic Projects and Terms of Reference (MCP server, pt-BR).

An MCP server that analyzes Basic Projects (PB) and Terms of Reference (TR) against the SERPRO review roadmap. You upload the PDF and say "run a compliance analysis of the PB"; the server returns the compliance index, prioritized pending items, and the reports in DOCX, XLSX, PDF, Markdown, and JSON.

A project by SERPRO — Brazil's Federal Data Processing Service.

What is checked

The checklist rules are conditional. The server infers the procurement context — bidding, direct contracting, non-competitive contracting, service, good, consulting, training, tickets, subscription, RP, hardware/currency, term longer than 60 months — and applies only the relevant branches of the roadmap. The rest are shown as Not applicable, with the reason explained. Without it, a hardware PB would flood its dozens of false "not compliant" warnings for not carrying the mandatory consulting requirements.

Five statuses, not two

Conforming / non-conforming would not be enough: several roadmap items require human heuristic judgment ("check whether there is coherence between them"). The report therefore uses:

Related MCP server: Tri-Tender Pricing MCP

How the Portuguese review works

The text is reviewed by the model that called the MCP — it already has the document in context, so it doesn't make sense for the server to open a second conversation with another model just to re-read the same text. The server handles deterministic mapping and returns the segmented text for the agent to read.

That's why the flow is three steps, which the agent can chain itself:

1. analisar_conformidade      → checklist, numeração, tabelas, valores
                                 (+ regras determinísticas de revisão)
2. obter_texto_para_revisao   → o agente lê e revisa o português
3. registrar_revisao_textual  → apontamentos entram e os relatórios saem

Each agent finding only enters the report if the quoted excerpt literally exists in the document. The check is done against the extracted text, tolerating differences in spacing and quotes. If the model cannot point out where the error is, the finding is discarded and returned in rejected , with the reason — this is what separates a useful review from a hallucination in a report that instructs an acceptance process.

Every finding cites the PB/TR item ("item 6.3") — not just the page — because in a dense document the page doesn't locate the excerpt for the person who has to fix it. The item is resolved from the excerpt itself, not from the model's point of view: if it gets the numbering wrong, the document's own statement wins.

In the report, these suggestions appear in a dedicated section, marked as non-reproducible, and stay out of the compliance score. Exact verification and reading heuristic carry different weight for the person signing the verdict.

Installation

System requirements: Python 3.11+. No Java dependency and no external services.

git clone https://github.com/charlesmmorais/conformidade-pbtr-mcp.git
cd conformidade-pbtr-mcp
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

Register in Claude Desktop / Claude Code (claude_desktop_config.json):

{
  "mcpServers": {
    "conformidade-pbtr": {
      "command": "/caminho/para/conformidade-pbtr-mcp/.venv/bin/conformidade-pbtr",
      "env": {
        "CONFORMIDADE_PBTR_SAIDA": "/caminho/onde/gravar/os/relatorios"
      }
    }
  }
}

Hosted deploy (Fly.io)

The server runs stdio locally and HTTP when hosted. The repository ships with Dockerfile and fly.toml ready to use:

fly launch --no-deploy --copy-config
fly deploy
curl https://<sua-app>.fly.dev/health

In hosted mode the client does not share a disk with the server: the PDF is uploaded in conteudo_base64 and the reports come back embedded in the response. Read docs/DEPLOY.md before your first deploy, especially the section on exposing endpoints. The image is 250 MB and runs in 512 MB.

Tools exposed

Main flow:

Support:

Prompt conduzir_analise_conformidade: takes the agent through the analysis — including the order of findings presentation and the instruction to not assert compliance unless the analysis has actually classified it as compliant.

Direct use (without MCP)

from conformidade_pbtr import analisar
from conformidade_pbtr.relatorios import gerar_docx

rel = analisar("PB_123_2026.pdf", tipo="PB")
print(rel.resumo.indice_conformidade)
gerar_docx(rel, "Relatorio_Conformidade.docx")

Compliance index

Weighted average by severity (critical 4, high 3, medium 2) over the items that can be assessed automatically. Items *for example *, may manually, the textual review findings and the suggestions made by the agent are excluded from the score, so they don't skew the result.

Pluggable checklist

All regulatory knowledge lives in recursos/checklist_roteiro_ti.yaml — the engine itself does not care. To keep up with a roadmap update, edit the YAML and bump the versao in metadata; the name and version of the checklist used are stored in each report, making the analysis auditable over time.

The project serves SERPRO today. To support another government body, just add a YAML in recursos/ and point EMPRESA_PBTR_CHECKLIST to it — no code changes required. The format is in docs/CHECKLIST.md.

Known limitations

• Aba Itens — the check between the Items tab in the system and the quantities in the PB is not possible from the PDF. The item always shows as far as check manually*.

• Scanned PDF — without a text layer there is no analysis. extrair_estrutura flags that case; apply OCR first.

• Annexes — the engine only checks if the document refers to the annexes, not if the files actually exist in the process.

• Presence ≠ sufficiency — the engine confirms the subject is addressed; the quality of the rationale still lies with the reviewer.

Documentation

• docs/MANUAL.md — micro manual for analysts

• docs/ARQUITETURA.md — design decisions, data model and roadmap

• docs/CHECKLIST.md — YAML structure and how to write good triggers

• docs/DEPLOY.md — Fly.io deployment, remote mode and environment variables

• CONTRIBUTING.md — how to contribute

Development

pip install -e ".[dev]"
pytest -q          # testes sobre um PB sintético com erros plantados
ruff check .

The test PB is generated by exemplos/gerar_pb_teste.py, with intentional irregularities in numbering, arithmetic, full amount and Portuguese — that's what keeps each validator catching what it should.

License

MIT — Copyright (c) 2026 SERPRO.