使用说明

项目简介

TokenScope 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为大型语言模型 (LLM) 提供token感知的目录和文件探索能力。它通过扫描目录结构、分析文件内容、评估token使用量，并生成报告，帮助LLM更好地理解代码库和项目结构。

主要功能点

Token 感知目录扫描: 递归探索目录，提供token高效的目录结构概要，并尊重 '.gitignore' 文件和自定义忽略规则。
文件内容分析: 智能提取文件内容，控制token数量，特殊处理 JSON 等结构化文件，并根据文件重要性进行优先级排序。
Token 使用量统计: 预估处理目录所需的token数量，按文件扩展名细分token使用情况，识别token消耗大的文件。
综合报告生成: 生成包含目录结构、token使用统计和重要文件样本的 Markdown 报告。
安全特性: 通过 'base-path' 限制文件操作在指定根目录下，防止访问未授权的文件。
文件复制工具: 提供文件复制工具，安全地在限定的根目录下复制文件。

安装步骤

安装 Python 3.10 或更高版本。
推荐安装 'uv' 包管理器，用于简化依赖管理：
```
pip install uv
```

使用 'uv' 安装 TokenScope:

uv pip install tokenscope

服务器配置

要将 TokenScope 配置为 MCP 服务器供 MCP 客户端（例如 Claude Desktop）使用，您需要在客户端的 MCP 服务器配置中添加 TokenScope 的启动命令和参数。以下是 Claude Desktop 的配置示例，其他 MCP 客户端的配置方法类似。

打开 Claude Desktop 的配置文件（通常位于 '~/.config/claude/config.json'），在 'mcpServers' 字段中添加 TokenScope 的配置信息：

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

参数说明:

'"TokenScope"': 服务器名称，可以自定义。
'"command": "uv"': 启动服务器的命令，这里使用 'uv run' 运行 Python 包。
'"args"': 传递给 'uv run' 的参数列表，包括：
- '"run"': 'uv' 的运行命令。
- '"--with"': 指定要运行的 Python 包。
- '"tokenscope"': 要运行的 Python 包名称 (TokenScope)。
- '"tokenscope"': 要执行的模块入口点，这里是 'tokenscope' 包的主模块。
- '"--base-path"': 必选参数，用于设置安全的文件操作根目录。 请将 '/your/secure/base/path' 替换为您希望限制 TokenScope 访问的目录的绝对路径。务必设置为安全的目录，以防止未授权的文件访问。

注意: 请将 '/your/secure/base/path' 替换为您实际希望 TokenScope 能够访问的根目录的绝对路径。 '--base-path' 参数至关重要，它限制了服务器的文件操作范围，保障了安全性。

保存配置文件并重启 Claude Desktop 或其他 MCP 客户端，即可连接到 TokenScope 服务器。

基本使用方法

配置完成后，您可以在 MCP 客户端中使用自然语言指令来调用 TokenScope 提供的工具，例如在 Claude 中：

扫描项目目录结构:

请扫描我的项目目录 /path/to/project 并告诉我它的结构，重点关注最重要的文件。

分析项目目录的 token 使用量:

分析我的项目目录 /path/to/project 的 token 使用情况，并告诉我用 LLM 处理整个代码库需要多少 token。

生成项目目录的综合报告:

生成关于我的项目目录 /path/to/project 的综合目录报告，包括结构、token 统计信息和最重要文件的样本。

您还可以直接调用 TokenScope 提供的工具，例如 'scan_directory_structure', 'extract_file_content', 'analyze_token_usage', 'generate_directory_report', 'copy_file_to_destination' 等，并根据工具的参数描述提供相应的参数。工具的具体参数和功能请参考仓库 README.md 文件中 "Available Tools" 章节的详细说明。

TokenScope 旨在帮助 LLM 更好地理解和分析代码库，提升 LLM 在软件开发和代码理解方面的应用能力。

关键词