Alcance del token

TokenScope es un explorador de directorios que reconoce tokens para modelos de lenguaje grandes.

Un servidor de Protocolo de Contexto de Modelo (MCP) para exploración y análisis de directorios con reconocimiento de tokens, diseñado para modelos de lenguaje grandes (LLM).

Descripción general

TokenScope ofrece análisis inteligente de la estructura de directorios y exploración del contenido de archivos con reconocimiento de tokens. Ayuda a los LLM como Claude a comprender las bases de código y las estructuras de directorios mediante:

Escaneo de estructuras de directorios con resúmenes que utilizan tokens de forma eficiente
Extracción y análisis del contenido de archivos con reconocimiento de tokens
Encontrar archivos importantes para comprender el código base
Generar informes con información relevante

Características

Escaneo de directorios con reconocimiento de tokens
- Explora directorios de forma recursiva con profundidad configurable
- Proporciona resúmenes inteligentes para directorios grandes
- Respeta los archivos .gitignore y los patrones de ignoración personalizados
Análisis del contenido de archivos
- Extracción inteligente del contenido de archivos que respeta los límites de tokens
- Manejo especial para JSON y otros archivos estructurados
- Priorización de selección de archivos según importancia
Estadísticas de uso de tokens
- Estima los tokens necesarios para procesar directorios
- Desglosa el uso del token por extensión de archivo
- Identifica archivos con muchos tokens
Informes completos
- Genera informes de rebajas con estructura de directorio
- Incluye estadísticas de uso de tokens
- Muestra muestras de archivos importantes
Características de seguridad
- Validación de ruta para restringir las operaciones a un directorio base específico
- Impide el acceso a archivos fuera de la ruta base permitida

Instalación

Prerrequisitos

Python 3.10 o superior
uv (recomendado para una fácil gestión de dependencias)

1. Instalación principal (PyPI)

Este es el método recomendado para la mayoría de los usuarios que solo desean utilizar TokenScope:

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

Ejecución de TokenScope

El argumento --base-path es obligatorio por razones de seguridad. Restringe todas las operaciones con archivos al directorio especificado.

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

Configuración en Claude Desktop

Localice el archivo de configuración de Claude Desktop (normalmente en ~/.config/claude/config.json )
Agregue TokenScope a la sección mcpServers :
"mcpServers": { "TokenScope": { "command": "uv", "args": [ "run", "--with", "tokenscope", "tokenscope", "--base-path", "/your/secure/base/path" ] } }
Reemplace /your/secure/base/path con el directorio al que desea restringir las operaciones
Guarde el archivo de configuración y reinicie Claude Desktop

2. Instalación de desarrollo (desde GitHub)

Para colaboradores o usuarios que quieran modificar el código:

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

Ejecutando en modo de desarrollo

# Run the server directly with uv
uv run --with fastmcp --with tiktoken src/server.py --base-path /path/to/allowed/directory

Configuración de la versión de desarrollo en Claude Desktop

Localice el archivo de configuración de Claude Desktop
Agregue TokenScope a la sección mcpServers con rutas de desarrollo:
"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" ] } }
Reemplace /path/to/your/token-scope-mcp/src/server.py con la ruta real al archivo server.py
Reemplace /your/secure/base/path con su directorio seguro

Características de seguridad

El argumento --base-path es obligatorio por razones de seguridad:

Todas las operaciones de archivos se validan para garantizar que estén dentro del directorio especificado
Se rechazarán los intentos de acceder o modificar archivos fuera de la ruta base.
La ruta base se establece una vez al iniciar el servidor y no se puede cambiar sin reiniciar

Ejemplos de indicaciones

A continuación se muestran algunos ejemplos de cómo utilizar TokenScope con Claude:

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.

Herramientas disponibles

El servidor proporciona las siguientes herramientas MCP:

`scan_directory_structure`

Escanea un directorio y devuelve su estructura de manera eficiente en términos de tokens.

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`

Extrae el contenido de un archivo específico, respetando los límites del token y el formato.

extract_file_content(
    file_path: str, 
    max_tokens: int = 10000,
    sample_only: bool = False
)

`search_files_by_pattern`

Busca archivos que coincidan con patrones específicos dentro de una estructura de directorio.

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`

Analiza el uso de tokens para un directorio o archivo para estimar los requisitos de procesamiento de 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`

Genera un informe de rebajas completo sobre un directorio con estadísticas de tokens.

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`

Copiar un archivo de la ruta de origen a la ruta de destino.

copy_file_to_destination(
    source_path: str,
    destination_path: str
)

Patrones de ignorar predeterminados

TokenScope ignora automáticamente los directorios y archivos comunes:

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/",
]

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Expresiones de gratitud

Creado con FastMCP
Utiliza TikTok para un conteo preciso de tokens
Este mismo concepto se implementó originalmente en repoai
Inspirado por la necesidad de analizar eficientemente bases de código con LLM