# mcp-territorio-brasil

**Servidor MCP de dados territoriais oficiais do Brasil (IBGE) — com as armadilhas de cruzamento entre bases declaradas na resposta.**

Três tools que não mentem, em vez de trinta que não sabem.

---

## O problema que este servidor resolve

Quase toda análise regional no Brasil cruza o IBGE com outra base oficial — DATASUS, CNES,
Receita Federal. E o primeiro cruzamento costuma falhar **em silêncio**:

> O código de município do IBGE tem **7 dígitos** — o 7º é dígito verificador. O DATASUS e o
> CNES usam **6** (Canoas/RS = `4304606` no IBGE, `430460` no CNES). Um JOIN direto entre as
> bases devolve **zero linhas, sem erro**. A análise parece vazia, não quebrada.

Este servidor devolve os **dois códigos** em toda resposta e aceita qualquer um deles como entrada.

## A garantia

Toda resposta segue o **phi-data-contract v0.1**: `data` + `provenance` (fonte, data de coleta,
ano de referência) + `caveats` (os defeitos que se aplicam àquela consulta, com evidência e data
de verificação) + `cannot_answer` (o que a pergunta pediu e a fonte não responde).

## Instalação

Requer **Node ≥ 22.5** (SQLite embutido — zero dependências nativas).

```bash
npm install && npm run build
npm run db:build        # baixa direto do IBGE (Localidades + SIDRA) e monta o SQLite
```

**Nada é redistribuído** — a base é construída na sua máquina, sempre da fonte.

```json
{
  "mcpServers": {
    "territorio": {
      "command": "node",
      "args": ["--experimental-sqlite", "/caminho/mcp-territorio-brasil/dist/index.js"],
      "env": { "TERRITORIO_LANG": "pt" }
    }
  }
}
```

## As tools

| Tool | O que faz |
|---|---|
| `territorio_municipio` | Município com região imediata/intermediária, população (estimativa + Censo 2022), PIB e PIB per capita. Aceita nome, código de 7 ou de 6 dígitos; `codes` resolve até 1000 de uma vez. |
| `territorio_regiao` | Totais de UF, região intermediária ou imediata (nº de municípios, população, PIB) + a lista de municípios. Aceita o código de um município. |
| `territorio_data_caveats` | As armadilhas conhecidas, com evidência e procedência. |

## Os caveats

| id | Severidade | Corrigido? |
|---|---|---|
| `codigo_6_vs_7_digitos` | crítico | ✅ os dois códigos em toda resposta |
| `populacao_estimada_nao_e_censo` | aviso | — as duas séries vêm separadas, com ano |
| `pib_defasado_e_corrente` | aviso | ✅ PIB per capita sobre a população do mesmo período (Censo 2022), nunca sobre a estimativa corrente |
| `microrregiao_descontinuada` | info | ✅ agrega pela região imediata (divisão oficial desde 2017) |

## Fontes

IBGE — API de Localidades (`servicodados.ibge.gov.br`) e SIDRA (`apisidra.ibge.gov.br`):
tabelas 6579 (estimativa de população), 4709 (Censo 2022) e 5938 (PIB dos municípios).

```bash
npm test
```

MIT · Autor: **Luis Delfin** · parte da rede de servidores MCP de dados públicos de [Phi AI](https://phiai.io)

---

# English

**MCP server for Brazil's official territorial data (IBGE) — with cross-dataset traps declared in the response.**

The first join between IBGE and another official dataset (DATASUS, CNES, Federal Revenue) usually
fails **silently**: IBGE municipality codes have **7 digits** (the 7th is a check digit), DATASUS/CNES
use **6**. A direct JOIN returns **zero rows, no error**. This server returns both codes in every
response and accepts either as input.

Every response follows **phi-data-contract v0.1**: `data` + `provenance` + `caveats` + `cannot_answer`.

| Tool | What it does |
|---|---|
| `territorio_municipio` | Municipality with immediate/intermediate region, population (estimate + 2022 Census), GDP and GDP per capita. Accepts name, 7- or 6-digit code; `codes` resolves up to 1000 at once. |
| `territorio_regiao` | Totals for a state, intermediate or immediate region, plus its municipalities. |
| `territorio_data_caveats` | Known traps, with evidence and provenance. |

Requires Node ≥ 22.5. `npm install && npm run build && npm run db:build`. No data is redistributed.

MIT · Author: **Luis Delfin**