AI导哈

目录探索工具

TokenScope是一个为大型语言模型设计的智能目录结构分析和令牌感知文件内容探索工具，帮助LLMs高效理解代码库和目录结构。

  • by cdgaete
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 cdgaete/token-scope-mcp

使用说明

TokenScope

用于大型语言模型（LLM）的令牌感知目录资源管理器。

A. 模型上下文协议（MCP） 服务器，帮助LLM高效地探索和理解代码库和目录结构。

概述

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

  1. 使用令牌感知摘要探索目录结构
  2. 在考虑令牌限制的情况下查看文件内容
  3. 生成关于目录的综合报告

主要特点

令牌感知目录探索

  • 自动汇总 用于大目录，同时完整显示小目录
  • 尊重代币限制 在约束条件下最大限度地利用有用信息
  • 内置安全 具有基本路径验证
  • 智能过滤 具有默认模式和.gitignore支持
  • 准确的目录统计 即使是最大的目录

简单直观的工具

TokenScope仅提供三个核心工具：

  1. explore_directory -扫描并理解目录结构
  2. view_content -通过令牌感知访问文件内容
  3. generate_report -创建综合报告（可选择保存到文件）

安装

先决条件

  • Python 3.10或更高版本
  • 紫外线 （建议用于依赖关系管理）

安装（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"
    ]
  }
}

  1. 替换 /your/secure/base/path 使用您要限制操作的目录

  2. 保存配置文件并重新启动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许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

相关 MCP