TokenScope

Проводник каталогов с поддержкой токенов для больших языковых моделей (LLM).

Сервер протокола контекста модели (MCP) , который помогает магистрам уровня магистра эффективно исследовать и понимать кодовые базы и структуры каталогов.

Обзор

TokenScope обеспечивает интеллектуальный анализ структуры каталогов и токен-ориентированное исследование содержимого файлов, разработанное для LLM, таких как Клод. Он помогает LLM понимать кодовые базы с помощью:

Изучение структур каталогов с помощью токен-ориентированного суммирования
Просмотр содержимого файла с учетом ограничений токенов
Формирование комплексных отчетов по каталогам

Related MCP server: Compiler Explorer MCP

Основные характеристики

Исследование каталога с использованием токенов

Автоматическое суммирование для больших каталогов с одновременным отображением небольших каталогов в полном объеме
Соблюдение ограничений токенов для максимизации полезной информации в рамках ограничений
Встроенная безопасность с проверкой базового пути
Умная фильтрация с шаблонами по умолчанию и поддержкой .gitignore
Точная статистика каталогов даже для самых крупных каталогов

Простые, интуитивно понятные инструменты

TokenScope предоставляет всего три основных инструмента:

explore_directory — сканирование и понимание структур каталогов
view_content — доступ к содержимому файла с использованием токенов
generate_report - Создание подробных отчетов (с возможностью сохранения в файл)

Установка

Предпосылки

Python 3.10 или выше
uv (рекомендуется для управления зависимостями)

Установка (PyPI)

Это рекомендуемый метод для большинства пользователей, которые просто хотят использовать TokenScope:

# Install from PyPI using uv (recommended) uv pip install tokenscope

Запуск TokenScope

Аргумент --base-path является обязательным по соображениям безопасности. Он ограничивает все файловые операции указанным каталогом.

# Run using the installed package uv run --with tokenscope tokenscope --base-path /path/to/allowed/directory

Настройка в Claude Desktop

Найдите файл конфигурации Claude Desktop (обычно ~/.config/claude/config.json )
Добавьте TokenScope в раздел mcpServers :

"mcpServers": { "TokenScope": { "command": "uv", "args": [ "run", "--with", "tokenscope", "tokenscope", "--base-path", "/your/secure/base/path" ] } }

Замените /your/secure/base/path на каталог, операции в котором вы хотите ограничить.
Сохраните файл конфигурации и перезапустите Claude Desktop.

Использование

Запуск сервера TokenScope

Аргумент --base-path необходим для безопасности (он ограничивает файловые операции указанным каталогом):

tokenscope --base-path /path/to/allowed/directory

Тестирование инструментов напрямую

TokenScope включает тестовый режим для непосредственного тестирования инструментов:

# Test directory exploration tokenscope --base-path /path/to/allowed/directory --test "explore:/path/to/directory" # Test with custom ignore patterns tokenscope --base-path /path/to/allowed/directory --test "explore:/path/to/directory?ignore=cache,*.log,tmp/&gitignore=false" # Test file viewing tokenscope --base-path /path/to/allowed/directory --test "view:/path/to/file" # Test report generation tokenscope --base-path /path/to/allowed/directory --test "report:/path/to/directory" # Test report generation with file output and custom ignore patterns tokenscope --base-path /path/to/allowed/directory --test "report:/path/to/directory?ignore=*.bak,temp/ > /path/to/output.md"

Примеры подсказок

Вот несколько примеров использования TokenScope с Клодом:

Could you explore my project directory at /path/to/project and tell me about its structure?

Can you show me the content of the file at /path/to/file.py?

Please generate a comprehensive report about my project at /path/to/project and save it to /path/to/report.md

Точная статистика каталога

TokenScope теперь предоставляет два уровня информации о каталогах:

Статистика быстрого сканирования : информация о файлах и каталогах, отображаемых в древовидной структуре.
Полная статистика каталога : полный подсчет ВСЕХ файлов и каталогов, даже в очень больших репозиториях.

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

Пример вывода

QUICK SCAN STATISTICS (files visible in tree): Files shown in tree: 47 Directories shown in tree: 16 Size shown in tree: 185.9 MB FULL DIRECTORY STATISTICS (all files): Total files: 16,059 Total directories: 8 Total disk size: 2.1 GB

Умная фильтрация с игнорированием шаблонов

TokenScope автоматически отфильтровывает общие каталоги и файлы, которые обычно не способствуют пониманию кодовой базы:

Игнорируемые по умолчанию шаблоны : .git/ , .venv/ , venv/ , __pycache__/ , node_modules/ , build/ , dist/ и т. д.
Пользовательские шаблоны игнорирования : вы можете указать дополнительные шаблоны для игнорирования с помощью параметра ignore_patterns
Поддержка .gitignore : TokenScope может автоматически учитывать файлы .gitignore в сканируемых каталогах.

Эта функция помогает предотвратить трату токенов на ненужные файлы и каталоги, такие как:

Каталоги зависимостей (например, node_modules , виртуальные среды)
Создание артефактов и кэширование каталогов
Метаданные контроля версий
Файлы конфигурации IDE

Использование шаблонов игнорирования в тестовом режиме CLI

# Ignore specific patterns tokenscope --base-path /path --test "explore:/code?ignore=*.log,temp/" # Disable .gitignore processing tokenscope --base-path /path --test "explore:/code?gitignore=false" # Both together tokenscope --base-path /path --test "explore:/code?ignore=*.tmp&gitignore=false"

Функции безопасности

TokenScope включает в себя важные функции безопасности:

Все файловые операции проверяются, чтобы убедиться, что они находятся в указанном базовом каталоге.
Попытки доступа к файлам за пределами базового пути отклоняются.
Базовый путь задается один раз при запуске сервера и не может быть изменен без перезапуска.

Лицензия

Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE.

Благодарности

Создано с помощью FastMCP
Использует tiktoken для точного подсчета токенов

TokenScope

TokenScope

Обзор

Основные характеристики

Исследование каталога с использованием токенов

Простые, интуитивно понятные инструменты

Установка

Предпосылки

Установка (PyPI)

Запуск TokenScope

Настройка в Claude Desktop

Использование

Запуск сервера TokenScope

Тестирование инструментов напрямую

Примеры подсказок

Точная статистика каталога

Пример вывода

Умная фильтрация с игнорированием шаблонов

Использование шаблонов игнорирования в тестовом режиме CLI

Функции безопасности

Лицензия

Благодарности

Resources

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API