토큰스코프

TokenScope는 대규모 언어 모델을 위한 토큰 인식 디렉토리 탐색기입니다.

대규모 언어 모델(LLM)을 위해 설계된 토큰 인식 디렉토리 탐색 및 분석을 위한 MCP(모델 컨텍스트 프로토콜) 서버입니다.

개요

TokenScope는 지능적인 디렉터리 구조 분석 및 토큰 기반 파일 콘텐츠 탐색 기능을 제공합니다. Claude와 같은 LLM이 코드베이스와 디렉터리 구조를 이해하는 데 도움을 주는 다음과 같은 기능을 제공합니다.

토큰 효율적인 요약을 사용한 디렉토리 구조 스캔
토큰 인식을 통한 파일 콘텐츠 추출 및 분석
코드베이스 이해를 위한 중요한 파일 찾기
관련 정보를 포함한 보고서 생성

특징

토큰 인식 디렉토리 스캐닝
- 구성 가능한 깊이로 디렉토리를 재귀적으로 탐색합니다.
- 대규모 디렉토리에 대한 지능형 요약을 제공합니다.
- .gitignore 파일과 사용자 정의 무시 패턴을 존중합니다.
파일 콘텐츠 분석
- 토큰 제한을 준수하는 파일 내용의 스마트 추출
- JSON 및 기타 구조화된 파일에 대한 특수 처리
- 중요도에 따른 파일 선택 우선순위 지정
토큰 사용 통계
- 디렉토리 처리에 필요한 토큰을 추정합니다.
- 파일 확장자별로 토큰 사용을 분석합니다.
- 토큰이 많은 파일을 식별합니다.
종합 보고
- 디렉토리 구조로 마크다운 보고서를 생성합니다.
- 토큰 사용 통계 포함
- 중요한 파일의 샘플을 보여줍니다
보안 기능
- 지정된 기본 디렉토리로 작업을 제한하기 위한 경로 검증
- 허용된 기본 경로 외부의 파일에 대한 액세스를 방지합니다.

설치

필수 조건

Python 3.10 이상
uv (쉽게 종속성을 관리할 수 있도록 권장)

1. 메인 설치(PyPI)

이는 TokenScope만 사용하려는 대부분의 사용자에게 권장되는 방법입니다.

지엑스피1

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 에 있음)
mcpServers 섹션에 TokenScope를 추가합니다.
"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 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

감사의 말

FastMCP 로 구축됨
정확한 토큰 계산을 위해 TikToken을 사용합니다.
이 동일한 개념은 원래 repoai 에 구현되었습니다.
LLM을 사용하여 코드베이스를 효율적으로 분석해야 한다는 필요성에서 영감을 얻었습니다.