TokenScope: Token-Aware Directory Explorer

TokenScope

大規模言語モデル（LLM）向けのトークンを考慮したディレクトリエクスプローラーです。

LLM がコードベースやディレクトリ構造を効率的に探索し、理解するのに役立つ Model Context Protocol（MCP） サーバーです。

概要

TokenScope は、Claude のような LLM 向けに設計された、インテリジェントなディレクトリ構造分析と、トークンを考慮したファイル内容の探索機能を提供します。次の方法で、LLM がコードベースを理解するのに役立ちます。

1. トークンを考慮して要約しながら、ディレクトリ構造を探索します
2. トークン制限を考慮してファイルの内容を表示します
3. ディレクトリに関する包括的なレポートを生成します

主な機能

トークンを考慮したディレクトリ探索

• 大きなディレクトリは自動的に要約し、小さなディレクトリはすべて表示します
• トークン制限を順守し、制約内で有用な情報を最大限に提示します
• ベースパスの検証による組み込みのセキュリティ
• デフォルトのパターンと .gitignore に対応したスマートなフィルタリング
• 非常に大きなディレクトリでも正確なディレクトリ統計

シンプルで直感的なツール

TokenScope は、次の 3 つの主要ツールを提供します。

1. explore_directory - ディレクトリ構造をスキャンして理解します
2. view_content - トークンを考慮してファイルの内容にアクセスします
3. generate_report - 包括的なレポートを作成します（ファイルへの保存も選択できます）

インストール

前提条件

• Python 3.10 以降
• uv（依存関係の管理に推奨）

インストール（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 です）

2. mcpServers セクションに TokenScope を追加します。

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

3. /your/secure/base/path を、操作対象を制限するディレクトリに置き換えます

4. 設定ファイルを保存し、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 は、次の 2 種類のディレクトリ情報を提供するようになりました。

1. クイックスキャン統計：ツリービューに表示されているファイルとディレクトリの情報
2. ディレクトリ全体の統計：非常に大きなリポジトリでも、すべてのファイルとディレクトリの完全な件数

この 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 対応：スキャンするディレクトリ内の .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 License の下でライセンスされています。詳細については LICENSE ファイルをご覧ください。

謝辞

• FastMCP を使用して構築されています
• 正確なトークン数のカウントに tiktoken を使用しています