FileScopeMCP

Сервер FileScopeMCP (протокол контекста модели)

✨ Мгновенно поймите и визуализируйте структуру и зависимости вашей кодовой базы! ✨

Инструмент на основе TypeScript для ранжирования файлов в вашей кодовой базе по важности, отслеживания зависимостей и предоставления сводок, помогающих понять структуру кода.

Обзор

Этот сервер MCP анализирует вашу кодовую базу, чтобы определить наиболее важные файлы на основе отношений зависимости. Он генерирует оценки важности (0-10) для каждого файла, отслеживает двунаправленные зависимости и позволяет вам добавлять пользовательские сводки для файлов. Вся эта информация становится доступной для инструментов ИИ через протокол контекста модели Cursor.

Функции

🚀 Усовершенствуйте свое понимание кода! FileScopeMCP предоставляет информацию напрямую вашему помощнику на основе искусственного интеллекта:

• 🎯 Анализ важности файлов
  • Ранжируйте файлы по шкале от 0 до 10 в зависимости от их роли в кодовой базе.
  • Рассчитайте важность, используя входящие/исходящие зависимости.
  • Мгновенно определяйте наиболее важные файлы в вашем проекте.
  • Интеллектуальный расчет учитывает тип файла, местоположение и значимость имени.
• 🔗 Отслеживание зависимости
  • Отобразите двунаправленные зависимости между файлами.
  • Определите, какие файлы импортируют данный файл (зависимые).
  • Посмотрите, какие файлы импортируются данным файлом (зависимости).
  • Различайте локальные и пакетные зависимости.
  • Поддержка нескольких языков: Python, JavaScript, TypeScript, C/C++, Rust, Lua, Zig.
• 📊 Визуализация
  • Создавайте диаграммы Mermaid для визуализации взаимосвязей файлов.
  • Цветовая визуализация на основе оценок важности.
  • Поддержка графов зависимостей, деревьев каталогов или гибридных представлений.
  • Вывод HTML со встроенным рендерингом, включая переключение тем и адаптивный дизайн.
  • Настройте глубину диаграммы, фильтруйте по важности и корректируйте параметры макета.
• 📝 Сводки файлов
  • Добавляйте в любой файл резюме, созданные человеком или искусственным интеллектом.
  • Извлекайте сохраненные сводки, чтобы быстро понять назначение файла.
  • Сводки сохраняются после перезапуска сервера.
• 📚 Поддержка нескольких проектов
  • Создавайте и управляйте несколькими деревьями файлов для различных областей проекта.
  • Настройте отдельные деревья с различными базовыми каталогами.
  • Легко переключайтесь между различными деревьями файлов.
  • Кэшированные деревья для более быстрых последующих операций.
• 💾 Постоянное хранилище
  • Все данные автоматически сохраняются на диск в формате JSON.
  • Загрузить существующие деревья файлов без повторного сканирования файловой системы.
  • Отслеживайте, когда в последний раз обновлялись файловые деревья.

Установка

