bncc.dev · pacotes, MCP e API de consulta

A Base Nacional Comum Curricular (BNCC) consumível em uma linha de código. As 1.721 aprendizagens da educação básica brasileira, verificadas contra os documentos oficiais do MEC/CNE, como pacote npm, pacote PyPI e servidor MCP para agentes de IA. Dados embutidos, zero dependências de runtime, zero rede: a consulta acontece na sua máquina.

O dataset não nasce aqui, vem do bncc-dados. Este repositório são as interfaces para máquina desse dataset.

Uso rápido

npx -y @bncc/mcp          # servidor MCP: a BNCC ao alcance do seu agente de IA
npm install @bncc/dados   # TypeScript / JavaScript
pip install bncc          # Python

TypeScript

import { porCodigo, habilidadesEF, buscar, decodificar } from '@bncc/dados';

const h = porCodigo('EF67LP08');
h.texto;                               // enunciado oficial verificado
h.organizacao.nomes.praticaLinguagem;  // 'Leitura'
h.fonte.localizador_pdf;               // 'Base-Nacional-Comum-Curricular-BNCC.pdf, página PDF 167'

habilidadesEF({ componente: 'LP', ano: 6, pratica: 'Leitura' });  // 37 habilidades
buscar('frações', { etapa: 'EF', componente: 'MA' });             // 6 resultados
decodificar('EM13LGG103');  // { etapa: 'EM', area: 'LGG', competenciaEspecifica: 1, sequencia: 3, ... }

Python, a mesma semântica, na convenção de cada ecossistema:

from bncc import por_codigo, habilidades_ef, buscar, decodificar

por_codigo('EF67LP08')['texto']
habilidades_ef(componente='LP', ano=6, pratica='Leitura')  # 37
decodificar('EI02TS01')  # {'etapa': 'EI', 'campo_experiencias': 'TS', ...}

Que as duas respondam idêntico não é promessa: é testado a cada commit pelas mesmas consultas douradas.

Servidor MCP

Sete tools (bncc_lookup, bncc_buscar, bncc_listar, bncc_decodificar, bncc_estatisticas, bncc_estrutura, bncc_progressao_ei) que dão ao agente a BNCC verificada, com fonte oficial em cada resposta. Códigos inexistentes recebem um erro que explica que a numeração da BNCC tem lacunas legítimas, em vez de um null que convida à alucinação.

Local, sem instalação permanente:

{ "mcpServers": { "bncc": { "command": "npx", "args": ["-y", "@bncc/mcp"] } } }

Hospedado, sem instalação nenhuma e sem API key: https://mcp.bncc.dev (streamable HTTP).

Quanto isso muda a resposta de um modelo está medido, com dados brutos publicados, no bncc-benchmark.

O que tem neste repositório

| Diretório | Publica | Versão | |---|---|---| | packages/bncc | npm @bncc/dados: dados embutidos + API tipada | 0.3.1 | | packages/mcp | npm @bncc/mcp: o servidor MCP, via npx | 0.2.0 | | python/ | PyPI bncc: a API equivalente em snake_case | 0.2.0 | | mcp-worker/ | o mesmo MCP hospedado em mcp.bncc.dev (Cloudflare Workers) | no ar |

Os dados embutidos são sincronizados de um commit específico do bncc-dados por scripts/sincronizar-dados.mjs, com data-version e checksums registrados em dados/VERSAO.json de cada pacote. Ninguém edita dados/ à mão.

O 1.0.0 dos três pacotes está condicionado à release dados-v1.0.0 do bncc-dados, que traz a revisão pedagógica registrada.

O site (bncc.dev) e o worker do formulário de contato não vivem aqui: migraram para bncc-site em jul/2026. Fica neste repo o que compartilha o dataset: ver DECISOES.md D2.

Desenvolvimento

pnpm install && pnpm -r build && pnpm -r test   # npm, MCP e worker
cd python && uv sync && uv run pytest           # PyPI

Node 22+, pnpm (a versão vem do packageManager) e uv. O CI roda exatamente esses dois blocos.

Antes de abrir PR, leia o CONTRIBUTING.md: a regra de ouro é que o núcleo injetável (criarConsultas) é a única superfície de consulta, e PRs que reimplementem lookup, busca ou decodificação são recusados mesmo passando nos testes.

Documentação

| Documento | Para quê | |---|---| | docs/manual-rapido.md | A visão de quem consome os pacotes: receitas por caso de uso | | docs/arquitetura.md | O desenho do monorepo, o fluxo de dados pinado e o núcleo injetável | | docs/paridade.md | O contrato das consultas douradas que impede npm e PyPI de divergirem | | docs/manutencao.md | Runbook: atualizar dados, mudar API, publicar, troubleshooting | | DECISOES.md | As escolhas não óbvias e por quê | | CHANGELOG.md | O que mudou em cada versão publicada | | AGENTS.md | Regras para agentes de IA trabalhando neste repo |

O ecossistema

| Repositório | O que é | |---|---| | bncc-dados | O dataset: extração reprodutível, validada em CI, com proveniência por registro | | bncc-pacotes | Este repo: npm, PyPI e MCP sobre o dataset | | bncc-benchmark | Quanto os LLMs alucinam sobre a BNCC, e quanto o grounding resolve |

Quem mantém

O bncc.dev é mantido pela Profy. A Profy opera produtos que usam LLMs sobre a BNCC; estes pacotes são a camada verificada que esses produtos consomem, publicada aberta para que qualquer um consuma a mesma coisa.

Licenças

Código MIT, dados embutidos CC BY 4.0, em arquivos separados porque o mesmo artefato publicado carrega as duas naturezas: LICENSE, LICENSE-CODIGO.md, LICENSE-DADOS.md.

O nome "bncc.dev" e a identidade visual não são licenciados: o código é livre, a marca não. Derivados não devem se apresentar como sendo o bncc.dev.

Segurança: SECURITY.md (não abra issue pública). Conduta: CODE_OF_CONDUCT.md.