Context Mapper MCP
Context Mapper es tu aliado para que los Agentes de IA entiendan tu proyecto al instante. Olvídate de copiar y pegar miles de líneas de código o de que el agente pierda el contexto.
Diseñado para ser ligero, rápido y ejecutarse localmente, este servidor MCP permite a cualquier asistente (como Claude Desktop o extensiones de IDE) "ver" la estructura de tu proyecto y entender sus dependencias sin leer cada archivo.
Perfecto Para
- Exploración Rápida: Entiende la arquitectura de un proyecto nuevo en segundos.
- Mapeo de Dependencias: Visualiza qué archivos dependen de cuáles librerías.
- Agentes Autónomos: Dale a tu IA la capacidad de navegar tu código con inteligencia.
- Ahorro de Tokens: Evita enviar todo el código al contexto; envía solo lo que importa.
Quick Start
Requisitos
- Node.js instalado.
- Un cliente MCP (ej: Claude Desktop).
Instalación y Ejecución
No necesitas instalar nada globalmente si no quieres. Simplemente clona este repositorio, construye y conecta.
- Clonar y Construir:
git clone https://github.com/gaboLectric/MCP_context-mapper
cd context-mapper
npm install
npm run build- Configurar en Claude Desktop:
Edita tu archivo de configuración de Claude (usualmente en ~/Library/Application Support/Claude/claude_desktop_config.json en Mac o %APPDATA%\Claude\claude_desktop_config.json en Windows):
{
"mcpServers": {
"context-mapper": {
"command": "node",
"args": ["/ruta/absoluta/a/context-mapper/dist/index.js"]
}
}
}- Listo. Reinicia Claude y verás las nuevas herramientas disponibles.
Características
Core Capabilities
| Herramienta | Descripción | Caso de Uso |
|---|---|---|
get_file_structure | Vista de Árbol: Genera una representación visual de tus carpetas, ignorando ruido como node_modules. Ahora con límites de profundidad y archivos para ahorrar tokens. | "¿Cuál es la estructura de este proyecto?", "Muéstrame los controladores". |
analyze_imports | Analizador de Dependencias: Extrae imports de JS/TS/Python/Go. Filtra por local o library para foco selectivo. | "¿Qué librerías usa App.tsx?", "¿De dónde sale este componente?". |
get_file_summary | Lectura Parcial: Lee archivos grandes por chunks (startLine + maxLines). Evita cargar archivos de 1000+ líneas completos. | "Muéstrame líneas 50-100 de utils.ts", "Lee las primeras 50 líneas". |
search_symbols | Búsqueda de Símbolos: Encuentra funciones, clases, interfaces por nombre o patrón regex. Soporta JS/TS/Python/Go. | "¿Dónde está definida getUser?", "Busca clases que implementen Handler". |
get_project_metadata | Detección de Proyecto: Detecta automáticamente el stack (React/Node/Python/Go), entry points y dependencias. | "¿Qué tipo de proyecto es este?", "¿Cuáles son las dependencias principales?". |
build_import_graph | Grafo de Dependencias: Construye grafo de imports entre archivos. Detecta dependencias circulares y archivos más acoplados. Usa caché persistente para proyectos grandes. | "¿Qué archivos dependen de utils.ts?", "¿Hay dependencias circulares?", "¿Cuál es el archivo más acoplado?". |
Consultas de Ejemplo que Funcionan
- *"Dame una vista general de la carpeta
srccon profundidad 3"* - *"Analiza los imports de
src/index.tspara ver sus dependencias"* - *"Explícame la arquitectura basándote en la estructura de archivos"*
Configuración Avanzada
Archivo de Configuración context-mapper.json
Crea un archivo context-mapper.json en la raíz de tu proyecto para personalizar el comportamiento:
{
"ignoredFolders": ["node_modules", ".git", "dist", "build"],
"ignoredExtensions": [".png", ".jpg", ".pdf"],
"maxDepth": 5,
"maxFiles": 100,
"maxResults": 50,
"cacheEnabled": true,
"cacheTTLMinutes": 60
}| Opción | Descripción |
|---|---|
ignoredFolders | Carpetas adicionales a ignorar durante el escaneo |
ignoredExtensions | Extensiones de archivo a ignorar |
maxDepth | Profundidad máxima de recursión (default: 5) |
maxFiles | Máximo archivos a listar por directorio (default: 100) |
cacheEnabled | Habilitar caché persistente en disco (default: true) |
cacheTTLMinutes | Tiempo de vida del caché en minutos (default: 60) |
Caché Persistente
El MCP ahora guarda análisis de proyectos grandes en ~/.cache/context-mapper/:
- Import Graphs: Se cachean automáticamente para reinicios instantáneos
- TTL configurable: Por defecto 60 minutos, ajustable vía config
- Por proyecto: El caché se identifica por hash único del path del proyecto
Flujo Optimizado para Agentes
1. get_project_metadata() → Detectar stack (10 tokens)
2. get_file_structure(depth=2) → Overview de estructura (50-100 tokens)
3. build_import_graph(format="cycles") → Detectar problemas de arquitectura
4. search_symbols(pattern="*") → Encontrar definiciones relevantes
5. get_file_summary(chunk) → Leer solo lo necesario (~100 tokens vs 5000+)Reducción típica de tokens: 95-99% vs leer archivos completos.
Contribuyendo
Las contribuciones son bienvenidas.
- Reporta bugs.
- Sugiere nuevas características (Soporte para Python/Go en camino).
- Envía PRs.
Licencia
ISC