BNCC MCP

Servidor MCP que expõe as habilidades da Base Nacional Comum Curricular (Educação Infantil, Ensino Fundamental e Ensino Médio) com unidade temática, objeto de conhecimento e a camada de priorização do Mapa de Foco (Instituto Reúna).

A BNCC (MEC) é de livre uso; o Mapa de Foco é © Instituto Reúna, incluído mediante autorização e sujeito a atribuição/uso não comercial — ver ATTRIBUTION.md.

Sumário

• Acervo

• Instalação

• Configuração no Claude Code

• Tools

  • bncc_lookup

  • bncc_buscar

  • bncc_listar

  • bncc_mapa_de_foco

  • bncc_estatisticas

• Esquema dos registros

• Semântica do filtro de ano

• Procedência dos dados

• Limitações

• Estrutura do projeto

Acervo

Mapa de Foco — 396 habilidades priorizadas com classificação, conhecimento prévio, objetivos de aprendizagem, competências e habilidades relacionadas e comentários:

Instalação

Requer Python 3.10+.

pip install bncc-mcp          # quando publicado no PyPI
# ou, a partir do código-fonte:
pip install .
# para desenvolvimento:
pip install -e .

Configuração no Claude Code

Após instalar o pacote:

claude mcp add bncc --scope user -- python -m bncc_mcp

Ou manualmente em .mcp.json / configuração de MCP:

{
  "mcpServers": {
    "bncc": {
      "command": "python",
      "args": ["-m", "bncc_mcp"]
    }
  }
}

As tools aparecem como mcp__bncc__<nome> na sessão seguinte (servidores adicionados durante uma sessão não carregam retroativamente).

Tools

bncc_lookup(codigo)

Retorna o registro completo de uma habilidade pelo código.

Quando a habilidade está no Mapa de Foco, o objeto mapa_foco é incluído. Código inexistente devolve {"erro": ..., "dica": ...}.

Exemplo — bncc_lookup("EF06MA01"):

{
  "codigo": "EF06MA01",
  "etapa": "Ensino Fundamental",
  "componente": "Matemática",
  "ano_ou_faixa": "06",
  "campo_experiencia": "",
  "unidade_tematica": "Números",
  "objeto_conhecimento": "Sistema de numeração decimal: características, leitura, escrita e comparação de números naturais e de números racionais representados na forma decimal",
  "habilidade": "Comparar, ordenar, ler e escrever números naturais e números racionais cuja representação decimal é finita, fazendo uso da reta numérica.",
  "em_foco": true,
  "mapa_foco": {
    "classificacao": "AF",
    "conhecimento_previo": "EF05MA01, EF05MA02, EF05MA05 e EF05MA07",
    "objetivos_aprendizagem": "• Ler e escrever números naturais e números racionais decimais\n• Comparar ...",
    "competencias_relacionadas": "CG: 1 e 4",
    "habilidades_relacionadas": "EF06MA05 EF06MA12",
    "comentarios": "..."
  }
}

bncc_buscar(texto, etapa, componente, ano, apenas_em_foco, limite)

Busca habilidades por palavra-chave no enunciado/objeto/unidade (acento-insensível), com filtros opcionais. Todos os termos do texto precisam estar presentes (AND).

Retorno: { "total": int, "exibindo": int, "resultados": [ {codigo, etapa, componente, ano, em_foco, habilidade} ] }

Exemplo — bncc_buscar(texto="fração", componente="Matemática", apenas_em_foco=true, limite=3):

{
  "total": 4,
  "exibindo": 3,
  "resultados": [
    {"codigo": "EF06MA07", "etapa": "Ensino Fundamental", "componente": "Matemática", "ano": "06", "em_foco": true, "habilidade": "Compreender, comparar e ordenar frações associadas às ideias de ..."}
  ]
}

bncc_listar(componente, ano, etapa, limite)

Lista as habilidades de um recorte (componente + ano), com unidade temática e objeto de conhecimento de cada uma.

Retorno: { "componente", "ano", "total", "exibindo", "resultados": [ {codigo, ano, unidade_tematica, objeto_conhecimento, em_foco, habilidade} ] }

bncc_mapa_de_foco(componente, ano, limite)

Retorna as habilidades priorizadas no Mapa de Foco, com toda a camada pedagógica.

Retorno: { "componente", "ano", "total", "exibindo", "resultados": [ {codigo, componente, ano, unidade_tematica, objeto_conhecimento, habilidade, mapa_foco} ] }

Exemplo — bncc_mapa_de_foco(componente="História", ano="6", limite=1):

