TokenScope 注意： 该包发布为 tokenscope，但出于历史原因，仓库名称仍为 directory-explorer-mcp。 一个用于支持令牌感知的目录探索和分析的 模型上下文协议 (MCP) 服务器，专为大型语言模型 (LLMs) 设计。 概览 TokenScope 提供智能的目录结构分析和令牌感知的文件内容探索。它通过以下方式帮助像 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 的配置文件 在 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" ] \} \} 将 /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 分析代码库的需求启发