トークンスコープ

TokenScope は、大規模言語モデル用のトークン対応ディレクトリエクスプローラーです。

大規模言語モデル (LLM) 向けに設計された、トークン対応のディレクトリ探索および分析用のモデルコンテキストプロトコル (MCP)サーバー。

概要

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

トークン効率の高い要約によるディレクトリ構造のスキャン
トークン認識によるファイル内容の抽出と分析
コードベースを理解するための重要なファイルを見つける
関連情報を含むレポートの生成

特徴

トークン対応ディレクトリスキャン
- 設定可能な深さでディレクトリを再帰的に探索します
- 大規模なディレクトリにインテリジェントな概要を提供します
- .gitignore ファイルとカスタム無視パターンを尊重
ファイルコンテンツ分析
- トークン制限を尊重したファイル内容のスマートな抽出
- JSONおよびその他の構造化ファイルの特別な処理
- 重要度に基づくファイル選択の優先順位付け
トークン使用統計
- ディレクトリの処理に必要なトークンを推定します
- ファイル拡張子別にトークンの使用状況を分類します
- トークンの多いファイルを識別します
包括的なレポート
- ディレクトリ構造を持つマークダウンレポートを生成する
- トークンの使用統計情報が含まれています
- 重要なファイルのサンプルを表示します
セキュリティ機能
- 指定されたベースディレクトリへの操作を制限するパス検証
- 許可されたベースパス外のファイルへのアクセスを防止します

インストール

前提条件

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の設定ファイルを見つける
開発パスを使用して、 mcpServersセクションに TokenScope を追加します。
"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引数はセキュリティ上の理由から必須です。

すべてのファイル操作は、指定されたディレクトリ内にあることを確認するために検証されます。
ベースパス外のファイルにアクセスしたり変更したりする試みは拒否されます
ベースパスはサーバーの起動時に一度設定され、再起動しないと変更できません。

プロンプトの例

Claude で TokenScope を使用する方法の例をいくつか示します。

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`

トークン統計を含むディレクトリに関する包括的なマークダウンレポートを生成します。

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で構築
正確なトークンカウントのためにTikTokを使用
この同じコンセプトは元々はrepoaiで実装されました
LLMを使用してコードベースを効率的に分析する必要性に着想を得て