fw-context-mcp

Servidor MCP para firmware embarcado em C/C++ — fornece aos assistentes de IA (Claude Code, Cursor, OpenCode, etc.) compreensão real da sua base de código. Analisa sua build real com libclang, extrai todos os símbolos e constrói um índice persistente com busca em texto completo, grafo de chamadas e embeddings vetoriais.

GitHub
8
Experimente este MCPPatrocinado

Documentação

fw-context

Inteligência de código ciente do build para agentes de codificação de IA que trabalham com firmware embarcado em C e C++.

O fw-context constrói um índice semântico persistente a partir do compile_commands.json e da AST do libclang, e o expõe a agentes de codificação por meio do MCP. Em vez de reconstruir seu firmware por meio de leituras repetidas de arquivos e buscas de texto, o agente pode consultar a estrutura do programa produzida pela configuração de build ativa.

Ele ajuda os agentes a responder perguntas como:

  • Qual implementação está ativa neste build?
  • Quem chama esta função, direta ou indiretamente?
  • Onde este callback está registrado?
  • Quais atribuições de ponteiro de função podem alcançar este ponto de chamada?
  • Qual código é excluído pelo pré-processamento?
  • O que será afetado se esta API mudar?
  • Como o fluxo de execução vai de uma ISR para o código da aplicação?

O objetivo não é dar ao modelo mais código-fonte. É dar a ele o menor contexto útil e ciente do build necessário para a tarefa atual.

Resultados de uma revisão real de firmware

No estudo de caso de revisão de firmware incluído, o fw-context foi usado em um projeto nRF52/Mbed OS contendo aproximadamente 67.000 linhas de C e C++:

  • 115 arquivos alterados revisados por 8 subagentes paralelos
  • 19 descobertas em segurança de memória, concorrência, uso de API e código morto
  • 9 descobertas que dependiam de relações semânticas não disponíveis apenas por busca de texto comum
  • aproximadamente 54.000 tokens de contexto usados pelas consultas do fw-context
  • uma estimativa de 5,8 milhões de tokens para o fluxo de trabalho equivalente de grep e leitura de arquivos

O estudo de caso inclui a saída da revisão, a metodologia e a análise de tokens por ferramenta, para que as afirmações possam ser inspecionadas em vez de tratadas como um benchmark de caixa-preta.

Início rápido

Pré-requisitos

  • Python 3.11 ou mais recente
  • libclang
  • um projeto que possa produzir compile_commands.json
  • um agente de codificação compatível com MCP, como Claude Code ou OpenCode

Ollama é opcional. Ele é usado apenas para enriquecimento semântico local e explicações de símbolos; o índice principal derivado do compilador não o exige.

Instalar via pip (recomendado)

pip install fw-context-mcp

Instalar a versão atual do código-fonte

git clone https://github.com/turbyho/fw-context-mcp.git ~/.fw-context/src
cd ~/.fw-context/src
make install

Registre o fw-context com os agentes de codificação compatíveis detectados no seu projeto:

cd /path/to/your/firmware
fw-context init

Compile e indexe o firmware:

cd /path/to/your/firmware
fw-context index --build

Em seguida, reinicie o agente de codificação e faça perguntas sobre o projeto. O índice é persistente e incremental; após a execução inicial, as unidades de tradução alteradas são reprocessadas em vez de reconstruir todo o índice.

Consulte o Início Rápido e o Guia de Instalação para configuração específica por plataforma e sistemas de build suportados.

O que o fw-context muda

Sem um índice semântico do projeto, um agente de codificação de IA geralmente começa abrindo arquivos, buscando nomes, seguindo includes e tentando inferir relações implícitas no build. Em firmware embarcado, essa reconstrução costuma ser a parte dominante da tarefa.

Essa abordagem pode falhar de maneiras previsíveis:

  • revisar arquivos de origem que não fazem parte do build ativo
  • seguir o ramo errado do pré-processador
  • perder registros de callbacks e chamadas indiretas
  • selecionar um driver ou implementação de plataforma inativo
  • tratar declarações encontradas por busca de texto como código alcançável
  • consumir grandes quantidades de contexto com código de fornecedor e arquivos não relacionados

O fw-context move grande parte dessa reconstrução para um índice reutilizável derivado do compilador. O agente pode solicitar corpos de símbolos exatos, chamadores, chamados, referências, macros ativas, relações de callbacks, arestas de herança e outras informações direcionadas sem ler árvores de origem inteiras.

Por que firmware embarcado é diferente

Em muitos projetos de nível de aplicação, os arquivos de origem visíveis no repositório estão razoavelmente próximos do programa em execução. Projetos embarcados em C e C++ geralmente têm uma lacuna muito maior entre a árvore de origem e o programa resultante.

O firmware ativo depende de fatores como:

  • flags do compilador e definições do pré-processador
  • configuração de alvo, placa e produto
  • caminhos de include e cabeçalhos gerados
  • seleções de Kconfig e Devicetree
  • implementações selecionadas de driver e HAL
  • templates, herança e despacho virtual
  • callbacks, manipuladores de interrupção e ponteiros de função
  • configuração de SDK e RTOS do fornecedor

