TokenScope

**注意：**此包作为tokenscope发布，但由于历史原因，存储库名称仍为directory-explorer-mcp 。

专为大型语言模型 (LLM) 设计的用于标记感知目录探索和分析的模型上下文协议 (MCP)服务器。

概述

TokenScope 提供智能目录结构分析和基于 token 的文件内容探索功能。它通过以下方式帮助像 Claude 这样的法学硕士 (LLM) 理解代码库和目录结构：

使用标记高效摘要扫描目录结构
使用令牌感知提取和分析文件内容
查找对代码库理解重要的文件
生成包含相关信息的报告

特征

令牌感知目录扫描
- 以可配置的深度递归探索目录
- 为大型目录提供智能摘要
- 尊重 .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 中配置

找到 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

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 中配置开发版本

找到 Claude Desktop 的配置文件
将 TokenScope 添加到具有开发路径的mcpServers部分：
"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" ] } }
将/path/to/your/directory-explorer-mcp/server.py替换为 server.py 文件的实际路径
将/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 高效分析代码库的需求的启发

Directory Explorer MCP Server

Integrations