토큰스코프
참고: 이 패키지는 tokenscope 라는 이름으로 게시되었지만, 역사적 이유로 저장소 이름은 directory-explorer-mcp 로 유지됩니다.
대규모 언어 모델(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/directory-explorer-mcp.git
cd directory-explorer-mcp
# Install development dependencies with uv
uv pip install -e ".[dev]"
개발 모드에서 실행
# Run the server directly with uv
uv run --with fastmcp --with tiktoken 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/directory-explorer-mcp/server.py",
"--base-path",
"/your/secure/base/path"
]
}
}
/path/to/your/directory-explorer-mcp/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
디렉토리를 스캔하여 토큰 효율적인 방식으로 구조를 반환합니다.
토큰 제한과 형식을 준수하여 특정 파일의 내용을 추출합니다.
search_files_by_pattern
디렉토리 구조 내에서 지정된 패턴과 일치하는 파일을 검색합니다.
analyze_token_usage
디렉토리나 파일에 대한 토큰 사용을 분석하여 LLM 처리 요구 사항을 추정합니다.
copy_file_to_destination
소스 경로에서 대상 경로로 파일을 복사합니다.
generate_directory_report
토큰 통계를 포함한 디렉토리에 대한 포괄적인 마크다운 보고서를 생성합니다.
특허
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.
감사의 말
- FastMCP 로 구축됨
- 이 동일한 개념은 원래 repoai 에 구현되었습니다.
- LLM을 사용하여 코드베이스를 효율적으로 분석해야 한다는 필요성에서 영감을 얻었습니다.