ContextBridge

Recuperación de código local para agentes de IA: reduce el contexto del código base de miles de tokens a unos pocos cientos, con cero rutas de archivo alucinadas.

GitHub

Prueba este MCPPatrocinado

Documentación

ContextBridge

¿Por qué ContextBridge?

Sin CB, un agente de codificación de IA o adivina qué archivos son relevantes, o pegas archivos fuente completos en el chat — quemando miles de tokens de entrada en código que no se necesita.

Con CB, la IA llama a una sola herramienta MCP y obtiene un resultado compacto y clasificado: el archivo propietario, archivos relacionados, símbolos clave y un resumen de dependencias — típicamente unos pocos cientos de tokens en lugar de decenas de miles de líneas de código fuente sin procesar.

Esto no se limita a investigaciones de errores — la misma herramienta responde preguntas generales sobre cómo se implementa una característica o flujo de trabajo existente.

Sin CB	Con CB
Pegar 10–50 archivos sin procesar en el contexto	CB devuelve los 3–5 archivos que realmente importan
La IA adivina qué código es relevante	El resultado se basa en la estructura real de tu código
Alto costo de tokens, contexto ruidoso	Bajo costo de tokens, contexto enfocado
Rutas de archivo y nombres de métodos alucinados	Rutas de archivo, símbolos y pistas de línea exactos

La etapa opcional de análisis de IA local comprime aún más el resultado antes de que llegue a tu IA en la nube — así pagas incluso menos.

Nota de alcance: ContextBridge es una herramienta de enrutamiento y recuperación de código, no un motor de razonamiento — encuentra los archivos, símbolos y conexiones correctos, pero no prueba causalidad ni elige la solución por ti. Consulta Alcance previsto para conocer el límite completo.

💡 ¿Nuevo aquí? ¿No quieres leer todo? Pide a tu asistente de IA (Claude, ChatGPT, Gemini, etc.) que lea la carpeta docs/ y te guíe en la configuración para tu sistema operativo y proyecto.

Una capa de recuperación de código local-first para agentes de codificación de IA. ContextBridge indexa tu código (a través de la salida de Graphify) y luego expone herramientas MCP que cualquier cliente de IA (Claude Code, Codex, Cursor, Antigravity, …) puede llamar para obtener archivos, símbolos y cadenas de dependencia clasificados — opcionalmente validados y re-clasificados por un LLM local antes de que la respuesta llegue a tu IA en la nube.

Your prompt ─► ContextBridge (keyword + vector retrieval)
            ─► Local AI (optional: validates, re-ranks, fills gaps)
            ─► Your AI agent (implements, grounded in real files)

El motor es genérico. Toda la clasificación específica del proyecto vive en un complemento de perfil intercambiable, por lo que la misma herramienta funciona para cualquier código.

Arquitectura

Cómo fluye tu código a través de ContextBridge hasta tu agente de IA:

ContextBridge architecture and data flow

Panel de control

ContextBridge incluye un panel de control local para monitorear la calidad de recuperación, la salud del índice y la configuración, sin dependencia de la nube.

ContextBridge dashboard overview
Resumen — calidad de recuperación, ahorro de tokens y desglose por modo de búsqueda

ContextBridge dashboard settings
Configuración — ajusta el modo de pipeline, los pesos RAG y la configuración del modelo en vivo

Token savings breakdown modal
Ahorro de tokens — desglose por consulta de lo que CB entregó vs. el costo de archivo completo

📖 Antes de empezar — lee la documentación. La carpeta docs/ contiene todo lo necesario para la configuración completa, configuración, pipeline y creación de perfiles. Comienza con docs/0. README.md para un índice guiado de toda la documentación.

Inicio rápido

:: 1. Install deps + build the index + scaffold config files
context_bridge\setup\windows\setup_context_bridge.bat

:: 2. Point the config at YOUR source folders
::    edit config.hybrid.json  ->  settings.discovery.*  (replace your_backend / your_frontend)

:: 3. Re-run setup to index your code
context_bridge\setup\windows\setup_context_bridge.bat

:: 4. Start the server + dashboard (pick Hybrid / Semantic / Keyword)
context_bridge\setup\windows\1.  start_Context_Bridge.bat

Mac/Linux: usa equivalentes de context_bridge/setup/mac/ o context_bridge/setup/linux/.

La configuración es re-ejecutable y segura: crea archivos de configuración/inicio a partir de las plantillas *.example solo si faltan (nunca sobrescribe tus ediciones) y reconstruye el índice en cada ejecución. Ejecuta setup_context_bridge.bat --force para restablecer las configuraciones a las plantillas.

