토큰스코프

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

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

개요

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

1. 토큰 효율적인 요약을 사용한 디렉토리 구조 스캔

2. 토큰 인식을 통한 파일 콘텐츠 추출 및 분석

3. 코드베이스 이해를 위한 중요한 파일 찾기

4. 관련 정보를 포함한 보고서 생성

Related MCP server: Codebase MCP

특징

• 토큰 인식 디렉토리 스캐닝

  • 구성 가능한 깊이로 디렉토리를 재귀적으로 탐색합니다.

  • 대규모 디렉토리에 대한 지능형 요약을 제공합니다.

  • .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에서 구성

1. Claude Desktop의 구성 파일을 찾습니다(일반적으로 ~/.config/claude/config.json 에 있음)

2. mcpServers 섹션에 TokenScope를 추가합니다.

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

3. /your/secure/base/path 작업을 제한하려는 디렉토리로 바꾸십시오.

4. 구성 파일을 저장하고 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에서 개발 버전 구성

1. Claude Desktop의 구성 파일을 찾으세요

2. 개발 경로를 사용하여 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"
    ]
    }
   }

3. /path/to/your/token-scope-mcp/src/server.py server.py 파일의 실제 경로로 바꾸세요.

4. /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을 사용하여 코드베이스를 효율적으로 분석해야 한다는 필요성에서 영감을 얻었습니다.

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers