Servidor FileScopeMCP (Protocolo de contexto de modelo)

✨ ¡Comprende y visualiza al instante la estructura y las dependencias de tu base de código! ✨

Una herramienta basada en TypeScript para clasificar archivos en su base de código por importancia, rastrear dependencias y proporcionar resúmenes para ayudar a comprender la estructura del código.

Descripción general

Este servidor MCP analiza su código base para identificar los archivos más importantes según sus relaciones de dependencia. Genera puntuaciones de importancia (0-10) para cada archivo, rastrea las dependencias bidireccionales y permite agregar resúmenes personalizados. Toda esta información está disponible para las herramientas de IA a través del Protocolo de Contexto de Modelo de Cursor.

Características

¡ Mejora tu comprensión del código! FileScopeMCP proporciona información directamente a tu asistente de IA:

• Análisis de la importancia de los archivos

  • Clasifique los archivos en una escala de 0 a 10 según su función en la base del código.

  • Calcular la importancia utilizando dependencias entrantes/salientes.

  • Identifique instantáneamente los archivos más críticos de su proyecto.

  • El cálculo inteligente considera el tipo de archivo, la ubicación y la importancia del nombre.

• 🔗 Seguimiento de dependencias

  • Asignar relaciones de dependencia bidireccionales entre archivos.

  • Identificar qué archivos importan un archivo determinado (dependientes).

  • Vea qué archivos son importados por un archivo determinado (dependencias).

  • Distinguir entre dependencias locales y de paquete.

  • Soporte para múltiples idiomas: Python, JavaScript, TypeScript, C/C++, Rust, Lua, Zig.

• 📊 Visualización

  • Genere diagramas de sirena para visualizar las relaciones de archivos.

  • Visualización codificada por colores según puntuaciones de importancia.

  • Soporte para gráficos de dependencia, árboles de directorios o vistas híbridas.

  • Salida HTML con renderizado incorporado que incluye alternancia de temas y diseño responsivo.

  • Personalice la profundidad del diagrama, filtre por importancia y ajuste las opciones de diseño.

• 📝 Resúmenes de archivos

  • Agregue resúmenes generados por humanos o IA a cualquier archivo.

  • Recupere resúmenes almacenados para comprender rápidamente el propósito del archivo.

  • Los resúmenes persisten después de reiniciar el servidor.

• 📚 Soporte para múltiples proyectos

  • Cree y administre múltiples árboles de archivos para diferentes áreas del proyecto.

  • Configurar árboles separados con directorios base distintos.

  • Cambie entre diferentes árboles de archivos sin esfuerzo.

  • Árboles en caché para operaciones posteriores más rápidas.

• Almacenamiento persistente

  • Todos los datos se guardan automáticamente en el disco en formato JSON.

  • Cargue árboles de archivos existentes sin volver a escanear el sistema de archivos.

  • Realiza un seguimiento de cuándo se actualizaron por última vez los árboles de archivos.

Instalación

1. Clonar este repositorio

2. Construir el proyecto:

   El script de compilación instalará todas las dependencias del nodo y generará mcp.json para usted.

   Ventanas:

   build.bat

   Copie la configuración mcp.json generada al directorio .cursor de su proyecto:

   { "mcpServers": { "FileScopeMCP": { "command": "node", "args": ["<build script sets this>/mcp-server.js","--base-dir=C:/Users/admica/my/project/base"], "transport": "stdio", "disabled": false, "alwaysAllow": [] } } }

   Linux: (Cursor en Windows, pero su proyecto está en Linux WSL, luego coloque el MCP en Linux y compile)

   build.sh
   { "mcpServers": { "FileScopeMCP": { "command": "wsl", "args": ["-d", "Ubuntu-24.04", "/home/admica/FileScopeMCP/run.sh"], "transport": "stdio", "disabled": false, "alwaysAllow": [] } } }

3. Actualice la ruta arg --base-dir a la ruta base de su proyecto.

Cómo funciona

Detección de dependencia

La herramienta escanea el código fuente en busca de declaraciones de importación y otros patrones específicos del lenguaje:

• Python: declaraciones import y from ... import

• JavaScript/TypeScript: declaraciones import y llamadas require()

• C/C++: directivas #include

• Rust: declaraciones de use y mod

• Lua: declaraciones require

• Zig: directivas @import

Cálculo de importancia

A los archivos se les asignan puntajes de importancia (de 0 a 10) según una fórmula ponderada que considera:

• Número de archivos que importan este archivo (dependientes)

• Número de archivos que este archivo importa (dependencias)

• Tipo de archivo y extensión (los archivos TypeScript/JavaScript obtienen puntuaciones base más altas)

• Ubicación en la estructura del proyecto (los archivos en src/ tienen mayor ponderación)

• Nombre de archivo (archivos como 'index', 'main', 'server', etc. obtienen puntos adicionales)

Un archivo que sea central para la base del código (importado por muchos archivos) tendrá una puntuación más alta.

Generación de diagramas

El sistema utiliza un enfoque de tres fases para generar una sintaxis de sirena válida:

1. Fase de recopilación: Registrar todos los nodos y relaciones

2. Fase de definición de nodo: generar definiciones para todos los nodos antes de cualquier referencia

3. Fase de generación de bordes: crear bordes entre nodos definidos

Esto garantiza que todos los diagramas tengan una sintaxis válida y se representen correctamente. La salida HTML incluye:

• Diseño responsivo que funciona en cualquier dispositivo

• Alternancia de tema claro/oscuro con detección de preferencias del sistema

• Renderizado de sirena del lado del cliente para un rendimiento óptimo

