TokenScope

注意： 该包发布为 tokenscope，但出于历史原因，仓库名称仍为 directory-explorer-mcp。

一个用于支持令牌感知的目录探索和分析的 模型上下文协议 (MCP) 服务器，专为大型语言模型 (LLMs) 设计。

概览

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

1. 以高效的令牌摘要扫描目录结构
2. 以令牌意识提取和分析文件内容
3. 找到对理解代码库重要的文件
4. 生成包含相关信息的报告

功能

• 令牌感知的目录扫描

  • 递归地探索目录，可配置深度
  • 为大型目录提供智能摘要
  • 尊重 .gitignore 文件和自定义忽略模式

• 文件内容分析

  • 智能提取文件内容，尊重令牌限制
  • 对 JSON 和其他结构化文件进行特殊处理
  • 基于重要性优先选择文件

• 令牌使用统计

  • 估计处理目录所需的令牌数量
  • 按文件扩展名细分令牌使用情况
  • 识别占用大量令牌的文件

• 全面报告

  • 生成带有目录结构的 Markdown 报告
  • 包含令牌使用统计信息
  • 显示重要文件的样本

安装

先决条件

• Python 3.10 或更高版本
• uv（推荐用于简化依赖管理）

1. 主安装（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

2. 开发安装（从 GitHub）

对于贡献者或希望修改代码的用户：

# Clone the repository
git clone https://github.com/cdgaete/directory-explorer-mcp.git
cd directory-explorer-mcp

# Install development dependencies with uv
uv pip install -e ".[dev]"

以开发模式运行

# Run the server directly with uv
uv run --with fastmcp --with tiktoken server.py --base-path /path/to/allowed/directory

在 Claude Desktop 中配置开发版本

1. 定位 Claude Desktop 的配置文件

2. 在 mcpServers 部分添加带有开发路径的 TokenScope：

   "mcpServers": {
     "TokenScope (Dev)": {
       "command": "uv",
       "args": [
         "run",
         "--with",
         "fastmcp",
         "--with",
         "tiktoken",
         "/path/to/your/directory-explorer-mcp/server.py",
         "--base-path",
         "/your/secure/base/path"
       ]
     }
   }
   

3. 将 /path/to/your/directory-explorer-mcp/server.py 替换为实际的 server.py 文件路径

4. 将 /your/secure/base/path 替换为你的安全目录

安全特性

出于安全原因，--base-path 参数是必须的：

• 所有文件操作都会被验证以确保它们在指定目录内
• 试图访问或修改基本路径外的文件将被拒绝
• 基本路径在启动服务器时设置一次，并且不重启无法更改

示例提示

以下是一些如何使用 TokenScope 与 Claude 的示例：

Please scan my project directory at /path/to/project and tell me about its structure, focusing on the most important files.

Analyze the token usage in my project directory at /path/to/project and tell me how many tokens would be needed to process the entire codebase with an LLM.

Generate a comprehensive directory report about my project at /path/to/project, including structure, token statistics, and samples of the most important files.

可用工具

服务器提供以下 MCP 工具：

scan_directory_structure

扫描目录并以高效令牌的方式返回其结构。

extract_file_content

提取特定文件的内容，同时遵守令牌限制和格式。

search_files_by_pattern

在目录结构中搜索符合指定模式的文件。

analyze_token_usage

分析目录或文件的令牌使用情况，以估计 LLM 处理需求。

copy_file_to_destination

将文件从源路径复制到目标路径。

generate_directory_report

生成包含令牌统计信息的关于目录的综合 Markdown 报告。

许可证

此项目根据 MIT 许可证许可 - 详情请参阅 LICENSE 文件。

致谢

• 使用 FastMCP 构建
• 此概念最初在 repoai 中实现
• 受到了有效利用 LLM 分析代码库的需求启发