MCP ツリーシッターサーバー
Tree-Sitterを用いたコード分析機能を提供するモデルコンテキストプロトコル（MCP）サーバー。適切なコンテキスト管理によってAIアシスタントがコードベースにインテリジェントにアクセスできるよう設計されています。Claude Desktopがリファレンス実装ターゲットです。
特徴
- 🔍柔軟な探索：複数の粒度レベルでコードを調査
- 🧠コンテキスト管理: コンテキストウィンドウを圧迫することなく、必要な情報だけを提供します
- 🌐言語に依存しない: tree-sitter-language-pack を介して、Python、JavaScript、TypeScript、Go、Rust、C、C++、Swift、Java、Kotlin、Julia、APL など、多くのプログラミング言語をサポートします。
- 🌳構造認識: 効率的なカーソルベースのトラバーサルで AST ベースの理解を使用します
- 🔎検索可能：テキスト検索とツリーシッタークエリを使用して特定のパターンを見つけます
- 🔄キャッシュ: 解析ツリーのキャッシュによるパフォーマンスの最適化
- 🔑シンボル抽出：関数、クラス、その他のコードシンボルを抽出して分析します
- 📊依存関係分析：コードの依存関係と関係を特定して分析します
- 🧩状態の永続性: 呼び出し間でプロジェクト登録とキャッシュされたデータを維持します
- 🔒安全: 組み込みのセキュリティ境界と入力検証
利用可能なすべてのコマンドの包括的なリスト、現在の実装ステータス、および詳細な機能マトリックスについては、 FEATURES.mdドキュメントを参照してください。
インストール
前提条件
- Python 3.10以上
- お好みの言語のための Tree-sitter 言語パーサー
基本的なインストール
pip install mcp-server-tree-sitter
開発インストール
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 を再起動します。
少なくとも1つの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 Tree-sitter Serverは、呼び出し間で状態を維持します。これは次のことを意味します。
- プロジェクトは明示的に削除されるか、サーバーが再起動されるまで登録されたままになります。
- 解析ツリーは設定に従ってキャッシュされます
- 言語情報はサーバーの存続期間中保持されます
この永続性は、主要コンポーネントのシングルトン パターンを使用して、サーバーの存続期間中メモリ内に維持されます。
スタンドアロンサーバーとして実行
サーバーを実行するにはいくつかの方法があります。
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インスペクターと併用する
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")
tree-sitter クエリを実行します。
run_query(
project="my-project",
query='(function_definition name: (identifier) @function.name)',
language="python"
)
複雑さを分析する
analyze_complexity(project="my-project", path="src/main.py")
Pythonの直接使用
主な使用目的は 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について
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 Tree-sitter Serverは、慎重な設計パターンとプロトコルにより、Tree-sitterライブラリとのインターフェースにおいて型安全性を維持しています。コードベースを拡張する場合は、Tree-sitter 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 - tree-sitter クエリ構文の説明suggest_improvements - コードの改善を提案するためのプロンプトを作成するproject_overview - プロジェクト概要分析のプロンプトを作成する
ライセンス
マサチューセッツ工科大学