{
  "componente": "História",
  "ano": "6",
  "total": 23,
  "exibindo": 1,
  "resultados": [
    {
      "codigo": "EF06HI01",
      "componente": "História",
      "ano": "06",
      "unidade_tematica": "História: tempo, espaço e formas de registros",
      "objeto_conhecimento": "A questão do tempo, sincronias e diacronias: reflexões sobre o sentido das cronologias",
      "habilidade": "Identificar diferentes formas de compreensão da noção de tempo e de periodização dos processos históricos (continuidades e rupturas).",
      "mapa_foco": {
        "classificacao": "AF",
        "conhecimento_previo": "EF05HI07",
        "objetivos_aprendizagem": "• Identificar e analisar diferentes noções de tempo.\n• Construir os conceitos de sincronia e de diacronia ...",
        "competencias_relacionadas": "CG: 1 e 2\nCA: 2, 4 e 5\nCE: 2 e 6",
        "habilidades_relacionadas": "AF:\n- EF06GE11: amplia o conhecimento da AF.\n- EF06GE08: amplia o conhecimento da AF.",
        "comentarios": "Ao se trabalhar características físico-naturais da superfície terrestre ..."
      }
    }
  ]
}

Campos do mapa_foco:

bncc_estatisticas()

Resumo do acervo. Sem parâmetros.

{
  "total_habilidades": 1576,
  "por_etapa": {"Ensino Fundamental": 1304, "Educação Infantil": 93, "Ensino Médio": 179},
  "em_foco_total": 396,
  "em_foco_por_componente": {"Ciências": 56, "Geografia": 53, "História": 37, "Língua Portuguesa": 127, "Matemática": 123}
}

Esquema dos registros

Campos retornados por bncc_lookup (varia conforme a etapa):

Semântica do filtro de ano

O parâmetro ano aceita 6, 06 ou 6º (a pontuação é ignorada) e segue a convenção de codificação da BNCC:

• Ano único vem com zero à esquerda: 06 = 6º ano.

• Faixa vem sem zero, com 1º dígito < 2º: 69 = 6º ao 9º, 15 = 1º ao 5º, 35 = 3º ao 5º, 12 = 1º e 2º.

Buscar ano="6" retorna tanto as habilidades exclusivas do 6º ano (EF06...) quanto as de faixas que incluem o 6º (EF69..., EF67...).

Procedência dos dados

Os CSVs em data/ são gerados por dois scripts no diretório-pai do projeto:

1. extrair_objetos.py — extrai unidade temática + objeto de conhecimento do PDF oficial da BNCC (EI/EF), explorando o layout em spread de duas páginas e casando por coordenada vertical. Cobre 100% das 1304 habilidades EF.

2. add_mapa_foco.py — lê a planilha unificada do Mapa de Foco (MapasDeFocoBncc_Unificados.xlsx, Instituto Reúna) e acrescenta as 7 colunas do Mapa de Foco para as 396 habilidades selecionadas.

Para regerar: rodar os dois scripts (nessa ordem) e copiar BNCC_habilidades_enriquecido.csv → data/bncc_habilidades.csv e bncc_em_habilidades.csv → data/bncc_em.csv.

Limitações

• O Mapa de Foco cobre apenas Língua Portuguesa, Matemática, Ciências, História e Geografia do Ensino Fundamental. Para Arte, Educação Física, Língua Inglesa, Ensino Religioso, Educação Infantil e Ensino Médio, em_foco é sempre false — porque não há Mapa de Foco publicado para esses, não por lacuna do acervo.

• Educação Infantil não tem unidade temática nem objeto de conhecimento (usa campos de experiência); esses campos ficam vazios para EI.

• Alguns objetos de conhecimento longos e com marcadores de História podem juntar duas células adjacentes do PDF (limitação da extração por coordenada).

Estrutura do projeto

bncc-mcp/
├── pyproject.toml        # empacotamento; console script `bncc-mcp`
├── README.md             # este arquivo
├── LICENSE               # MIT (cobre o código)
├── ATTRIBUTION.md        # proveniência e licenças dos dados
├── CHANGELOG.md
├── bncc_mcp/
│   ├── __init__.py
│   ├── __main__.py       # `python -m bncc_mcp`
│   ├── server.py         # servidor MCP (FastMCP), 5 tools
│   └── data/
│       ├── bncc_habilidades.csv   # EI + EF, enriquecido + Mapa de Foco
│       └── bncc_em.csv            # Ensino Médio
└── tests/
    └── test_server.py

Licença e atribuição

• Código: licença MIT (ver LICENSE).

• Dados: a BNCC (MEC) é de livre uso; o Mapa de Foco é © 2020 Instituto Reúna, incluído mediante autorização, e seu reuso exige atribuição e é restrito a fins não comerciais. Detalhes e forma de citar em ATTRIBUTION.md.

Dados da BNCC: Ministério da Educação (MEC). Camada de priorização: Mapas de Foco da BNCC © 2020 Instituto Reúna (institutoreuna.org.br), usados com autorização.