Token Scope MCP

TokenScope

用于大型语言模型（LLM）的令牌感知目录资源管理器。

A. 模型上下文协议（MCP） 服务器，帮助LLM高效地探索和理解代码库和目录结构。

概述

TokenScope提供智能目录结构分析和令牌感知文件内容探索，专为Claude等LLM设计。它通过以下方式帮助LLM理解代码库：

1. 使用令牌感知摘要探索目录结构
2. 在考虑令牌限制的情况下查看文件内容
3. 生成关于目录的综合报告

主要特点

令牌感知目录探索

• 自动汇总 用于大目录，同时完整显示小目录
• 尊重代币限制 在约束条件下最大限度地利用有用信息
• 内置安全 具有基本路径验证
• 智能过滤 具有默认模式和.gitignore支持
• 准确的目录统计 即使是最大的目录

简单直观的工具

TokenScope仅提供三个核心工具：

1. explore_directory -扫描并理解目录结构
2. view_content -通过令牌感知访问文件内容
3. generate_report -创建综合报告（可选择保存到文件）

安装

先决条件

• Python 3.10或更高版本
• 紫外线 （建议用于依赖关系管理）

安装（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中配置

1. 找到Claude Desktop的配置文件（通常 ~/.config/claude/config.json)

1. 将TokenScope添加到 mcpServers 章节：

"mcpServers": {
  "TokenScope": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "tokenscope",
      "tokenscope",
      "--base-path",
      "/your/secure/base/path"
    ]
  }
}

1. 替换 /your/secure/base/path 使用您要限制操作的目录

1. 保存配置文件并重新启动Claude Desktop

用法

正在运行TokenScope服务器

这 --base-path 参数是安全性所必需的（它将文件操作限制在指定的目录中）：

tokenscope --base-path /path/to/allowed/directory

直接测试工具

TokenScope包括一个直接试用工具的测试模式：

# Test directory exploration
tokenscope --base-path /path/to/allowed/directory --test "explore:/path/to/directory"

# Test with custom ignore patterns
tokenscope --base-path /path/to/allowed/directory --test "explore:/path/to/directory?ignore=cache,*.log,tmp/&gitignore=false"

# Test file viewing
tokenscope --base-path /path/to/allowed/directory --test "view:/path/to/file"

# Test report generation
tokenscope --base-path /path/to/allowed/directory --test "report:/path/to/directory"

# Test report generation with file output and custom ignore patterns
tokenscope --base-path /path/to/allowed/directory --test "report:/path/to/directory?ignore=*.bak,temp/ > /path/to/output.md"

示例提示

以下是一些如何在Claude中使用TokenScope的示例：

Could you explore my project directory at /path/to/project and tell me about its structure?

Can you show me the content of the file at /path/to/file.py?

Please generate a comprehensive report about my project at /path/to/project and save it to /path/to/report.md

准确的目录统计

TokenScope现在提供两级目录信息：

1. 快速扫描统计：有关树视图中可见的文件和目录的信息
2. 完整目录统计信息：所有文件和目录的完整计数，即使在非常大的存储库中也是如此

这种双重方法确保即使对于大型目录（包含数千或数百万个文件），您也能获得有关文件、目录和磁盘使用总数的准确信息。当处理大型代码库时，这尤其有价值，因为完整的目录列表会超过令牌限制。

输出示例

QUICK SCAN STATISTICS (files visible in tree):
Files shown in tree: 47
Directories shown in tree: 16
Size shown in tree: 185.9 MB

FULL DIRECTORY STATISTICS (all files):
Total files: 16,059
Total directories: 8
Total disk size: 2.1 GB

具有忽略模式的智能过滤

TokenScope会自动筛选出通常对理解代码库没有帮助的常见目录和文件：

• 默认忽略模式: .git/, .venv/, venv/, __pycache__/, node_modules/, build/, dist/等等。
• 自定义忽略模式：您可以通过指定要忽略的其他模式 ignore_patterns 参数
• .gitignore支持：TokenScope可以自动尊重它扫描的目录中的.gitignore文件

此功能有助于防止令牌浪费在不相关的文件和目录上，例如：

• 依赖目录（例如。， node_modules，虚拟环境）
• 构建工件和缓存目录
• 版本控制元数据
• IDE配置文件

在CLI测试模式下使用忽略模式

# Ignore specific patterns
tokenscope --base-path /path --test "explore:/code?ignore=*.log,temp/"

# Disable .gitignore processing
tokenscope --base-path /path --test "explore:/code?gitignore=false"

# Both together
tokenscope --base-path /path --test "explore:/code?ignore=*.tmp&gitignore=false"

安全功能

TokenScope包括重要的安全功能：

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

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

• 内置于 FastMCP
• 用途 tiktoken 用于精确的代币计数