MCP_context-mapper

# 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. 1. **Clonar y Construir**: ``` git clone https://github.com/gaboLectric/MCP_context-mapper cd context-mapper npm install npm run build ``` 2. **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): ```json { "mcpServers": { "context-mapper": { "command": "node", "args": ["/ruta/absoluta/a/context-mapper/dist/index.js"] } } } ``` 3. **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 `src` con profundidad 3"* * *"Analiza los imports de `src/index.ts` para 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: ```json { "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. 1. Reporta bugs. 2. Sugiere nuevas características (Soporte para Python/Go en camino). 3. Envía PRs. ## Licencia ISC