Mason – el constructor de contexto para LLMs 👷

Mason proporciona a los LLMs un mapa persistente de tu base de código para que dejen de explorar desde cero en cada sesión.

El problema: Cada vez que un LLM inicia una nueva conversación sobre tu código, utiliza grep, lee archivos y reconstruye la arquitectura, consumiendo tokens en un contexto que ya entendía ayer. En un proyecto de 164 archivos, responder "¿qué funciones tiene esta aplicación?" requiere leer más de 8 archivos a través de múltiples llamadas a herramientas.

La solución de Mason: Un mapa conceptual que persiste entre sesiones. Una llamada a la herramienta devuelve una tabla de búsqueda de funciones a archivos: el LLM sabe exactamente dónde buscar, sin necesidad de explorar.

Resultado medido (deepeval, Claude Sonnet, proyecto KMP de 164 archivos):

La misma calidad de respuesta (0.9/1.0 en todas las pruebas, ambos caminos). Reproducir: bench/.

Inicio rápido

claude mcp add mason --scope user -- npx -p mason-context mason-mcp

Reinicia Claude Code y luego pregunta: "use mason to analyze this project and create a snapshot."

Eso es todo: Mason analizará tu base de código y creará un mapa conceptual. En la siguiente sesión, cargará el mapa en lugar de volver a explorar todo.

Related MCP server: ontomics

Cómo funciona

Mapa conceptual

La función principal de Mason. Persiste un mapa de funciones a archivos en .mason/snapshot.json que sobrevive a las conversaciones. Cuando el LLM necesita entender tu proyecto, lee este mapa en lugar de buscar mediante grep en toda tu base de código:

{
  "features": {
    "home screen": {
      "files": ["HomeScreen.kt", "HomeViewModel.kt", "GetWeatherDataUseCase.kt"]
    }
  },
  "flows": {
    "weather fetch": {
      "chain": ["HomeViewModel.kt", "WeatherRepositoryImpl.kt", "WeatherServiceImpl.kt"]
    }
  }
}

El mapa es generado por el propio LLM: Mason proporciona las herramientas de análisis y el LLM interpreta tu código para decidir cuáles son las funciones y los flujos. Esto significa que el mapa captura la comprensión arquitectónica, no solo listados de archivos.

Crea uno pidiéndole a tu asistente de IA que "create a mason snapshot", o mediante la CLI:

mason set-llm gemini          # configure a provider (no API key needed)
mason snapshot ~/my-project   # generate concept map
mason snapshot --install-hook # auto-update on every commit

Análisis de impacto de cambios

Antes de editar un archivo, Mason puede decirte qué más podría verse afectado. Combina tres señales que requerirían múltiples llamadas a herramientas para recopilar manualmente:

• Historial de cambios conjuntos — archivos que históricamente cambian juntos en los commits de git

• Referencias — archivos que importan o mencionan el objetivo por su nombre

• Pruebas relacionadas — archivos de prueba emparejados con el objetivo por convención de nombres

mason impact WeatherRepository.kt -d ~/my-project

También disponible como la herramienta MCP get_impact: pídele a tu asistente "what would be affected if I changed WeatherRepository?"

Análisis del historial de Git

Mason agrega cientos de commits en estadísticas procesables: qué archivos cambian con más frecuencia (archivos "calientes" con los que debes tener cuidado), qué directorios no se han tocado en meses (código potencialmente obsoleto) y qué convenciones de commit sigue el equipo. Este es el tipo de análisis que requeriría docenas de llamadas a git log para calcular manualmente.

mason analyze ~/my-project

Herramientas MCP

Mason expone 6 herramientas a través del Protocolo de Contexto de Modelo (MCP). Cualquier cliente compatible con MCP (Claude Code, Cursor, etc.) puede usarlas:

Uso de la CLI

Mason también funciona como una CLI independiente para generar archivos CLAUDE.md y ejecutar análisis sin un cliente MCP. Configura un proveedor de LLM una vez y luego usa cualquier comando:

mason set-llm claude|gemini|ollama|openai  # configure provider
mason generate                # analyze codebase + LLM -> CLAUDE.md
mason analyze                 # git stats only (no LLM needed)
mason impact File.kt          # change impact analysis
mason snapshot                # create/update concept map

La mayoría de los proveedores funcionan sin una clave API: claude, gemini y ollama utilizan sus respectivas CLI directamente.

Seguridad

Qué contiene la instantánea: Nombres de funciones, rutas de archivos relativas y descripciones de flujos. Sin código fuente, secretos ni lógica de negocio.

Qué no toca: Mason respeta .gitignore (a través de git ls-files) y tiene una lista de denegación que bloquea .env, .pem, .key, credenciales y otros archivos confidenciales para que no sean muestreados. La protección contra el recorrido de rutas garantiza que todo el acceso a archivos permanezca dentro de la raíz del proyecto.

Flujo de datos del LLM: Generar una instantánea a través de la CLI envía contenidos de archivos muestreados a tu proveedor de LLM configurado, de la misma manera que cualquier asistente de codificación de IA lee tu código. Usa ollama para una generación totalmente local. Las herramientas del servidor MCP (get_snapshot, get_impact, etc.) solo leen archivos locales.

Soporte de idiomas

Mason es completamente agnóstico al lenguaje. Utiliza patrones de nombres de archivos e historial de git en lugar de análisis específico del lenguaje, por lo que funciona con cualquier proyecto que tenga archivos fuente y un repositorio git: TypeScript, Kotlin, Python, Go, Rust, Swift, Java, C#, Dart y más.

Licencia

MIT