Сервер 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 .