MCP Tree-sitter Server

tree-sitterを使用したコード解析機能を提供するModel Context Protocol (MCP) サーバーです。AIアシスタントが適切なコンテキスト管理を行いながら、コードベースにインテリジェントにアクセスできるように設計されています。Claude Desktopがリファレンス実装のターゲットです。

機能

• 🔍 柔軟な探索: 複数の粒度でコードを調査

• 🧠 コンテキスト管理: コンテキストウィンドウを圧迫することなく、必要十分な情報を提供

• 🌐 言語非依存: tree-sitter-language-packを通じて、Python、JavaScript、TypeScript、Go、Rust、C、C++、C#、Swift、Java、Kotlin、Dart、Julia、APLなど、多くのプログラミング言語をサポート

• 🌳 構造認識: 効率的なカーソルベースのトラバーサルを備えたASTベースの理解を使用

• 🔎 検索可能: テキスト検索とtree-sitterクエリを使用して特定のパターンを検索

• 🔄 キャッシュ: パースツリーのキャッシュによるパフォーマンスの最適化

• 🔑 シンボル抽出: 関数、クラス、その他のコードシンボルの抽出と解析

• 📊 依存関係解析: コードの依存関係と関係性の特定と解析

• 🧩 状態の永続化: 呼び出し間でのプロジェクト登録とキャッシュデータの保持

• 🔒 セキュア: 組み込みのセキュリティ境界と入力バリデーション

利用可能なすべてのコマンド、現在の実装状況、詳細な機能マトリックスについては、FEATURES.mdドキュメントを参照してください。

Related MCP server: code-index-mcp

インストール

前提条件

• 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]"

クイックスタート

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を手動で設定することもできます：

1. Claude Desktopの設定ファイルを開きます：

   • macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   ファイルが存在しない場合は作成してください。

2. mcpServersセクションにサーバーを追加します：

   {
    "mcpServers": {
    "tree_sitter": {
    "command": "python",
    "args": [
    "-m",
    "mcp_server_tree_sitter.server"
    ]
    }
    }
   }

   または、uvや他のパッケージマネージャーを使用している場合：

   {
    "mcpServers": {
    "tree_sitter": {
    "command": "uv",
    "args": [
    "--directory",
    "/ABSOLUTE/PATH/TO/YOUR/PROJECT",
    "run",
    "-m",
    "mcp_server_tree_sitter.server"
    ]
    }
    }
   }

   注: /ABSOLUTE/PATH/TO/YOUR/PROJECTをプロジェクトディレクトリへの実際の絶対パスに置き換えてください。

3. ファイルを保存し、Claude Desktopを再起動します。

少なくとも1つのMCPサーバーを適切に設定すると、Claude DesktopのインターフェースにMCPツールアイコン（ハンマー）が表示されます。このアイコンをクリックすることで、tree_sitterサーバーの機能にアクセスできます。

リリース版での設定

PyPI（リリース版）からパッケージを手動でインストールしたり、リポジトリをクローンしたりしたくない場合は、Claude Desktopに対して以下の設定を使用してください：

1. Claude Desktopの設定ファイル（上記と同じ場所）を開きます。

2. mcpServersセクションにtree-sitterサーバーを追加します：

   {
    "mcpServers": {
    "tree_sitter": {
    "command": "uvx",
    "args": [
    "--directory", "/ABSOLUTE/PATH/TO/YOUR/PROJECT",
    "mcp-server-tree-sitter"
    ]
    }
    }
   }

3. ファイルを保存し、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 Inspectorでの使用

MCP CLIを直接使用：

python -m mcp dev mcp_server_tree_sitter.server

またはMakefileターゲットを使用：

make mcp-dev

引数を渡すこともできます：

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）を使用します。

設定値は以下の優先順位で適用されます：

1. 環境変数（最高）

2. configure()呼び出しで設定された値

3. YAML設定ファイル

4. デフォルト値（最低）

サーバーは以下の場所で設定を探します：

1. configure()呼び出しで指定されたパス

2. MCP_TS_CONFIG_PATH環境変数で指定されたパス

3. デフォルトの場所: ~/.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 - プロジェクト概要解析用のプロンプトを作成

フィードバックとコミュニティ

mcp-server-tree-sitterをどのように使用しているか、またワークフローをより便利にするために何が必要か、ぜひお聞かせください。

• 質問と機能リクエスト: GitHub Discussions

• バグ報告: GitHub Issues

ライセンス

MIT

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• adapt_queryC
• analyze_complexityC
• analyze_projectC
• build_queryC
• check_language_availableC
• clear_cacheC
• configureC
• diagnose_configC