TokenScope
TokenScope 是用于大型语言模型的令牌感知目录浏览器。
专为大型语言模型 (LLM) 设计的用于标记感知目录探索和分析的模型上下文协议 (MCP)服务器。
概述
TokenScope 提供智能目录结构分析和基于 token 的文件内容探索功能。它通过以下方式帮助像 Claude 这样的法学硕士 (LLM) 理解代码库和目录结构：
使用标记高效摘要扫描目录结构
使用令牌感知提取和分析文件内容
查找对代码库理解重要的文件
生成包含相关信息的报告
Related MCP server: Compiler Explorer MCP
特征
令牌感知目录扫描
以可配置的深度递归探索目录
为大型目录提供智能摘要
尊重 .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/token-scope-mcp.git
cd token-scope-mcp
# Install development dependencies with uv
uv pip install -e ".[dev]"以开发模式运行
# Run the server directly with uv
uv run --with fastmcp --with tiktoken src/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/token-scope-mcp/src/server.py", "--base-path", "/your/secure/base/path" ] } }将
/path/to/your/token-scope-mcp/src/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
扫描目录并以高效的方式返回其结构。
scan_directory_structure(
path: str,
depth: int = 3,
max_tokens: int = 10000,
ignore_patterns: list[str] | None = None,
include_gitignore: bool = True,
include_default_ignores: bool = True
)extract_file_content
提取特定文件的内容，尊重令牌限制和格式。
extract_file_content(
file_path: str,
max_tokens: int = 10000,
sample_only: bool = False
)search_files_by_pattern
在目录结构中搜索与指定模式匹配的文件。
search_files_by_pattern(
directory: str,
patterns: list[str],
max_depth: int = 5,
include_content: bool = False,
max_files: int = 100,
max_tokens_per_file: int = 1000,
sample_only: bool = False,
ignore_patterns: list[str] | None = None,
include_gitignore: bool = True,
include_default_ignores: bool = True
)analyze_token_usage
分析目录或文件的令牌使用情况以估计 LLM 处理要求。
analyze_token_usage(
path: str,
include_file_details: bool = False,
ignore_patterns: list[str] | None = None,
include_gitignore: bool = True,
include_default_ignores: bool = True
)generate_directory_report
生成有关目录的包含令牌统计信息的综合 markdown 报告。
generate_directory_report(
directory: str,
depth: int = 3,
include_file_content: bool = True,
max_files_with_content: int = 5,
max_tokens_per_file: int = 1000,
sample_only: bool = False,
ignore_patterns: list[str] | None = None,
include_gitignore: bool = True,
include_default_ignores: bool = True
)copy_file_to_destination
将文件从源路径复制到目标路径。
copy_file_to_destination(
source_path: str,
destination_path: str
)默认忽略模式
TokenScope 自动忽略常见目录和文件：
DEFAULT_IGNORE_PATTERNS = [
".git/",
".venv/",
"venv/",
"__pycache__/",
"node_modules/",
".pytest_cache/",
".ipynb_checkpoints/",
".DS_Store",
"*.pyc",
"*.pyo",
"*.pyd",
"*.so",
"*.dll",
"*.class",
"build/",
"dist/",
"*.egg-info/",
".tox/",
".coverage",
".idea/",
".vscode/",
".mypy_cache/",
]执照
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。