TokenScope: Token-Aware Directory Explorer

Name: TokenScope: Token-Aware Directory Explorer
Author: cdgaete

@cdgaete

About TokenScope: Token-Aware Directory Explorer

A tool to analyze directory structures while being mindful of token limitations for LLMs. Customize ignore files like gitignore patterns, such as .venv or node_modules

#mcp #directory #explorer #claude #ai #assistant #token-aware

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

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

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is TokenScope: Token-Aware Directory Explorer?

TokenScope is a Model Context Protocol (MCP) server that provides token-aware directory structure analysis and file content extraction for Large Language Models. It helps LLMs understand codebases efficiently by respecting token limits and filtering via .gitignore patterns.

How to use TokenScope: Token-Aware Directory Explorer?

Configure TokenScope with a mandatory base path for security, then invoke its six tools (e.g., scan_directory_structure, extract_file_content, search_files_by_pattern, analyze_token_usage, generate_directory_report, copy_file_to_destination) from any MCP-compatible client. All operations are confined to the allowed directory and automatically respect .gitignore rules.

Key features of TokenScope: Token-Aware Directory Explorer

Recursive directory scanning with token-efficient summaries
Smart file content extraction respecting token limits
Pattern-based file search within the allowed directory
Token usage estimation for entire directories
Comprehensive directory reports with structure and token statistics
Secure file copying between locations inside the base path

Use cases of TokenScope: Token-Aware Directory Explorer

Give an LLM structured context about a codebase before code generation
Extract relevant source files from a large project while staying under token budgets
Estimate the token cost of processing a directory with an LLM
Quickly locate files matching specific patterns in a project
Generate token-aware overviews of directory contents for AI-assisted development

FAQ from TokenScope: Token-Aware Directory Explorer

What is the base path and why is it required?

The base path is a mandatory directory that limits all file operations. It ensures security by confining scans, extractions, and copies to that directory only.

How does TokenScope handle token limits?

The server estimates token counts and uses smart extraction to stay within configurable token limits, providing only as much content as the LLM can process.

Does TokenScope respect .gitignore patterns?

Yes, it automatically filters out files and directories matched by .gitignore patterns in the scanned directory, reducing noise and saving tokens.

What are the runtime dependencies of TokenScope?

TokenScope is an MCP server; it requires a runtime environment with the MCP protocol and access to the filesystem it scans. No additional databases or external services are needed.

How secure is file copy in TokenScope?

The copy_file_to_destination tool operates exclusively within the allowed base path, preventing any file operations outside that directory. Destination files must also reside inside the base path.