• Marca de tiempo de generación

Normalización de trayectoria

El sistema maneja varios formatos de ruta para garantizar una identificación de archivos consistente:

• Formatos de ruta de Windows y Unix

• Rutas absolutas y relativas

• Rutas codificadas en URL

• Compatibilidad entre plataformas

Almacenamiento de archivos

Todos los datos del árbol de archivos se almacenan en archivos JSON con la siguiente estructura:

• Metadatos de configuración (nombre de archivo, directorio base, marca de tiempo de la última actualización)

• Árbol de archivos completo con dependencias, dependientes, puntuaciones de importancia y resúmenes

Detalles técnicos

• TypeScript/Node.js : Creado con TypeScript para seguridad de tipos y funciones modernas de JavaScript

• Protocolo de contexto de modelo : implementa la especificación MCP para la integración con Cursor

• Mermaid.js : utiliza la sintaxis de Mermaid para la generación de diagramas

• Almacenamiento JSON : utiliza archivos JSON simples para persistencia

• Normalización de rutas : manejo de rutas multiplataforma para compatibilidad con Windows y Unix

• Almacenamiento en caché : implementa el almacenamiento en caché para operaciones repetidas más rápidas

Herramientas disponibles

El servidor MCP expone las siguientes herramientas:

Gestión del árbol de archivos

• list_saved_trees : Lista todos los árboles de archivos guardados

• create_file_tree : crea una nueva configuración de árbol de archivos para un directorio específico

• select_file_tree : selecciona un árbol de archivos existente para trabajar con él

• delete_file_tree : Eliminar una configuración de árbol de archivos

Análisis de archivos

• list_files : enumera todos los archivos del proyecto con sus clasificaciones de importancia

• get_file_importance : obtiene información detallada sobre un archivo específico, incluidas las dependencias y los dependientes

• find_important_files : Encuentra los archivos más importantes del proyecto según criterios configurables

• read_file_content : Lee el contenido de un archivo específico

• recalculate_importance : recalcula los valores de importancia para todos los archivos en función de las dependencias

Resúmenes de archivos

• get_file_summary : obtiene el resumen almacenado de un archivo específico

• set_file_summary : Establece o actualiza el resumen de un archivo específico

Vigilancia de archivos

• toggle_file_watching : Activar o desactivar la vigilancia de archivos

• get_file_watching_status : obtener el estado actual de la vigilancia de archivos

• update_file_watching_config : Actualizar la configuración de vigilancia de archivos

Generación de diagramas

• generate_diagram : Crea diagramas de sirena con opciones personalizables

  • Formatos de salida: texto de sirena ( .mmd ) o HTML con renderizado incrustado

  • Estilos de diagrama: vistas predeterminadas, de dependencia, de directorio o híbridas

  • Opciones de filtro: profundidad máxima, umbral de importancia mínimo

  • Opciones de diseño: dirección (TB, BT, LR, RL), espaciado de nodos, espaciado de rango

Ejemplos de uso

La forma más sencilla de empezar es habilitar este mcp en cursor e indicarle que lo detecte y lo use. En cuanto se inicia el mcp, crea un árbol JSON inicial. Indica a un LLM que cree resúmenes de todos tus archivos importantes y usa la función set_file_summary del mcp para agregarlos.

Analizando un proyecto

1. Crea un árbol de archivos para tu proyecto:

   create_file_tree(filename: "my-project.json", baseDirectory: "/path/to/project")

2. Encuentra los archivos más importantes:

   find_important_files(limit: 5, minImportance: 5)

3. Obtenga información detallada sobre un archivo específico:

   get_file_importance(filepath: "/path/to/project/src/main.ts")

Trabajar con resúmenes

1. Leer el contenido de un archivo para comprenderlo:

   read_file_content(filepath: "/path/to/project/src/main.ts")

2. Añade un resumen al archivo:

   set_file_summary(filepath: "/path/to/project/src/main.ts", summary: "Main entry point that initializes the application, sets up routing, and starts the server.")

3. Recuperar el resumen más tarde:

   get_file_summary(filepath: "/path/to/project/src/main.ts")

Generando diagramas

1. Crear un diagrama de estructura básica del proyecto:

   generate_diagram(style: "directory", maxDepth: 3, outputPath: "diagrams/project-structure", outputFormat: "mmd")

2. Generar un diagrama HTML con relaciones de dependencia:

   generate_diagram(style: "hybrid", maxDepth: 2, minImportance: 5, showDependencies: true, outputPath: "diagrams/important-files", outputFormat: "html")

3. Personaliza el diseño del diagrama:

   generate_diagram(style: "dependency", layout: { direction: "LR", nodeSpacing: 50, rankSpacing: 70 }, outputPath: "diagrams/dependencies", outputFormat: "html")

Uso de la vigilancia de archivos

1. Habilite la vigilancia de archivos para su proyecto:

   toggle_file_watching()

2. Compruebe el estado actual de visualización de archivos:

   get_file_watching_status()

3. Actualizar la configuración de vigilancia de archivos:

   update_file_watching_config(config: { debounceMs: 500, autoRebuildTree: true, watchForNewFiles: true, watchForDeleted: true, watchForChanged: true })

Mejoras futuras

• Añadir soporte para más lenguajes de programación

• Añadir algoritmos de cálculo de importancia más sofisticados

• Mejorar las opciones de personalización del diagrama

• Soporte para exportar diagramas a formatos adicionales

Licencia

Este proyecto está licenciado bajo la Licencia Pública General GNU v3 (GPL-3.0). Consulte el archivo LICENSE para ver el texto completo de la licencia.