内容
# [bncc.dev](https://bncc.dev) · 软件包、MCP 和查询 API
[](https://github.com/bncc-dev/bncc-pacotes/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@bncc/dados)
[](https://pypi.org/project/bncc/)
[](LICENSE-CODIGO.md)
[](LICENSE-DADOS.md)
巴西基础教育国家共同课程基准（BNCC）可在一行代码中直接使用。包含 1,721 个基本教育学习目标，经过教育部（MEC）和国家教育委员会（CNE）官方文件的验证，以 npm 软件包、PyPI 软件包和 MCP 服务器的形式提供，供 AI 代理使用。数据嵌入，运行时零依赖，查询在您的机器上进行。
数据集并非源自本仓库，而是来自 [bncc-dados](https://github.com/bncc-dev/bncc-dados)。
本仓库提供的是该数据集的**机器接口**。
## 快速使用
```bash
npx -y @bncc/mcp # MCP 服务器：BNCC 可用于您的 AI 代理
npm install @bncc/dados # TypeScript / JavaScript
pip install bncc # Python
```
**TypeScript**
```ts
import { porCodigo, habilidadesEF, buscar, decodificar } from '@bncc/dados';
const h = porCodigo('EF67LP08');
h.texto; // 验证后的官方陈述
h.organizacao.nomes.praticaLinguagem; // '阅读'
h.fonte.localizador_pdf; // 'Base-Nacional-Comum-Curricular-BNCC.pdf, PDF 第 167 页'
habilidadesEF({ componente: 'LP', ano: 6, pratica: 'Leitura' }); // 37 个技能
buscar('分数', { etapa: 'EF', componente: 'MA' }); // 6 个结果
decodificar('EM13LGG103'); // { etapa: 'EM', area: 'LGG', competenciaEspecifica: 1, sequencia: 3, ... }
```
**Python**，相同的语义，按照每个生态系统的约定：
```python
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', ...}
```
我们承诺两个实现的结果相同：[每次提交都会测试](docs/paridade.md)，使用相同的黄金查询。
## MCP 服务器
七种工具（`bncc_lookup`, `bncc_buscar`, `bncc_listar`, `bncc_decodificar`, `bncc_estatisticas`, `bncc_estrutura`, `bncc_progressao_ei`）为代理提供经过验证的 BNCC，官方来源在每个响应中。 不存在的代码会收到一个错误，解释 BNCC 编号有合法的空白，而不是一个 `null` 值，容易引起幻觉。
**本地**，无需永久安装：
```json
{ "mcpServers": { "bncc": { "command": "npx", "args": ["-y", "@bncc/mcp"] } } }
```
**托管**，无需任何安装和 API 密钥：`https://mcp.bncc.dev`（可流式传输的 HTTP）。
这对模型的影响程度正在衡量，原始数据已发布在 [bncc-benchmark](https://github.com/bncc-dev/bncc-benchmark) 中。
## 本仓库的内容
| 目录 | 发布 | 版本 |
|---|---|---|
| `packages/bncc` | npm [`@bncc/dados`](https://www.npmjs.com/package/@bncc/dados): 嵌入式数据 + 类型 API | `0.3.1` |
| `packages/mcp` | npm [`@bncc/mcp`](https://www.npmjs.com/package/@bncc/mcp): MCP 服务器，通过 npx | `0.2.0` |
| `python/` | PyPI [`bncc`](https://pypi.org/project/bncc/): snake_case 中的等效 API | `0.2.0` |
| `mcp-worker/` | 与 `mcp.bncc.dev` 上托管的相同（Cloudflare Workers） | 运行中 |
嵌入式数据通过 `scripts/sincronizar-dados.mjs` 与 bncc-dados 的特定提交同步，数据版本和校验和记录在每个包的 `dados/VERSAO.json` 中。 无人手动编辑 `dados/`。
三个包的 `1.0.0` 版本取决于 bncc-dados 的 `dados-v1.0.0` 版本，该版本具有记录的教学修订。
网站（bncc.dev）和联系表单的工作器**不再此处**：它们已迁移到 [bncc-site](https://github.com/bncc-dev/bncc-site)，于 2026 年 7 月生效。
本仓库中保留共享数据集的内容：参见 [DECISOES.md](DECISOES.md) D2。
## 开发
```bash
pnpm install && pnpm -r build && pnpm -r test # npm、MCP 和工作器
cd python && uv sync && uv run pytest # PyPI
```
Node 22+，[pnpm](https://pnpm.io)（版本来自 `packageManager`）和 [uv](https://docs.astral.sh/uv/)。CI 恰好运行这两个块。
在打开 PR 之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)：黄金法则是可注入的核心（`criarConsultas`）是**唯一**查询接口，
拒绝重新实现查找、搜索或解码的 PR，即使它们通过测试。
## 文档
| 文档 | 用途 |
|---|---|
| [docs/manual-rapido.md](docs/manual-rapido.md) | 消费包的视图：按用例的配方 |
| [docs/arquitetura.md](docs/arquitetura.md) | monorepo 的设计、数据流和可注入的核心 |
| [docs/paridade.md](docs/paridade.md) | 阻止 npm 和 PyPI 分歧的黄金查询合约 |
| [docs/manutencao.md](docs/manutencao.md) | 运行手册：更新数据、更改 API、发布、故障排除 |
| [DECISOES.md](DECISOES.md) | 非显而易见的选择及原因 |
| [CHANGELOG.md](CHANGELOG.md) | 每个已发布版本中的更改 |
| [AGENTS.md](AGENTS.md) | 用于此仓库的 AI 代理规则 |
## 生态系统
| 仓库 | 内容 |
|---|---|
| [bncc-dados](https://github.com/bncc-dev/bncc-dados) | 数据集：可复制、验证的提取，具有溯源记录 |
| **bncc-pacotes** | 本仓库：数据集上的 npm、PyPI 和 MCP |
| [bncc-benchmark](https://github.com/bncc-dev/bncc-benchmark) | LLM 关于 BNCC 的幻觉程度，以及 grounding 解决程度 |
## 维护者
bncc.dev 由 [Profy](https://www.profy.ai/) 维护。 Profy 运营使用 LLMs 的产品，关于 BNCC；这些包是经过验证的层，这些产品使用，公开供任何人使用。
## 许可证
**MIT 代码**，**CC BY 4.0 数据**，在单独的文件中，因为相同的制品承载两种性质： [LICENSE](LICENSE)， [LICENSE-CODIGO.md](LICENSE-CODIGO.md)， [LICENSE-DADOS.md](LICENSE-DADOS.md)。
"bncc.dev" 名称和视觉身份**不**被许可：代码是开放的，品牌不是。衍生品不应表现为 bncc.dev。
安全： [SECURITY.md](SECURITY.md)（不要公开提问）。
行为准则： [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。
