Directory Explorer MCP Server

TokenScope

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

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

概述

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

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

特征

• 令牌感知目录扫描
  • 以可配置的深度递归探索目录
  • 为大型目录提供智能摘要
  • 尊重 .gitignore 文件和自定义忽略模式
• 文件内容分析
  • 智能提取符合令牌限制的文件内容
  • JSON 和其他结构化文件的特殊处理
  • 根据重要性确定文件选择优先级
• 代币使用情况统计
  • 估计处理目录所需的令牌
  • 按文件扩展名细分令牌使用情况
  • 识别包含大量标记的文件
• 综合报告
  • 生成具有目录结构的 Markdown 报告
  • 包括代币使用情况统计
  • 显示重要文件的示例

安装

先决条件

• Python 3.10 或更高版本
• uv （推荐用于轻松的依赖管理）

1.主要安装（PyPI）

对于只想使用 TokenScope 的大多数用户来说，这是推荐的方法：

运行 TokenScope

出于安全原因， --base-path参数是必需的。它将所有文件操作限制在指定的目录中。

在 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）

对于想要修改代码的贡献者或用户：

以开发模式运行

在 Claude Desktop 中配置开发版本

1. 找到 Claude Desktop 的配置文件
2. 将 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" ] } }
3. 将/path/to/your/directory-explorer-mcp/server.py替换为 server.py 文件的实际路径
4. 将/your/secure/base/path替换为您的安全目录

安全功能

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

• 所有文件操作都经过验证，以确保它们位于指定的目录中
• 访问或修改基本路径之外的文件的尝试将被拒绝
• 启动服务器时设置一次基本路径，如果不重新启动则无法更改

示例提示

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

可用工具

该服务器提供以下 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 高效分析代码库的需求的启发