README - TokenScope: Token-Aware Directory Explorer by cdgaete

TokenScope

Token-Aware Directory Explorer for Large Language Models (LLMs).

A Model Context Protocol (MCP) server that helps LLMs efficiently explore and understand codebases and directory structures.

Overview

TokenScope provides intelligent directory structure analysis and token-aware file content exploration designed for LLMs like Claude. It helps LLMs understand codebases by:

Exploring directory structures with token-aware summarization
Viewing file contents with token limitations in mind
Generating comprehensive reports about directories

Key Features

Token-Aware Directory Exploration

Automatic summarization for large directories while showing small directories in full
Respect for token limits to maximize useful information within constraints
Built-in security with base path validation
Smart filtering with default patterns and .gitignore support
Accurate directory statistics for even the largest directories

Simple, Intuitive Tools

TokenScope provides just three core tools:

explore_directory - Scan and understand directory structures
view_content - Access file contents with token awareness
generate_report - Create comprehensive reports (with option to save to file)

Installation

Prerequisites

Python 3.10 or higher
uv (recommended for dependency management)

Installation (PyPI)

This is the recommended method for most users who just want to use TokenScope:

# Install from PyPI using uv (recommended)
uv pip install tokenscope

Running TokenScope

The --base-path argument is mandatory for security reasons. It restricts all file operations to the specified directory.

# Run using the installed package
uv run --with tokenscope tokenscope --base-path /path/to/allowed/directory

Configuring in Claude Desktop

Locate Claude Desktop's configuration file (typically ~/.config/claude/config.json)
Add TokenScope to the mcpServers section:

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

Replace /your/secure/base/path with the directory you want to restrict operations to
Save the configuration file and restart Claude Desktop

Usage

Running TokenScope Server

The --base-path argument is required for security (it restricts file operations to the specified directory):

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

Testing Tools Directly

TokenScope includes a test mode for trying out tools directly:

# 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"

Example Prompts

Here are some examples of how to use TokenScope with Claude:

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

Accurate Directory Statistics

TokenScope now provides two levels of directory information:

Quick Scan Statistics: Information about files and directories visible in the tree view
Full Directory Statistics: Complete counts of ALL files and directories, even in very large repositories

This dual approach ensures that even for massive directories (with thousands or millions of files), you'll get accurate information about the total number of files, directories, and disk usage. This is especially valuable when working with large codebases where a complete directory listing would exceed token limits.

Example Output

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

Smart Filtering with Ignore Patterns

TokenScope automatically filters out common directories and files that typically don't contribute to understanding a codebase:

Default ignored patterns: .git/, .venv/, venv/, __pycache__/, node_modules/, build/, dist/, etc.
Custom ignore patterns: You can specify additional patterns to ignore via the ignore_patterns parameter
.gitignore support: TokenScope can automatically respect .gitignore files in the directories it scans

This functionality helps prevent token waste on irrelevant files and directories like:

Dependency directories (e.g., node_modules, virtual environments)
Build artifacts and cache directories
Version control metadata
IDE configuration files

Using Ignore Patterns in CLI Test Mode

# 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"

Security Features

TokenScope includes important security features:

All file operations are validated to ensure they're within the specified base directory
Attempts to access files outside the base path are rejected
The base path is set once when starting the server and cannot be changed without restart

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with FastMCP
Uses tiktoken for accurate token counting