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:

1. Escaneo de estructuras de directorios con resúmenes que utilizan tokens de forma eficiente

2. Extracción y análisis del contenido de archivos con reconocimiento de tokens

3. Encontrar archivos importantes para comprender el código base

4. Generar informes con información relevante

Related MCP server: Codebase MCP

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

1. Localice el archivo de configuración de Claude Desktop (normalmente en ~/.config/claude/config.json )

2. Agregue TokenScope a la sección mcpServers :

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

3. Reemplace /your/secure/base/path con el directorio al que desea restringir las operaciones

4. 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

1. Localice el archivo de configuración de Claude Desktop

2. 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"
    ]
    }
   }

3. Reemplace /path/to/your/token-scope-mcp/src/server.py con la ruta real al archivo server.py

4. 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

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers