TokenScope: Token-Aware Directory Explorer

TokenScope

面向大语言模型（LLM）的令牌感知目录浏览器。

Model Context Protocol (MCP) 服务，可帮助大模型高效浏览和理解代码库及目录结构。

概述

TokenScope 提供智能目录结构分析和令牌感知文件内容浏览功能，专为 Claude 等大模型设计。它通过以下方式帮助大模型理解代码库：

1. 通过令牌感知摘要浏览目录结构
2. 查看文件内容时兼顾令牌限制
3. 生成全面的目录报告

主要功能

令牌感知目录浏览

• 自动摘要大型目录，同时完整显示小型目录
• 遵守令牌限制，在限制范围内尽可能提供有用信息
• 内置安全保护，验证基础路径
• 智能筛选，支持默认模式和 .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. 在 mcpServers 部分添加 TokenScope：

"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"

提示词示例

以下是一些如何在 Claude 中使用 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 进行精确的 Token 计数