MCP 트리시터 서버
트리시터를 사용하여 코드 분석 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버로, AI 어시스턴트가 적절한 컨텍스트 관리를 통해 코드베이스에 지능적으로 접근할 수 있도록 설계되었습니다. Claude Desktop이 참조 구현 대상입니다.
특징
- 🔍 유연한 탐색 : 다양한 수준의 세부성에서 코드를 검사합니다.
- 🧠 컨텍스트 관리 : 컨텍스트 창을 압도하지 않으면서 필요한 정보만 제공합니다.
- 🌐 언어 독립적 : tree-sitter-language-pack을 통해 Python, JavaScript, TypeScript, Go, Rust, C, C++, Swift, Java, Kotlin, Julia, APL 등 다양한 프로그래밍 언어를 지원합니다.
- 🌳 구조 인식 : 효율적인 커서 기반 탐색을 통해 AST 기반 이해를 활용합니다.
- 🔎 검색 가능 : 텍스트 검색 및 트리시터 쿼리를 사용하여 특정 패턴 찾기
- 🔄 캐싱 : 파스 트리 캐싱을 통한 성능 최적화
- 🔑 심볼 추출 : 함수, 클래스 및 기타 코드 심볼을 추출하고 분석합니다.
- 📊 종속성 분석 : 코드 종속성 및 관계를 식별하고 분석합니다.
- 🧩 상태 지속성 : 호출 간에 프로젝트 등록 및 캐시된 데이터를 유지합니다.
- 🔒 보안 : 내장된 보안 경계 및 입력 검증
사용 가능한 모든 명령의 포괄적인 목록, 현재 구현 상태 및 자세한 기능 매트릭스는 FEATURES.md 문서를 참조하세요.
설치
필수 조건
- 파이썬 3.10+
- 선호하는 언어에 대한 트리시터 언어 파서
기본 설치
지엑스피1
개발 설치
git clone https://github.com/wrale/mcp-server-tree-sitter.git
cd mcp-server-tree-sitter
pip install -e ".[dev,languages]"
빠른 시작
Claude Desktop으로 실행
MCP CLI를 통하거나 Claude Desktop을 수동으로 구성하여 Claude Desktop에서 서버를 사용할 수 있습니다.
MCP CLI 사용
Claude Desktop에 서버를 등록하세요:
mcp install mcp_server_tree_sitter.server:mcp --name "tree_sitter"
수동 구성
또는 Claude Desktop을 수동으로 구성할 수 있습니다.
- Claude Desktop 구성 파일을 엽니다.
- macOS/Linux:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
파일이 없으면 생성합니다.
mcpServers 섹션에 서버를 추가합니다.{
"mcpServers": {
"tree_sitter": {
"command": "python",
"args": [
"-m",
"mcp_server_tree_sitter.server"
]
}
}
}
{
"mcpServers": {
"tree_sitter": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/YOUR/PROJECT",
"run",
"-m",
"mcp_server_tree_sitter.server"
]
}
}
}
/ABSOLUTE/PATH/TO/YOUR/PROJECT 프로젝트 디렉토리의 실제 절대 경로로 바꿔야 합니다.- 파일을 저장하고 Claude Desktop을 다시 시작하세요.
최소 하나의 MCP 서버를 올바르게 구성하면 Claude Desktop 인터페이스에 MCP 도구 아이콘(망치)이 나타납니다. 이 아이콘을 클릭하면 tree_sitter 서버 기능에 액세스할 수 있습니다.
릴리스된 버전으로 구성
PyPI(릴리스 버전)에서 패키지를 수동으로 설치하지 않거나 저장소를 복제하지 않으려면 Claude Desktop에 대해 다음 구성을 사용하세요.
- Claude Desktop 구성 파일을 엽니다(위와 같은 위치).
mcpServers 섹션에 tree-sitter 서버를 추가합니다.{
"mcpServers": {
"tree_sitter": {
"command": "uvx",
"args": [
"--directory", "/ABSOLUTE/PATH/TO/YOUR/PROJECT",
"mcp-server-tree-sitter"
]
}
}
}
- 파일을 저장하고 Claude Desktop을 다시 시작하세요.
이 방법은 uvx 사용하여 설치된 PyPI 패키지를 직접 실행하는데, 이는 출시된 버전에 권장되는 방식입니다. 서버는 기본 구성에서 실행하기 위해 추가 매개변수를 필요로 하지 않습니다.
상태 지속성
MCP 트리시터 서버는 호출 간 상태를 유지합니다. 이는 다음을 의미합니다.
- 프로젝트는 명시적으로 제거되거나 서버가 다시 시작될 때까지 등록된 상태로 유지됩니다.
- 구문 분석 트리는 구성 설정에 따라 캐시됩니다.
- 언어 정보는 서버의 수명 동안 유지됩니다.
이러한 지속성은 주요 구성 요소에 대한 싱글톤 패턴을 사용하여 서버가 작동하는 동안 메모리에 유지됩니다.
독립형 서버로 실행
서버를 실행하는 방법에는 여러 가지가 있습니다.
MCP CLI를 직접 사용하는 경우:
python -m mcp run mcp_server_tree_sitter.server
Makefile 타겟 사용:
# Show available targets
make
# Run the server with default settings
make mcp-run
# Show help information
make mcp-run ARGS="--help"
# Show version information
make mcp-run ARGS="--version"
# Run with custom configuration file
make mcp-run ARGS="--config /path/to/config.yaml"
# Enable debug logging
make mcp-run ARGS="--debug"
# Disable parse tree caching
make mcp-run ARGS="--disable-cache"
설치된 스크립트 사용:
# Run the server with default settings
mcp-server-tree-sitter
# Show help information
mcp-server-tree-sitter --help
# Show version information
mcp-server-tree-sitter --version
# Run with custom configuration file
mcp-server-tree-sitter --config /path/to/config.yaml
# Enable debug logging
mcp-server-tree-sitter --debug
# Disable parse tree caching
mcp-server-tree-sitter --disable-cache
MCP Inspector와 함께 사용
MCP CLI를 직접 사용하는 경우:
python -m mcp dev mcp_server_tree_sitter.server
또는 Makefile 타겟을 사용합니다.
인수를 전달할 수도 있습니다.
make mcp-dev ARGS="--debug"
용법
프로젝트 등록
먼저 분석할 프로젝트를 등록하세요.
register_project_tool(path="/path/to/your/project", name="my-project")
파일 탐색
프로젝트의 파일 나열:
list_files(project="my-project", pattern="**/*.py")
파일 내용 보기:
get_file(project="my-project", path="src/main.py")
코드 구조 분석
구문 트리를 얻으세요:
get_ast(project="my-project", path="src/main.py", max_depth=3)
기호 추출:
get_symbols(project="my-project", path="src/main.py")
검색 코드
텍스트 검색:
find_text(project="my-project", pattern="function", file_pattern="**/*.py")
트리시터 쿼리 실행:
run_query(
project="my-project",
query='(function_definition name: (identifier) @function.name)',
language="python"
)
복잡성 분석
analyze_complexity(project="my-project", path="src/main.py")
직접 파이썬 사용법
이 라이브러리는 주로 MCP 서버를 통해 사용되지만 Python 코드에서 직접 사용할 수도 있습니다.
# Import from the API module
from mcp_server_tree_sitter.api import (
register_project, list_projects, get_config, get_language_registry
)
# Register a project
project_info = register_project(
path="/path/to/project",
name="my-project",
description="Description"
)
# List projects
projects = list_projects()
# Get configuration
config = get_config()
# Access components through dependency injection
from mcp_server_tree_sitter.di import get_container
container = get_container()
project_registry = container.project_registry
language_registry = container.language_registry
구성
YAML 구성 파일을 만듭니다.
cache:
enabled: true # Enable/disable caching (default: true)
max_size_mb: 100 # Maximum cache size in MB (default: 100)
ttl_seconds: 300 # Cache entry time-to-live in seconds (default: 300)
security:
max_file_size_mb: 5 # Maximum file size to process in MB (default: 5)
excluded_dirs: # Directories to exclude from processing
- .git
- node_modules
- __pycache__
allowed_extensions: # Optional list of allowed file extensions
# - py
# - js
# Leave empty or omit for all extensions
language:
default_max_depth: 5 # Default max depth for AST traversal (default: 5)
preferred_languages: # List of languages to pre-load at startup for faster performance
- python # Pre-loading reduces latency for first operations
- javascript
log_level: INFO # Logging level (DEBUG, INFO, WARNING, ERROR)
max_results_default: 100 # Default maximum results for search operations
다음을 로드하세요:
configure(config_path="/path/to/config.yaml")
로깅 구성
서버의 로깅 세부 정보는 환경 변수를 사용하여 제어할 수 있습니다.
# Enable detailed debug logging
export MCP_TS_LOG_LEVEL=DEBUG
# Use normal informational logging (default)
export MCP_TS_LOG_LEVEL=INFO
# Only show warning and error messages
export MCP_TS_LOG_LEVEL=WARNING
로깅 구성에 대한 자세한 내용은 로깅 설명서 를 참조하십시오. 명령줄 인터페이스에 대한 자세한 내용은 CLI 설명서를 참조하십시오.
선호하는 언어에 관하여
preferred_languages 설정은 요청 시가 아닌 서버 시작 시 미리 로드되는 언어 파서를 제어합니다. 이는 다음과 같은 여러 가지 이점을 제공합니다.
- 더 빠른 초기 분석 : 미리 로드된 언어 파일을 처음 분석할 때 지연이 없습니다.
- 조기 오류 감지 : 파서 문제는 사용 중이 아닌 시작 시 발견됩니다.
- 예측 가능한 메모리 할당 : 자주 사용되는 파서의 메모리가 미리 할당됩니다.
기본적으로 모든 파서는 처음 필요할 때 온디맨드로 로드됩니다. 최적의 성능을 위해 프로젝트에서 가장 자주 사용하는 언어를 지정하세요.
다음과 같은 특정 설정을 구성할 수도 있습니다.
configure(cache_enabled=True, max_file_size_mb=10, log_level="DEBUG")
또는 환경 변수를 사용하세요.
export MCP_TS_CACHE_MAX_SIZE_MB=256
export MCP_TS_LOG_LEVEL=DEBUG
export MCP_TS_CONFIG_PATH=/path/to/config.yaml
환경 변수는 섹션 설정의 경우 MCP_TS_SECTION_SETTING (예: MCP_TS_CACHE_MAX_SIZE_MB ) 형식을 사용하고 최상위 설정의 경우 MCP_TS_SETTING (예: MCP_TS_LOG_LEVEL ) 형식을 사용합니다.
구성 값은 다음 우선순위에 따라 적용됩니다.
- 환경 변수(가장 높음)
configure() 호출을 통해 설정된 값- YAML 구성 파일
- 기본값(최저)
서버는 다음에서 구성을 찾습니다.
configure() 호출에서 지정된 경로MCP_TS_CONFIG_PATH 환경 변수에 의해 지정된 경로- 기본 위치:
~/.config/tree-sitter/config.yaml
개발자를 위한
진단 기능
MCP Tree-sitter Server에는 문제를 식별하고 해결하는 데 도움이 되는 진단 프레임워크가 포함되어 있습니다.
# Run diagnostic tests
make test-diagnostics
# CI-friendly version (won't fail the build on diagnostic issues)
make test-diagnostics-ci
진단 테스트는 서버 동작에 대한 자세한 정보를 제공하고 특정 문제를 파악하는 데 도움이 될 수 있습니다. 진단 프레임워크에 대한 자세한 내용은 진단 설명서를 참조하세요.
유형 안전 고려 사항
MCP 트리시터 서버는 신중한 디자인 패턴과 프로토콜을 통해 트리시터 라이브러리와 인터페이싱할 때 타입 안전성을 유지합니다. 코드베이스를 확장하는 경우, 트리시터 API 변형 처리에 대한 중요한 정보는 타입 안전성 가이드를 참조하세요.
사용 가능한 리소스
서버는 다음과 같은 MCP 리소스를 제공합니다.
project://{project}/files - 프로젝트의 모든 파일 나열project://{project}/files/{pattern} - 패턴과 일치하는 파일 나열project://{project}/file/{path} - 파일 내용 가져오기project://{project}/file/{path}/lines/{start}-{end} - 파일에서 특정 줄 가져오기project://{project}/ast/{path} - 파일의 AST를 가져옵니다.project://{project}/ast/{path}/depth/{depth} - 사용자 정의 깊이로 AST 가져오기
사용 가능한 도구
서버는 다음을 위한 도구를 제공합니다.
- 프로젝트 관리:
register_project_tool , list_projects_tool , remove_project_tool - 언어 관리:
list_languages , check_language_available - 파일 작업:
list_files , get_file , get_file_metadata - AST 분석:
get_ast , get_node_at_position - 코드 검색:
find_text , run_query - 심볼 추출:
get_symbols , find_usage - 프로젝트 분석:
analyze_project , get_dependencies , analyze_complexity - 쿼리 작성:
get_query_template_tool , list_query_templates_tool , build_query , adapt_query , get_node_types - 유사 코드 감지:
find_similar_code - 캐시 관리:
clear_cache - 구성 진단:
diagnose_config
각 도구의 구현 상태, 종속성 및 사용 예에 대한 자세한 내용은 FEATURES.md를 참조하세요.
사용 가능한 프롬프트
서버는 다음과 같은 MCP 프롬프트를 제공합니다.
code_review - 코드 검토를 위한 프롬프트 생성explain_code - 코드 설명을 위한 프롬프트를 만듭니다.explain_tree_sitter_query - 트리시터 쿼리 구문 설명suggest_improvements - 코드 개선 제안을 위한 프롬프트를 만듭니다.project_overview - 프로젝트 개요 분석을 위한 프롬프트 만들기
특허
MIT