AI导哈

项目结构映射工具

Context Mapper是一个轻量级本地服务器，帮助AI代理快速理解项目结构和依赖关系，支持代码探索、依赖分析和智能导航。

  • by gaboLectric
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 gaboLectric/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):

    {
  "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:

{
  "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

相关 MCP