TokenScope

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

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

Обзор

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

1. Изучение структур каталогов с помощью токен-ориентированного суммирования

2. Просмотр содержимого файла с учетом ограничений токенов

3. Формирование комплексных отчетов по каталогам

Related MCP server: Compiler Explorer MCP

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

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

• Автоматическое суммирование для больших каталогов с одновременным отображением небольших каталогов в полном объеме

• Соблюдение ограничений токенов для максимизации полезной информации в рамках ограничений

• Встроенная безопасность с проверкой базового пути

• Умная фильтрация с шаблонами по умолчанию и поддержкой .gitignore

• Точная статистика каталогов даже для самых крупных каталогов

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

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

1. explore_directory — сканирование и понимание структур каталогов

2. view_content — доступ к содержимому файла с использованием токенов

3. 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

1. Найдите файл конфигурации Claude Desktop (обычно ~/.config/claude/config.json )

2. Добавьте TokenScope в раздел mcpServers :

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

3. Замените /your/secure/base/path на каталог, операции в котором вы хотите ограничить.

4. Сохраните файл конфигурации и перезапустите 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 теперь предоставляет два уровня информации о каталогах:

1. Статистика быстрого сканирования : информация о файлах и каталогах, отображаемых в древовидной структуре.

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

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

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

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 для точного подсчета токенов