Um repositório pode, portanto, conter várias implementações plausíveis do mesmo subsistema, enquanto apenas uma é compilada para o alvo selecionado. Um agente pode raciocinar de forma convincente sobre a implementação errada, a menos que primeiro reconstrua o contexto do build corretamente.

Como funciona

O fw-context indexa o projeto por meio do mesmo banco de dados de compilação usado pelas ferramentas de build e servidores de linguagem.

flowchart LR
    CCJ[compile_commands.json] & SRC[(source files)] --> LIBCLANG[libclang<br/>AST parser]
    LIBCLANG --> SYMBOLS[symbols<br/>name, kind, USR<br/>signature, source body<br/>docstring, tokens] & FILES[files<br/>path, language<br/>ifdef-filtered content<br/>project/SDK sources] & REFS[refs &amp; call graph<br/>fp_assignments<br/>indirect_call_sites] & INHERIT[inheritance<br/>&amp; overrides<br/>virtual dispatch] & MACROS[macros<br/>raw &amp; expanded values<br/>FTS5 searchable] & ENRICH[optional enrichment<br/>embeddings &amp; summaries<br/>hotspot cache]
    SYMBOLS & FILES & REFS & INHERIT & MACROS & ENRICH --> MCP[MCP server<br/>37 tools]
    MCP --> LLM[AI coding agent]

O índice contém:

  • definições de símbolos, assinaturas, extensões de origem e documentação
  • referências, arestas de chamada direta e caminhos de chamadores recursivos
  • atribuições de ponteiro de função e pontos de chamada indireta
  • registros de callbacks e relações de invocação
  • conteúdo de arquivo ativo e filtrado por pré-processador
  • valores de macro brutos e expandidos
  • herança, overrides e relações de despacho virtual
  • metadados de unidade de tradução e de projeto/fornecedor
  • embeddings opcionais e resumos gerados por LLM

O servidor MCP expõe essas informações como consultas compactas de alto nível, otimizadas para uso repetido por um agente de IA.

Casos de uso típicos

  • revisão de commits de firmware ciente do build
  • rastreamento de execução entre ISRs, filas de trabalho, tarefas e callbacks
  • localização de todos os chamadores e referências de uma API
  • identificação da implementação selecionada pelo build atual
  • análise de impacto antes de alterar uma assinatura de função ou tipo de dado
  • navegação em firmware desconhecido sem ler arquivos completos
  • encontrar candidatos a código morto e símbolos não referenciados
  • separar código do projeto de código de SDK e fornecedor
  • reduzir texto de origem irrelevante enviado ao modelo

O fw-context suporta Zephyr, PlatformIO, Mbed OS, Arduino, ESP-IDF, CMake genérico, projetos baseados em Makefile e builds personalizados que possam fornecer um banco de dados de compilação. Caminhos de configuração adicionais são documentados para Keil, IAR, STM32CubeIDE e TI Code Composer Studio.

Por que não usar apenas clangd ou outro LSP?

O clangd já usa comandos de compilação e é excelente em tarefas orientadas a editor, como diagnósticos, conclusão, ir para definição e busca de referências. O fw-context não o substitui.

O fw-context tem como alvo uma interface e uma carga de trabalho diferentes:

  • dados persistentes de todo o projeto preparados para consultas repetidas de agentes
  • ferramentas MCP que retornam contexto semântico compacto e estruturado
  • consultas de chamadores recursivos e análise de impacto
  • modelagem de relações de callbacks e ponteiros de função
  • conteúdo de origem ativo adequado para recuperação direcionada
  • classificação de projeto/fornecedor e fluxos de trabalho específicos de firmware
  • enriquecimento em cache opcional compartilhado entre análises repetidas

Use clangd para edição interativa. Use fw-context quando um agente de IA precisar de contexto estruturado e reutilizável para revisar, entender ou navegar no firmware compilado.

Documentação

Maturidade do projeto

O fw-context é funcional e é usado em projetos reais de C e C++ embarcado, mas suas interfaces e comportamento de indexação ainda estão evoluindo. Relatórios de bugs, resultados incorretos, configurações de build não suportadas e casos extremos reproduzíveis são particularmente valiosos.

O projeto é local-first: o código-fonte e o índice derivado do compilador permanecem na máquina do desenvolvedor, a menos que serviços externos opcionais sejam explicitamente configurados.

Contexto

O projeto surgiu de um modo de falha recorrente no trabalho assistido por IA com firmware: agentes de codificação frequentemente gastavam mais esforço reconstruindo o programa ativo do que raciocinando sobre a própria questão de engenharia.

Para a explicação mais longa, leia: Por que agentes de codificação de IA continuam cometendo os mesmos erros ao analisar firmware embarcado

O compilador já reconstruiu seu programa. Deixe seu agente de codificação usá-lo.