El servidor MCP ejecuta SSE por defecto en http://127.0.0.1:8755/sse — apunta tu cliente de IA allí. El transporte Stdio también es compatible (establece CONTEXT_BRIDGE_TRANSPORT=stdio antes de iniciar) para clientes que no soportan SSE; se recomienda SSE ya que permite que múltiples clientes de IA compartan un servidor en ejecución en lugar de que cada uno genere su propio proceso. Panel de control: http://127.0.0.1:8795. Las estadísticas en vivo pueden retrasarse hasta ~15 segundos respecto a la actividad más reciente, y las listas de historial (eventos recientes, archivos omitidos, consultas fallidas) muestran las 1000 entradas más recientes en lugar del registro completo de por vida — ambos son compensaciones de rendimiento intencionales, no pérdida de datos.

Modos de recuperación

Elegido al inicio (el script de inicio selecciona el archivo de configuración correspondiente):

Modo	Configuración	Qué hace
Híbrido	`config.hybrid.json`	Palabras clave primero + asistencia vectorial protegida (recomendado)
Semántico	`config.semantic.json`	Solo vectorial (necesita `sentence-transformers`)
Palabras clave	`config.json`	Solo palabras clave, sin vectores

Herramientas MCP

Herramienta	Uso
`search_context_hybrid()`	Principal — descubrimiento amplio de archivos + contexto (ejecuta análisis automáticamente)
`find_code_locations()`	Archivo propietario / símbolo / línea exactos para un método o clase
`get_module_summary()`	Resumen de un módulo/servicio
`get_graphify_pack()`	Todos los archivos en un paquete de características
`record_outcome()`	Registrar si un resultado fue útil
`health_check()`, `get_usage_summary()`, `search_context()`, `find_related_files()`	Utilidad

Qué herramientas aparecen está controlado por la configuración — si una herramienta está registrada, es seguro llamarla.

Escribiendo tu propio perfil

El motor genérico solicita un perfil para la clasificación específica del proyecto en cada paso. Sin perfil (project_profile: "default") obtienes una puntuación genérica pura.

Copia rules/projects/example_profile.py → rules/projects/<yourapp>_profile.py
Implementa los hooks que necesites (cada hook es opcional — los hooks omitidos se convierten en no-op)
Actívalo: establece CONTEXT_BRIDGE_PROFILE=<yourapp> en tu script de inicio, o project_profile: "<yourapp>" en tu configuración

Hooks de perfil (todos opcionales)

Hook	Propósito
`expand_query_tokens(query, tokens)`	Agregar tokens de búsqueda adicionales
`module_intent_tokens()`	Mapear nombre de módulo → vocabulario
`pinned_owner_files(query_tokens)`	Forzar archivos específicos a la parte superior
`adjust_document_score(...)`	Aumentar/penalizar un documento candidato
`adjust_owner_score(...)`	Aumentar/penalizar un archivo propietario por nombre
`adjust_primary_owner_score(...)`	Empujar al propietario principal único
`adjust_scoped_score(...)`	Preferir archivos bajo el módulo/paquete dominante
`extra_owner_file_patterns()`	Patrones de nombres de archivo adicionales de alta prioridad
`infer_module_from_path(path)`	Ruta → nombre de módulo (alcance de fusión)
`low_signal_terms()`	Palabras de módulo/dominio a tratar como de baja señal
`noise_files()`	Nombres de archivo a de-priorizar (ui/soporte/raíz)
`gap_queries()`	Palabras desencadenantes → consulta de re-búsqueda limpia
`analysis_prompt_override()`	Prompt de sistema completo para la IA local
`pack_files_for_intents(...)`	Mapear intenciones → archivos de paquete Graphify (avanzado)

Consulta docs/ para guías extendidas sobre configuración, pipeline, creación de perfiles y comandos de depuración.

Indexación

ContextBridge indexa la salida de Graphify (graph.json, GRAPH_REPORT.md, source-files.txt, scope-summary.md, manifest.json) más documentos /behavior/ — no el código fuente. Genera Graphify para tu proyecto, apunta settings.discovery.* a esas carpetas y ejecuta la configuración. Vuelve a ejecutar la configuración después de cada actualización de Graphify para refrescar el índice.

IA local (opcional)

Configura un modelo local bajo pipeline.analysis_stage (proveedor ollama por defecto, o anthropic/openai/openrouter). Cuando está habilitado, valida y re-clasifica los resultados de CB, descompone prompts de múltiples temas y dispara re-búsquedas de brechas — luego pasa un resultado compacto y fundamentado a tu IA en la nube. Cambia los modelos modificando solo model; los prompts son independientes del modelo.

Licencia

Licenciado bajo la Licencia Apache, Versión 2.0.