abnt-mcp 0.2.0__tar.gz

abnt_mcp-0.2.0/.gitignore

@@ -0,0 +1,55 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE & OS
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Compilation artifacts
+*.aux
+*.bbl
+*.blg
+*.log
+*.out
+*.toc
+*.synctex.gz
+*.pdf

abnt_mcp-0.2.0/AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md — Diretrizes Operacionais e Governança SDD para Agentes de IA
+
+> **Atenção Agente Autônomo (Antigravity, Claude Code, Cursor, GitHub Copilot, Codex):**
+> Este repositório opera estritamente sob o paradigma **Spec-Driven Development (SDD — Desenvolvimento Orientado a Especificações)**. Toda e qualquer proposta de alteração, refatoração, correção normativa ou nova funcionalidade **DEVE obrigatoriamente atualizar ou criar as especificações em `specs/` antes ou simultaneamente à modificação do código-fonte**.
+
+---
+
+## 1. Regra de Ouro: Sincronização Obrigatória de Specs (`Spec-Sync`)
+
+1. **`specs/` é a Fonte Única da Verdade:**
+   - `specs/01-normative-catalog.spec.md`: Catálogo de regras normativas ABNT e IBGE (`NORMATIVE_RULES` em `src/abnt_mcp/config.py`).
+   - `specs/02-research-spec-schema.spec.md`: Contrato do manifesto `abnt.spec.json` e `SPEC.md` (`ResearchSpec` em `src/abnt_mcp/models.py`).
+   - `specs/03-mcp-tools-contract.spec.md`: Contrato formal de todas as `@mcp.tool`, `@mcp.prompt` e `@mcp.resource` expostas em `src/abnt_mcp/server.py`.
+2. **Proibição de Drift (Desvio entre Spec e Código):**
+   - **Ao propor uma alteração (Plano/RFC):** Sempre inclua no plano quais arquivos de `specs/` serão atualizados e quais IDs de regra (`NBRXXXX-RXX`) serão criados ou modificados.
+   - **Ao implementar uma alteração:** Atualize `specs/` em sincronia estrita com `src/abnt_mcp/`.
+   - **Trava Automatizada de CI/CD:** A suíte `tests/test_sdd.py` possui testes anti-drift (`test_sdd_anti_drift_normative_rules` e `test_sdd_anti_drift_mcp_surface`) que falham imediatamente caso qualquer regra em `NORMATIVE_RULES` ou qualquer interface em `server.py` não esteja documentada em `specs/`.
+
+---
+
+## 2. Fluxo de Trabalho Obrigatório em 4 Etapas
+
+Sempre que receber uma tarefa neste repositório, execute rigorosamente esta sequência:
+
+1. **Etapa 1 — Especificar (`specs/`):**
+   - Consulte e atualize o arquivo correspondente em `specs/` (`01-normative-catalog.spec.md`, `02-research-spec-schema.spec.md` ou `03-mcp-tools-contract.spec.md`).
+2. **Etapa 2 — Tipar e Catalogar (`config.py` & `models.py`):**
+   - Registre ou atualize o identificador canônico em `NORMATIVE_RULES` (`src/abnt_mcp/config.py`) e os modelos Pydantic em `src/abnt_mcp/models.py`.
+3. **Etapa 3 — Implementar nos Pilares e Servidor (`pillars/`, `parsers/`, `server.py`):**
+   - Implemente a lógica mantendo a separação modular dos 4 pilares + motor SDD (`diagnostics.py`, `writing.py`, `compiler.py`, `advisory.py`, `spec.py`).
+4. **Etapa 4 — Verificar com Testes Rastreáveis e Registrar no `CHANGELOG.md` (`tests/` & `CHANGELOG.md`):**
+   - Registre obrigatoriamente a alteração em `CHANGELOG.md` (sob `## [Unreleased]` ou na seção da versão sendo lançada). A esteira de CI falha automaticamente em Pull Requests que alterem `src/`, `specs/` ou `pyproject.toml` sem atualizar `CHANGELOG.md`.
+   - Adicione testes cobrindo a nova cláusula/funcionalidade e execute:
+     ```bash
+     uv run pytest -v --cov=abnt_mcp --cov-report=term-missing
+     ```
+
+---
+
+## 3. Invariantes Normativas Inegociáveis (ABNT & IBGE)
+
+Jamais gere código, templates, prompts ou testes que violem estas regras vigentes:
+
+- **`NBR10520-R01` (ABNT NBR 10520:2023):** Autores citados **dentro de parênteses** utilizam exclusivamente **caixa mista** `(Silva, 2023)` ou `(Silva; Santos, 2023)`. O padrão antigo em CAIXA ALTA `(SILVA, 2023)` da norma revogada de 2002 é estritamente proibido.
+- **`NBR10520-R03` (ABNT NBR 10520:2023):** Citações diretas curtas (até 3 linhas) ficam no parágrafo entre aspas duplas com o ponto final **após** os parênteses; citações diretas longas (> 3 linhas) usam recuo de 4 cm, fonte 10, espaçamento simples e **sem aspas**.
+- **`NBR14724-R02` (ABNT NBR 14724:2011, item 5.3):** A Capa não é contada; a contagem sequencial inicia na Folha de Rosto; nenhum elemento pré-textual pode exibir número de página impresso; a numeração arábica aparece apenas a partir da Introdução, no canto superior direito.
+- **`NBR6022-R01` (ABNT NBR 6022:2018):** Artigos científicos periódicos não exigem capa, folha de rosto nem sumário.
+- **`NBR6023-R01` & `NBR6023-R02` (ABNT NBR 6023:2018):** Referências alinhadas exclusivamente à margem esquerda; destaque tipográfico (negrito ou itálico) aplicado **apenas ao título principal** (nunca ao subtítulo); mês de maio grafado por extenso (`maio`, nunca `mai.`).
+- **`NBR6024-R01` (ABNT NBR 6024:2012):** Não há ponto final após o indicativo numérico de seção (`1.1 Metodologia` e nunca `1.1. Metodologia`).
+- **`IBGE1993-R01` (Normas Tabulares IBGE, 1993):** **Tabelas** (dados quantitativos) têm bordas laterais esquerda e direita **abertas**; **Quadros** (dados conceituais/textuais) têm todas as bordas **fechadas**.
+
+---
+
+## 4. Padrão de Commits, Branches, Pull Requests e Releases (`uvx` / SemVer)
+
+- **Branches:** `spec/<escopo>`, `feat/<escopo>`, `fix/<rule-id>`, `docs/<escopo>`, `test/<escopo>`, `chore/<escopo>`.
+- **Commits Semânticos:**
+  - `spec(nbr10520): adicionar cláusula NBR10520-R04 ao catálogo`
+  - `feat(spec): implementar auditoria de objetivos específicos em abnt.spec.json`
+  - `fix(NBR14724-R02): corrigir detecção de paginação em elementos pré-textuais`
+- **Pull Requests:** Preencha integralmente o template `.github/PULL_REQUEST_TEMPLATE.md`, preenchendo a tabela de rastreabilidade (`Spec Atualizada` -> `Rule ID / Tool` -> `Teste`) e confirmando a atualização do `CHANGELOG.md`.
+- **Releases e Privacidade de Metadados (`pyproject.toml` & `CHANGELOG.md`):**
+  - **Paridade de Versão:** A versão em `pyproject.toml`, `src/abnt_mcp/__init__.py` (`__version__`) e a última seção versionada em `CHANGELOG.md` (`## [X.Y.Z]`) devem estar estritamente sincronizadas.
+  - **Privacidade PEP 621:** Jamais adicione chaves `email` em `authors` no `pyproject.toml` (prevenção contra scrapers de spam no PyPI). Utilize exclusivamente `[project.urls]` apontando para o GitHub.