1. Клонировать этот репозиторий
2. Создайте проект:Скрипт сборки установит все зависимости узлов и сгенерирует mcp.json.Окна:
   build.bat
   Скопируйте сгенерированную конфигурацию mcp.json в каталог .cursor вашего проекта:
   { "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: (Курсор в Windows, но ваш проект в Linux WSL, затем поместите MCP в Linux и выполните сборку)
   build.sh
   { "mcpServers": { "FileScopeMCP": { "command": "wsl", "args": ["-d", "Ubuntu-24.04", "/home/admica/FileScopeMCP/run.sh"], "transport": "stdio", "disabled": false, "alwaysAllow": [] } } }
3. Обновите путь arg --base-dir до базового пути вашего проекта.

Как это работает

Обнаружение зависимости

Инструмент сканирует исходный код на предмет наличия операторов импорта и других шаблонов, специфичных для данного языка:

• Python: import и from ... import
• JavaScript/TypeScript: операторы import и вызовы require()
• C/C++: директивы #include
• Rust: операторы use и mod
• Lua: require операторы
• Zig: директивы @import

Расчет важности

Файлам присваиваются баллы важности (0–10) на основе взвешенной формулы, которая учитывает:

• Количество файлов, импортирующих этот файл (зависимых)
• Количество файлов, которые импортирует этот файл (зависимости)
• Тип и расширение файла (при этом файлы TypeScript/JavaScript получают более высокие базовые баллы)
• Расположение в структуре проекта (файлы в src/ имеют больший вес)
• Именование файлов (файлы типа «index», «main», «server» и т. д. получают дополнительные баллы)

Файл, являющийся центральным в кодовой базе (импортируемый многими файлами), будет иметь более высокую оценку.

Генерация диаграмм

Система использует трехэтапный подход для генерации допустимого синтаксиса Mermaid:

1. Фаза сбора: регистрация всех узлов и связей.
2. Фаза определения узлов: создание определений для всех узлов перед любыми ссылками.
3. Фаза генерации ребер: создание ребер между определенными узлами.

Это гарантирует, что все диаграммы имеют правильный синтаксис и отображаются правильно. Вывод HTML включает:

• Адаптивный дизайн, работающий на любом устройстве
• Переключение между светлой и темной темой с определением системных настроек
• Клиентская визуализация Mermaid для оптимальной производительности
• Временная метка генерации

Нормализация пути

Система обрабатывает различные форматы путей для обеспечения единообразной идентификации файлов:

• Форматы путей Windows и Unix
• Абсолютные и относительные пути
• URL-кодированные пути
• Кроссплатформенная совместимость

Хранение файлов

Все данные файлового дерева хранятся в файлах JSON со следующей структурой:

• Метаданные конфигурации (имя файла, базовый каталог, метка времени последнего обновления)
• Полное дерево файлов с зависимостями, иждивенцами, оценками важности и сводками

Технические подробности

• TypeScript/Node.js : создан с использованием TypeScript для обеспечения безопасности типов и современных функций JavaScript.
• Протокол контекста модели : реализует спецификацию MCP для интеграции с курсором.
• Mermaid.js : использует синтаксис Mermaid для генерации диаграмм
• Хранилище JSON : использует простые файлы JSON для сохранения данных.
• Нормализация пути : кроссплатформенная обработка пути для поддержки Windows и Unix
• Кэширование : реализует кэширование для более быстрых повторяющихся операций.

Доступные инструменты

Сервер MCP предоставляет следующие инструменты:

Управление деревом файлов

• list_saved_trees : Список всех сохраненных деревьев файлов
• create_file_tree : Создать новую конфигурацию дерева файлов для определенного каталога
• select_file_tree : Выберите существующее дерево файлов для работы.
• delete_file_tree : Удалить конфигурацию дерева файлов

Анализ файла

• list_files : Список всех файлов в проекте с указанием их важности.
• get_file_importance : Получить подробную информацию о конкретном файле, включая зависимости и зависимые элементы
• find_important_files : поиск наиболее важных файлов в проекте на основе настраиваемых критериев
• read_file_content : Прочитать содержимое определенного файла
• recalculate_importance : Пересчитать значения важности для всех файлов на основе зависимостей

Сводки файлов

• get_file_summary : Получить сохраненную сводку определенного файла
• set_file_summary : Установить или обновить сводку определенного файла

Просмотр файлов

• toggle_file_watching : Включить/выключить наблюдение за файлами
• get_file_watching_status : Получить текущий статус наблюдения за файлом
• update_file_watching_config : Обновить конфигурацию отслеживания файлов

Генерация диаграмм

• generate_diagram : Создание диаграмм «Русалка» с настраиваемыми параметрами
  • Форматы вывода: текст русалки ( .mmd ) или HTML со встроенным рендерингом
  • Стили диаграмм: по умолчанию, зависимости, каталог или гибридные представления
  • Параметры фильтра: максимальная глубина, минимальный порог важности
  • Варианты компоновки: направление (TB, BT, LR, RL), расстояние между узлами, расстояние между рангами

Примеры использования

Самый простой способ начать — включить этот mcp в курсоре и сказать курсору разобраться и использовать его. Как только mcp запустится, он построит начальное дерево json. Скажите LLM сделать сводки всех важных файлов и использовать set_file_summary mcp для их добавления.

Анализ проекта

1. Создайте дерево файлов для вашего проекта:
   create_file_tree(filename: "my-project.json", baseDirectory: "/path/to/project")
2. Найдите самые важные файлы:
   find_important_files(limit: 5, minImportance: 5)
3. Получите подробную информацию о конкретном файле:
   get_file_importance(filepath: "/path/to/project/src/main.ts")

Работа с резюме

1. Прочитайте содержимое файла, чтобы понять его:
   read_file_content(filepath: "/path/to/project/src/main.ts")
2. Добавьте резюме в файл:
   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. Получить сводку позже:
   get_file_summary(filepath: "/path/to/project/src/main.ts")

Создание диаграмм

1. Создайте базовую схему структуры проекта:
   generate_diagram(style: "directory", maxDepth: 3, outputPath: "diagrams/project-structure", outputFormat: "mmd")
2. Создайте HTML-диаграмму с зависимостями:
   generate_diagram(style: "hybrid", maxDepth: 2, minImportance: 5, showDependencies: true, outputPath: "diagrams/important-files", outputFormat: "html")
3. Настройте макет диаграммы:
   generate_diagram(style: "dependency", layout: { direction: "LR", nodeSpacing: 50, rankSpacing: 70 }, outputPath: "diagrams/dependencies", outputFormat: "html")

Использование наблюдения за файлами

1. Включите наблюдение за файлами для вашего проекта:
   toggle_file_watching()
2. Проверьте текущий статус просмотра файла:
   get_file_watching_status()
3. Обновите конфигурацию отслеживания файлов:
   update_file_watching_config(config: { debounceMs: 500, autoRebuildTree: true, watchForNewFiles: true, watchForDeleted: true, watchForChanged: true })

Будущие улучшения

• Добавить поддержку большего количества языков программирования
• Добавить более сложные алгоритмы расчета важности
• Расширение возможностей настройки диаграммы
• Поддержка экспорта диаграмм в дополнительные форматы

Лицензия

Этот проект лицензирован в соответствии с GNU General Public License v3 (GPL-3.0). Полный текст лицензии см. в файле LICENSE .