TokenScope

TokenScope 是用于大型语言模型的令牌感知目录浏览器。

专为大型语言模型 (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/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 文件。

致谢

使用FastMCP构建
使用tiktoken进行精确的代币计数
这一概念最初在repoai中实现
受到使用 LLM 高效分析代码库的需求的启发