abnt_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+Todas as alterações relevantes, evoluções normativas (ABNT/IBGE) e novas interfaces MCP deste projeto são obrigatoriamente documentadas neste arquivo.
+
+O formato baseia-se em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/) e este projeto adere ao [Versionamento Semântico (SemVer)](https://semver.org/lang/pt-BR/) governado por **Desenvolvimento Orientado a Especificações (*Spec-Driven Development* — SDD)**.
+
+> **Regra de Governança SDD:** Nenhuma alteração em `src/` ou `specs/` pode ser mesclada à `main` sem o respectivo registro neste `CHANGELOG.md`. O teste automatizado `test_sdd_release_version_changelog_and_privacy_invariants` em `tests/test_sdd.py` e a pipeline de CI validam esta paridade.
+
+---
+
+## [Unreleased]
+
+### Adicionado
+- Padronização automatizada de Releases (`.github/workflows/release.yml` e `.github/release.yml`) com validação de paridade de versão, build `uv build`, teste de fumaça `uvx` e publicação via PyPI Trusted Publishing (OIDC).
+- Trava automatizada de integridade de versão, `CHANGELOG.md` e privacidade de metadados PEP 621 (`test_sdd_release_version_changelog_and_privacy_invariants` em `tests/test_sdd.py`).
+
+---
+
+## [0.2.0] - 2026-10-24
+
+### Adicionado
+- **Arquitetura Spec-Driven Development (`PR #1`):**
+  - Diretório `specs/` contendo a Fonte Única da Verdade: `01-normative-catalog.spec.md` (13 cláusulas canônicas `NORMATIVE_RULES`), `02-research-spec-schema.spec.md` (`ResearchSpec` em 3 camadas) e `03-mcp-tools-contract.spec.md`.
+  - Motor SDD (`src/abnt_mcp/pillars/spec.py`) com geração e leitura de `abnt.spec.json` e `SPEC.md`.
+  - Ferramentas MCP `init_research_spec`, `audit_research_spec` e `simulate_banca`, além dos recursos `abnt://guia/sdd` e `abnt://template/spec`.
+  - Suporte nativo ao perfil de Artigos Científicos Periódicos segundo a **ABNT NBR 6022:2018** (`NBR6022-R01`).
+  - Documentos de governança técnica e instruções para agentes de IA: `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `.github/PULL_REQUEST_TEMPLATE.md` e templates estruturados em `.github/ISSUE_TEMPLATE/`.
+- **Segurança de I/O, Ano Dinâmico e Backup de `.bib` (`PR #2`):**
+  - Utilitários `get_current_year()`, `get_default_author_source()` e `validate_safe_path()` (prevenção de *Path Traversal*) em `src/abnt_mcp/config.py`.
+  - Criação automática de backup em `.abnt-mcp/backups/<nome>.bib.bak` antes de higienizar arquivos BibTeX em `clean_bibtex_file`.
+- **Modelo Unificado de Diagnóstico (`PR #3`):**
+  - Modelo `DiagnosticItem` em `src/abnt_mcp/models.py` diferenciando regras normativas (`nature="normative"`, `human_review_required=False`), diretrizes institucionais (`nature="institutional"`) e heurísticas editoriais (`nature="heuristic"`, `human_review_required=True`).
+- **Scaffolding de Projetos e Aprendizado de Padrão/Logo Institucional via PDF (`PR #4`):**
+  - Ferramenta MCP `scaffold_academic_project` para inicialização completa de projetos em `typst`, `latex` e `markdown` com proteção `overwrite=False`.
+  - Extrator `extract_institutional_pattern_from_pdf` em `src/abnt_mcp/parsers/pdf_reader.py` capaz de aprender cabeçalho da capa, preâmbulo, orientador, elementos pré-textuais exigidos, rótulo de conclusão e extrair automaticamente o brasão/logotipo (`/XObject /Image`) da Capa (Página 1) para `figuras/logo_instituicao.png` usando apenas a biblioteca padrão.
+- **Auditoria de Figuras, Tabelas e Quadros (`PR #5`):**
+  - Ferramenta MCP `audit_illustrations_and_tables` (`audit_project_illustrations_and_tables` em `src/abnt_mcp/pillars/diagnostics.py`) validando chamada prévia no texto (`NBR14724-R03`), presença obrigatória de `Fonte:` (`NBR14724-R03`), existência física de imagens, sequência numérica e distinção conceitual entre `Tabela` e `Quadro` (`IBGE1993-R01`).
+- **Auditoria SDD Integrada, Prontidão de Entrega e Relatórios Persistentes (`PR #6`):**
+  - Evolução de `audit_research_spec` com indicador `submission_readiness` (`"READY"`, `"READY_WITH_WARNINGS"`, `"NOT_READY"`), validação das regras institucionais (`INST-PROFILE-*`) e geração automática de `.abnt-mcp/last-audit.json` e `.abnt-mcp/relatorio-conformidade.md`.
+
+### Alterado
+- Substituição de anos fixos (`"2026"`) em `format_figure` e `format_table` por obtenção dinâmica do ano corrente (`get_current_year()`).
+- Remoção de campo de e-mail pessoal em `authors` no `pyproject.toml` (prevenção de spam conforme PEP 621) e adição de links oficiais em `[project.urls]`.
+
+---
+
+## [0.1.0] - 2026-10-24
+
+### Adicionado
+- Lançamento fundacional do servidor FastMCP `abnt-mcp` estruturado em 4 pilares (`diagnostics`, `writing`, `compiler`, `advisory`).
+- Validação estrutural ABNT NBR 14724:2011 e auditoria forense de paginação em PDF (`audit_pdf_pagination`).
+- Formatação e validação de citações conforme ABNT NBR 10520:2023 (autoria em caixa mista entre parênteses) e referências conforme ABNT NBR 6023:2018.
+- Compilação multi-engine (`typst` nativo em Rust, `pdflatex`/`latexmk` com `abnTeX2` e `pandoc`).
+- Integração com APIs científicas abertas Crossref, SciELO e resolução de BibTeX por DOI.

abnt_mcp-0.2.0/CLAUDE.md

@@ -0,0 +1,46 @@
+# CLAUDE.md — Guia de Engenharia SDD e Contexto Rápido do Repositório
+
+Este projeto (**ABNT Copilot MCP** — `abnt-mcp`) segue **Spec-Driven Development (SDD)**.
+Leia integralmente as diretrizes em [AGENTS.md](AGENTS.md) e as especificações em `specs/` antes de propor ou executar qualquer alteração.
+
+---
+
+## 1. Diretriz Mandatória para Propostas e Alterações
+
+> **IMPORTANTE:** Sempre que você (Claude / Agente de IA) formular uma proposta de mudança arquitetural, alteração de regra ABNT/IBGE ou criação/modificação de tool MCP, **você deve obrigatoriamente propor e aplicar a atualização correspondente nos arquivos dentro de `specs/`**.
+
+- Mudança ou adição de regra normativa ABNT/IBGE -> Atualizar `specs/01-normative-catalog.spec.md` + `NORMATIVE_RULES` em `src/abnt_mcp/config.py`.
+- Mudança no manifesto `abnt.spec.json` / `SPEC.md` -> Atualizar `specs/02-research-spec-schema.spec.md` + `src/abnt_mcp/models.py` + `src/abnt_mcp/pillars/spec.py`.
+- Mudança em `@mcp.tool`, `@mcp.prompt` ou `@mcp.resource` -> Atualizar `specs/03-mcp-tools-contract.spec.md` + `src/abnt_mcp/server.py`.
+- Toda alteração em `src/`, `specs/` ou `pyproject.toml` -> Registrar obrigatoriamente em `CHANGELOG.md` (sob `## [Unreleased]` ou na seção da versão). Jamais inclua campo `email` em `authors` no `pyproject.toml`.
+
+---
+
+## 2. Comandos Essenciais de Desenvolvimento
+
+```bash
+# Instalar dependências de desenvolvimento
+uv sync --extra dev
+
+# Executar suíte completa de testes (incluindo trava anti-drift SDD) e cobertura
+uv run pytest -v --cov=abnt_mcp --cov-report=term-missing
+
+# Verificar execução da CLI do servidor MCP
+uv run abnt-mcp --help
+```
+
+---
+
+## 3. Mapa de Arquitetura
+
+- `specs/`: Especificações canônicas (Catálogo Normativo, Schema SDD e Contrato de Interfaces MCP).
+- `src/abnt_mcp/config.py`: `NORMATIVE_RULES` (IDs canônicos `NBRXXXX-RXX`), regexes normativas, meses ABNT (`maio` sem ponto) e léxico de impessoalidade.
+- `src/abnt_mcp/models.py`: Modelos Pydantic de entrada, saída e `ResearchSpec` (3 camadas).
+- `src/abnt_mcp/pillars/`:
+  - `diagnostics.py`: Pilar 1 — Validação estrutural (`ABNT_14724` e `ABNT_6022`), auditoria `.bib` e tom científico.
+  - `writing.py`: Pilar 2 — Citações NBR 10520:2023, referências NBR 6023:2018, figuras, tabelas IBGE e resumos NBR 6028.
+  - `compiler.py`: Pilar 3 — Compilação nativa via Rust `typst`, `pdflatex`/`latexmk` (`abnTeX2`) e `pandoc`.
+  - `advisory.py`: Pilar 4 — Crossref, SciELO, BibTeX por DOI e Simulador de Banca Examinadora integrado ao SDD.
+  - `spec.py`: Motor SDD — Inicialização, parsing e auditoria de `abnt.spec.json` e `SPEC.md`.
+- `src/abnt_mcp/server.py`: Servidor FastMCP expondo 18 tools, 3 prompts e 8 resources.
+- `CHANGELOG.md`: Registro histórico canônico de todas as versões e alterações SDD.

abnt_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,121 @@
+# Protocolo Técnico-Científico de Colaboração e Governança SDD (`CONTRIBUTING.md`)
+
+**Diretrizes Formais para Engenharia Orientada a Especificações, Conformidade Normativa (ABNT/IBGE) e Submissão de Contribuições ao `abnt-mcp`**
+
+---
+
+## 1. Fundamentação e Paradigma de Engenharia
+
+O **ABNT Copilot MCP** (`abnt-mcp`) constitui uma infraestrutura programática de validação, formatação e compilação documental submetida ao rigor estrito das normas técnicas brasileiras emanadas pela **Associação Brasileira de Normas Técnicas (ABNT)** e pelo **Instituto Brasileiro de Geografia e Estatística (IBGE)**.
+
+Diferentemente de projetos de software convencionais nos quais os requisitos são informais ou mutáveis, neste ecossistema **a especificação normativa precede a implementação**. Por essa razão, o repositório adota formalmente a metodologia de **Desenvolvimento Orientado a Especificações (*Spec-Driven Development* — SDD)** tanto para colaboradores humanos quanto para agentes autônomos de Inteligência Artificial (conforme regido em [AGENTS.md](AGENTS.md) e [CLAUDE.md](CLAUDE.md)).
+
+---
+
+## 2. Ciclo de Vida SDD (*Spec-First Workflow*)
+
+Nenhuma modificação de comportamento normativo, esquema de dados ou superfície de protocolo MCP pode ser introduzida diretamente no código-fonte sem antes percorrer as quatro etapas do ciclo SDD:
+
+```text
+[1. Especificação em specs/] ──► [2. Catálogo & Schema (config/models)] ──► [3. Implementação no Pilar/Server] ──► [4. Teste Anti-Drift & Cobertura]
+```
+
+### 2.1. Etapa 1: Atualização da Especificação (`specs/`)
+Toda proposta de alteração ou implementação deve iniciar pela edição (ou adição) do contrato correspondente no diretório `specs/`:
+- **Regras da ABNT ou do IBGE:** Documentar a cláusula em `specs/01-normative-catalog.spec.md`, atribuindo um identificador canônico único no formato `<NORMA>-R<NN>` (ex.: `NBR10520-R01`, `NBR14724-R02`, `IBGE1993-R01`), acompanhado do ano de vigência e seção/item oficial da norma.
+- **Manifesto Científico do Pesquisador (`abnt.spec.json`):** Documentar alterações nas 3 camadas do schema em `specs/02-research-spec-schema.spec.md`.
+- **Superfície do Protocolo FastMCP:** Documentar qualquer nova `@mcp.tool`, `@mcp.prompt` ou `@mcp.resource` (ou alteração de assinatura) em `specs/03-mcp-tools-contract.spec.md`.
+
+### 2.2. Etapa 2: Sincronização de Catálogo e Tipagem (`config.py` e `models.py`)
+- Registrar o identificador canônico no dicionário `NORMATIVE_RULES` em `src/abnt_mcp/config.py`.
+- Declarar ou atualizar os esquemas de validação estrita com `pydantic>=2.0` em `src/abnt_mcp/models.py`.
+
+### 2.3. Etapa 3: Implementação Modular nos Pilares (`src/abnt_mcp/pillars/`)
+A arquitetura deve preservar o desacoplamento entre responsabilidades:
+- `pillars/diagnostics.py`: Auditoria estrutural (NBR 14724 e NBR 6022), consistência cruzada `.bib` e análise de impessoalidade/tom científico.
+- `pillars/writing.py`: Geração e formatação normativa (NBR 10520:2023, NBR 6023:2018, NBR 6028:2021, ilustrações e tabelas IBGE).
+- `pillars/compiler.py`: Compilação multi-engine (`typst` nativo em Rust, `pdflatex`/`latexmk` com `abnTeX2` e `pandoc`).
+- `pillars/advisory.py`: Integração com APIs científicas (Crossref, SciELO, `doi.org`) e Simulador de Banca Examinadora.
+- `pillars/spec.py`: Motor de Escrita Acadêmica Orientada a Especificação (`abnt.spec.json` / `SPEC.md`).
+
+### 2.4. Etapa 4: Verificação Automatizada e Trava Anti-Drift (`tests/`)
+O repositório possui uma trava automatizada em `tests/test_sdd.py` que verifica em tempo de execução se todas as regras declaradas em `NORMATIVE_RULES` e todas as interfaces registradas em `server.py` estão presentes nos arquivos de `specs/`. Caso uma contribuição modifique o código sem atualizar `specs/`, a esteira de integração contínua (**GitHub Actions CI/CD**) rejeitará a submissão automaticamente.
+
+---
+
+## 3. Padrão Geral de Branches, Commits e Pull Requests
+
+### 3.1. Convenção de Nomenclatura de *Branches*
+Utilize prefixos semânticos alinhados à natureza da intervenção:
+- `spec/<escopo>`: Criação ou revisão de especificações formais em `specs/` (ex.: `spec/nbr-6022-artigos`).
+- `feat/<pilar-ou-norma>`: Implementação de novas ferramentas ou regras especificadas (ex.: `feat/sdd-audit-engine`).
+- `fix/<rule-id-ou-modulo>`: Correção de desvio normativo ou falha técnica (ex.: `fix/NBR14724-R02-pagination`).
+- `docs/<escopo>`: Evolução de documentação técnica ou acadêmica (ex.: `docs/contributing-protocol`).
+- `test/<escopo>`: Ampliação da cobertura de testes e casos de borda (ex.: `test/ibge-tabular-edges`).
+
+### 3.2. Padrão de Mensagens de *Commit* (*Conventional Commits*)
+As mensagens de *commit* devem ser redigidas de forma imperativa, clara e referenciar o escopo ou ID canônico:
+
+```text
+<tipo>(<escopo>): <descrição concisa e técnica>
+
+[Corpo opcional detalhando a cláusula da NBR/IBGE e os arquivos de specs/ atualizados]
+```
+
+**Tipos admitidos:**
+- `spec`: Alteração nas especificações canônicas dentro de `specs/`.
+- `feat`: Nova funcionalidade ou regra normativa respaldada por spec.
+- `fix`: Correção de bug técnico ou desvio de conformidade normativa.
+- `refactor`: Refatoração interna sem alteração de contrato externo.
+- `test`: Adição ou atualização de testes automatizados no `pytest`.
+- `docs`: Atualização de `README.md`, `CONTRIBUTING.md`, `AGENTS.md`, `CLAUDE.md` ou docstrings.
+- `ci`: Ajustes nos pipelines de integração contínua (`.github/workflows/`).
+
+### 3.3. Padrão de Submissão de *Pull Requests* (PRs) e Registro no `CHANGELOG.md`
+Todo *Pull Request* submetido à *branch* `main` deve preencher integralmente o modelo `.github/PULL_REQUEST_TEMPLATE.md`, apresentando obrigatoriamente:
+1. **Justificativa Científica / Normativa:** Indicação explícita da norma (ex.: ABNT NBR 10520:2023, Seção 4.2) ou motivação arquitetural.
+2. **Tabela de Rastreabilidade SDD:** Mapeamento entre o arquivo atualizado em `specs/`, o `Rule ID` ou `@mcp.tool` afetado e o teste correspondente em `tests/`.
+3. **Atualização Obrigatória do `CHANGELOG.md`:** Toda modificação em `src/`, `specs/` ou `pyproject.toml` deve ser documentada em `CHANGELOG.md` (verificada automaticamente pelo GitHub Actions em Pull Requests e pela suíte `tests/test_sdd.py`).
+4. **Conformidade Multiplataforma:** Aprovação integral na matriz do GitHub Actions (Ubuntu Linux e Windows Server sob Python 3.10, 3.11 e 3.12).
+
+### 3.4. Governança de Releases SemVer e Publicação `uvx` / PyPI
+O lançamento de versões segue o **Versionamento Semântico (SemVer)** sincronizado às especificações:
+- **MAJOR (`X.0.0`):** Alteração incompatível no contrato de ferramentas (`specs/03-mcp-tools-contract.spec.md`) ou no schema `abnt.spec.json`.
+- **MINOR (`0.Y.0`):** Adição de nova ferramenta `@mcp.tool`, novo recurso ou nova regra em `NORMATIVE_RULES`.
+- **PATCH (`0.0.Z`):** Correções de validadores, regexes normativas ou documentação sem quebra de contrato.
+
+Ao criar e enviar uma tag `vX.Y.Z` (`git tag v0.2.0 && git push origin v0.2.0`), o workflow `.github/workflows/release.yml`:
+1. Verifica a paridade estrita entre a tag (`vX.Y.Z`), `pyproject.toml`, `src/abnt_mcp/__init__.py` e a seção `## [X.Y.Z]` do `CHANGELOG.md`;
+2. Constrói os pacotes `.whl` e `.tar.gz` via `uv build` e executa um teste de fumaça com `uvx`;
+3. Publica a **GitHub Release** oficial e realiza o upload para o **PyPI via Trusted Publishing (OIDC)**.
+
+---
+
+## 4. Configuração do Ambiente de Desenvolvimento e Auditoria Local
+
+### 4.1. Requisitos de Ambiente
+- Interpretador Python `>= 3.10` (`3.10`, `3.11` ou `3.12`).
+- Gerenciador de pacotes e ambientes [uv](https://docs.astral.sh/uv/).
+
+### 4.2. Instalação e Execução dos Testes
+```bash
+# 1. Clonar o repositório e sincronizar o ambiente determinístico
+git clone https://github.com/PedroSmaxY/abnt-mcp.git
+cd abnt-mcp
+uv sync --extra dev
+
+# 2. Executar a suíte completa com auditoria de cobertura e verificação SDD
+uv run pytest -v --cov=abnt_mcp --cov-report=term-missing
+
+# 3. Validar a interface de linha de comando do servidor
+uv run abnt-mcp --help
+```
+
+---
+
+## 5. Reporte de Problemas e Propostas via *Issues*
+
+Para assegurar a reprodutibilidade e o rigor normativo na triagem de demandas, utilize exclusivamente os formulários estruturados disponibilizados pelo repositório:
+1. **Desvio ou Atualização Normativa (`.github/ISSUE_TEMPLATE/normative_deviation.yml`):** Destinado a relatar divergências em relação às normas da ABNT ou do IBGE, exigindo a citação da norma, edição e item normativo.
+2. **Proposta de Especificação SDD (`.github/ISSUE_TEMPLATE/feature_spec.yml`):** Destinado à proposição de novas ferramentas MCP, perfis institucionais ou ampliação do manifesto `abnt.spec.json`.
+3. **Relato de Falha Técnica (`.github/ISSUE_TEMPLATE/bug_report.yml`):** Destinado a erros de execução, parsers de BibTeX/PDF ou motores de compilação (`typst`, `latex`, `markdown`).

abnt_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Henrique da Silva Novais
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.