fw-context-mcp

Servidor MCP para firmware embebido en C/C++ — brinda a asistentes de IA (Claude Code, Cursor, OpenCode, etc.) una comprensión real de tu base de código. Analiza tu compilación real con libclang, extrae cada símbolo y construye un índice persistente con búsqueda de texto completo, grafo de llamadas y embeddings vectoriales.

GitHub
8
Prueba este MCPPatrocinado

Documentación

fw-context

Inteligencia de código consciente del build para agentes de codificación de IA que trabajan en firmware embebido en C y C++.

fw-context construye un índice semántico persistente a partir de compile_commands.json y el AST de libclang, y luego lo expone a los agentes de codificación a través de MCP. En lugar de reconstruir tu firmware mediante lecturas repetidas de archivos y búsquedas de texto, el agente puede consultar la estructura del programa producida por la configuración de build activa.

Ayuda a los agentes a responder preguntas como:

  • ¿Qué implementación está activa en este build?
  • ¿Quién llama a esta función, directa o indirectamente?
  • ¿Dónde está registrado este callback?
  • ¿Qué asignaciones de punteros a función pueden alcanzar este sitio de llamada?
  • ¿Qué código está excluido por el preprocesamiento?
  • ¿Qué se verá afectado si esta API cambia?
  • ¿Cómo fluye la ejecución desde una ISR hasta el código de aplicación?

El objetivo no es darle al modelo más código fuente. Es darle el contexto más pequeño y útil, consciente del build necesario para la tarea actual.

Resultados de una revisión de firmware real

En el caso de estudio de revisión de firmware incluido, fw-context se utilizó en un proyecto nRF52/Mbed OS que contiene aproximadamente 67,000 líneas de C y C++:

  • 115 archivos modificados revisados por 8 subagentes en paralelo
  • 19 hallazgos en seguridad de memoria, concurrencia, uso de API y código muerto
  • 9 hallazgos que dependían de relaciones semánticas no disponibles mediante búsqueda de texto ordinaria
  • aproximadamente 54,000 tokens de contexto utilizados por las consultas de fw-context
  • un estimado de 5.8 millones de tokens para el flujo de trabajo equivalente de grep y lectura de archivos

El caso de estudio incluye la salida de la revisión, la metodología y el análisis de tokens por herramienta para que las afirmaciones puedan ser inspeccionadas en lugar de tratarse como un benchmark de caja negra.

Inicio rápido

Requisitos previos

  • Python 3.11 o más reciente
  • libclang
  • un proyecto que pueda producir compile_commands.json
  • un agente de codificación compatible con MCP, como Claude Code u OpenCode

Ollama es opcional. Se utiliza solo para enriquecimiento semántico local y explicaciones de símbolos; el índice central derivado del compilador no lo requiere.

Instalar vía pip (recomendado)

pip install fw-context-mcp

Instalar la versión actual del código fuente

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

Registra fw-context con los agentes de codificación compatibles detectados en tu proyecto:

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

Compila e indexa el firmware:

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

Luego reinicia el agente de codificación y hazle preguntas sobre el proyecto. El índice es persistente e incremental; después de la ejecución inicial, las unidades de traducción modificadas se reprocesan en lugar de reconstruir todo el índice.

Consulta la Guía de inicio rápido y la Guía de instalación para la configuración específica de la plataforma y los sistemas de build compatibles.

Qué cambia fw-context

Sin un índice semántico del proyecto, un agente de codificación de IA generalmente comienza abriendo archivos, buscando nombres, siguiendo includes e intentando inferir relaciones que son implícitas en el build. En firmware embebido, esta reconstrucción suele ser la parte dominante de la tarea.

Ese enfoque puede fallar de maneras predecibles:

  • revisar archivos fuente que no forman parte del build activo
  • seguir la rama incorrecta del preprocesador
  • perder registros de callbacks y llamadas indirectas
  • seleccionar un driver o una implementación de plataforma inactivos
  • tratar declaraciones encontradas por búsqueda de texto como código alcanzable
  • consumir grandes cantidades de contexto en código de proveedor y archivos no relacionados

fw-context traslada gran parte de esa reconstrucción a un índice reutilizable derivado del compilador. El agente puede solicitar cuerpos de símbolos exactos, llamadores, llamados, referencias, macros activas, relaciones de callbacks, aristas de herencia y otra información específica sin leer árboles de código fuente completos.

Por qué el firmware embebido es diferente

