# brdata

brdata puts Brazil's open public data behind one small command-line
tool and one stdio MCP server. Most of the questions it answers need
no account and no key: where a CEP lands, what a company registration
says, whether a CPF number is even arithmetically valid, what the
central bank's headline rates are doing, which vehicle brands the
FIPE table tracks, what a state or municipality looks like in the
IBGE geography, and what is being bought, published, or registered
in the public procurement portal, municipal gazettes, the lawyers'
registry, the slave-labour blacklist, and the national health
facility registry.

Twelve tools are included. This is a labelled core subset of a
larger catalogue: company deep profiles, court-process and warrant
searches, wanted-person and consumer-complaint lookups, and several
other tools from that catalogue are deliberately out of scope here.

## Install

```bash
npx @reneturcios/brdata ibge --uf SP
```

Or run the container image:

```bash
docker run -i ghcr.io/cloudcorprecords/brdata
```

The container defaults to the MCP server. Pass CLI arguments to use
it as a CLI instead. No environment variable is required: every
upstream used here is a public, keyless endpoint.

## CLI

```bash
brdata ibge --scope municipios --uf SP
brdata pncp merenda --uf BA
brdata diario edital
brdata oab "Maria Silva" --uf RJ
brdata lista-suja "Fazenda Exemplo"
brdata cnpj 12345678000195
brdata cep 01310-100
brdata cpf 529.982.247-25
brdata whois example.com.br
brdata bacen --indicator selic
brdata fipe Fiat
brdata cnes "Hospital Central" --municipio Campinas

brdata --version
```

Each command prints the upstream JSON payload, except `cpf`, which
prints the local validation result. Exit codes: `0` on success, `1`
when a call or validation input fails, `2` for usage errors.

## MCP server

```bash
npx -y @reneturcios/brdata mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "brdata": {
      "command": "npx",
      "args": ["-y", "@reneturcios/brdata", "mcp"]
    }
  }
}
```

### Tools

| Tool | Input | What it returns |
| --- | --- | --- |
| `ibge_localidades` | `scope` (optional: estados/municipios), `uf` (optional) | IBGE states or municipalities. |
| `pncp_licitacoes` | `query`, `uf` (both optional) | PNCP public procurement notices. |
| `querido_diario` | `query` (required) | Municipal gazette search results. |
| `oab_advogado` | `name` (required), `uf` (optional) | OAB lawyer registry matches. |
| `lista_suja_lookup` | `query` (required) | Slave-labour blacklist matches. |
| `cnpj_lookup` | `cnpj` (required, 14 digits) | Company registration data via BrasilAPI. |
| `cep_lookup` | `cep` (required, 8 digits) | Postal-code locality via BrasilAPI. |
| `cpf_validate` | `cpf` (required) | Local check-digit validation; no network call. |
| `domain_whois` | `domain` (required) | .br domain WHOIS via the registro.br data on BrasilAPI. |
| `bacen_taxas` | `indicator` (optional: selic/ipca/usd/eur/cdi) | Latest Banco Central SGS value for the indicator. |
| `fipe_veiculos` | `query` (optional) | FIPE vehicle brands, filtered by the query when given. |
| `cnes_saude` | `query`, `municipio` (both optional) | CNES health facilities. |

Notes on sources: IBGE geography comes from the IBGE localities
service, Banco Central figures from the BCB open-data SGS series,
FIPE brands from the public Parallelum FIPE API, and CNPJ/CEP/WHOIS
from BrasilAPI. The PNCP, OAB, lista suja, and CNES requests are
shaped against those services' public endpoints; their parameter
shapes are reconstructions from the public search surface and are
labelled as such in the build report, since no live call was made
while building this package.

CPF validation is exact, not sampled: it strips punctuation,
rejects all-equal digits and wrong lengths, and recomputes both
modulo-11 check digits locally.

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx
```

## License

MIT — see `LICENSE`.