En muchos proyectos a nivel de aplicación, los archivos fuente visibles en el repositorio están razonablemente cerca del programa que se ejecuta. Los proyectos embebidos en C y C++ suelen tener una brecha mucho mayor entre el árbol de código fuente y el programa resultante.

El firmware activo depende de factores como:

  • banderas del compilador y definiciones del preprocesador
  • configuración del objetivo, la placa y el producto
  • rutas de include y encabezados generados
  • selecciones de Kconfig y Devicetree
  • implementaciones seleccionadas de drivers y HAL
  • plantillas, herencia y despacho virtual
  • callbacks, manejadores de interrupciones y punteros a función
  • configuración del SDK del proveedor y del RTOS

Por lo tanto, un repositorio puede contener varias implementaciones plausibles del mismo subsistema, mientras que solo una se compila para el objetivo seleccionado. Un agente puede razonar de manera convincente sobre la implementación incorrecta a menos que primero reconstruya correctamente el contexto del build.

Cómo funciona

fw-context indexa el proyecto a través de la misma base de datos de compilación utilizada por las herramientas de build y los servidores de lenguaje.

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]

El índice contiene:

  • definiciones de símbolos, firmas, extensiones de código fuente y documentación
  • referencias, aristas de llamadas directas y rutas de llamadores recursivas
  • asignaciones de punteros a función y sitios de llamadas indirectas
  • registros de callbacks y relaciones de invocación
  • contenido de archivos activo y filtrado por preprocesador
  • valores de macros crudos y expandidos
  • herencia, overrides y relaciones de despacho virtual
  • metadatos de unidades de traducción y de proyecto/proveedor
  • embeddings opcionales y resúmenes generados por LLM

El servidor MCP expone esta información como consultas compactas de alto nivel optimizadas para uso repetido por un agente de IA.

Casos de uso típicos

  • revisión de commits de firmware consciente del build
  • trazado de la ejecución a través de ISRs, colas de trabajo, tareas y callbacks
  • localización de todos los llamadores y referencias de una API
  • identificación de la implementación seleccionada por el build actual
  • análisis de impacto antes de cambiar una firma de función o un tipo de datos
  • navegación en firmware desconocido sin leer archivos completos
  • búsqueda de candidatos a código muerto y símbolos sin referencias
  • separación del código del proyecto del código del SDK y del proveedor
  • reducción de texto fuente irrelevante enviado al modelo

fw-context es compatible con Zephyr, PlatformIO, Mbed OS, Arduino, ESP-IDF, CMake genérico, proyectos basados en Makefile y builds personalizados que puedan proporcionar una base de datos de compilación. Se documentan rutas de configuración adicionales para Keil, IAR, STM32CubeIDE y TI Code Composer Studio.

¿Por qué no usar simplemente clangd u otro LSP?

clangd ya utiliza comandos de compilación y es excelente para tareas orientadas al editor, como diagnósticos, autocompletado, ir a la definición y búsqueda de referencias. fw-context no lo reemplaza.

fw-context se dirige a una interfaz y una carga de trabajo diferentes:

  • datos persistentes de todo el proyecto preparados para consultas repetidas de agentes
  • herramientas MCP que devuelven contexto semántico compacto y estructurado
  • consultas recursivas de llamadores y análisis de impacto
  • modelado de relaciones de callbacks y punteros a función
  • contenido fuente activo adecuado para recuperación específica
  • clasificación de proyecto/proveedor y flujos de trabajo específicos de firmware
  • enriquecimiento en caché opcional compartido entre análisis repetidos

Usa clangd para edición interactiva. Usa fw-context cuando un agente de IA necesite contexto estructurado y reutilizable para revisar, comprender o navegar el firmware compilado.

Documentación

Madurez del proyecto

fw-context es funcional y se utiliza en proyectos reales de C y C++ embebido, pero sus interfaces y su comportamiento de indexación aún están evolucionando. Los informes de errores, resultados incorrectos, configuraciones de build no compatibles y casos límite reproducibles son particularmente valiosos.

El proyecto es local-first: el código fuente y el índice derivado del compilador permanecen en la máquina del desarrollador a menos que se configuren explícitamente servicios externos opcionales.

Antecedentes

El proyecto surgió de un modo de fallo recurrente en el trabajo de firmware asistido por IA: los agentes de codificación frecuentemente dedicaban más esfuerzo a reconstruir el programa activo que a razonar sobre la propia pregunta de ingeniería.

Para la explicación más extensa, lee: Por qué los agentes de codificación de IA siguen cometiendo los mismos errores al analizar firmware embebido

El compilador ya ha reconstruido tu programa. Deja que tu agente de codificación lo use.