skills / tree-sitter.md
skills / tree-sitter.md
This guide provides instructions for LLMs on how to effectively use the tree-sitter-mcp toolset to perform deep code analysis, structural querying, and project navigation.
Before performing any analysis, you MUST ensure a project is registered. If you try to call analysis tools (like tsm_get_file, tsm_run_query) without a registered project, the tools will fail.
Step 1: Check if a project exists
Call tsm_list_projects_tool first. If the list is empty, you must proceed to Step 2.
Step 2: Register the project
Identify the root directory of the source code and call:
tsm_register_project_tool(project_name="my_project", root_path="/path/to/source")
Note: Replace /path/to/source with the actual absolute path of the codebase.
Step 3: Proceed with analysis Once the project is registered, you can use all other tools.
The tree-sitter-mcp toolset allows you to interact with source code at a structural level rather than just a text level.
tsm_list_languages: List all supported languages.tsm_check_language_available(language): Verify if a specific language is supported.tsm_register_project_tool(project_name, root_path): REQUIRED FIRST STEP to register a codebase.tsm_list_projects_tool: List all registered projects.tsm_remove_project_tool(project_name): Remove a project from the registry.Use these tools to inspect the structure of specific files.
tsm_list_files: List files within the current project scope.tsm_get_file_metadata(path): Get basic information about a file.tsm_get_file(path): Retrieve the content of a file.tsm_get_ast(path): Get the full Abstract Syntax Tree of a file.tsm_get_node_at_position(path, line, column): Get the specific AST node at a given coordinate.Use these tools for high-level project insights and finding code.
tsm_find_text(query): Simple text-based search.tsm_get_symbols(path): List all symbols (functions, classes, variables) in a file.Use these tools for complex, pattern-based searching.
tsm_list_query_templates_tool: View available query templates.tsm_get_query_template_tool(template_name): Get a specific query template.tsm_build_query(query_string): Compile a raw Tree-sitter query into an executable format.tsm_adapt_query(query, context): Modify a query based on specific context.tsm_run_query(query): Execute a compiled query against the project.tsm_configure(config_yaml): Apply new YAML configurations.tsm_diagnose_config: Check for errors in the current configuration.tsm_clear_cache: Clear the internal cache to refresh indices.tsm_register_project_tool first.tsm_list_languages to verify supported types.tsm_run_query fails, it is likely a syntax error in the query string. Use tsm_build_query to verify the string first.This guide provides instructions for LLMs on how to effectively use the tree-sitter-mcp toolset to perform deep code analysis, structural querying, and project navigation.
Before performing any analysis, you MUST ensure a project is registered. If you try to call analysis tools (like tsm_get_file, tsm_run_query) without a registered project, the tools will fail.
Step 1: Check if a project exists
Call tsm_list_projects_tool first. If the list is empty, you must proceed to Step 2.
Step 2: Register the project
Identify the root directory of the source code and call:
tsm_register_project_tool(project_name="my_project", root_path="/path/to/source")
Note: Replace /path/to/source with the actual absolute path of the codebase.
Step 3: Proceed with analysis Once the project is registered, you can use all other tools.
The tree-sitter-mcp toolset allows you to interact with source code at a structural level rather than just a text level.
tsm_list_languages: List all supported languages.tsm_check_language_available(language): Verify if a specific language is supported.tsm_register_project_tool(project_name, root_path): REQUIRED FIRST STEP to register a codebase.tsm_list_projects_tool: List all registered projects.tsm_remove_project_tool(project_name): Remove a project from the registry.Use these tools to inspect the structure of specific files.
tsm_list_files: List files within the current project scope.tsm_get_file_metadata(path): Get basic information about a file.tsm_get_file(path): Retrieve the content of a file.tsm_get_ast(path): Get the full Abstract Syntax Tree of a file.tsm_get_node_at_position(path, line, column): Get the specific AST node at a given coordinate.Use these tools for high-level project insights and finding code.
tsm_find_text(query): Simple text-based search.tsm_get_symbols(path): List all symbols (functions, classes, variables) in a file.Use these tools for complex, pattern-based searching.
tsm_list_query_templates_tool: View available query templates.tsm_get_query_template_tool(template_name): Get a specific query template.tsm_build_query(query_string): Compile a raw Tree-sitter query into an executable format.tsm_adapt_query(query, context): Modify a query based on specific context.tsm_run_query(query): Execute a compiled query against the project.tsm_configure(config_yaml): Apply new YAML configurations.tsm_diagnose_config: Check for errors in the current configuration.tsm_clear_cache: Clear the internal cache to refresh indices.tsm_register_project_tool first.tsm_list_languages to verify supported types.tsm_run_query fails, it is likely a syntax error in the query string. Use tsm_build_query to verify the string first.tsm_get_node_types: List available node types for a language.tsm_analyze_projecttsm_analyze_complexity(path): Analyze the cyclomatic complexity of a file.tsm_get_dependencies(path): Identify dependencies for a specific module/file.tsm_find_similar_code(path): Find code snippets structurally similar to the provided path.tsm_find_usage(symbol): Find usage of a symbol.Chain of Thought: For any request involving "finding code" or "analyzing a function":
tsm_list_files to find the correct path.tsm_get_symbols or tsm_get_file to understand the content.tsm_get_ast to understand the structural logic.tsm_run_query if looking for specific patterns across multiple files.Handle Paths Carefully: Always use paths relative to the project root once a project is registered.
Use Query Templates: Before running a complex query, call tsm_list_query_templates_tool to see if a pre-defined template exists that matches your goal.
tsm_get_node_types: List available node types for a language.tsm_analyze_projecttsm_analyze_complexity(path): Analyze the cyclomatic complexity of a file.tsm_get_dependencies(path): Identify dependencies for a specific module/file.tsm_find_similar_code(path): Find code snippets structurally similar to the provided path.tsm_find_usage(symbol): Find usage of a symbol.Chain of Thought: For any request involving "finding code" or "analyzing a function":
tsm_list_files to find the correct path.tsm_get_symbols or tsm_get_file to understand the content.tsm_get_ast to understand the structural logic.tsm_run_query if looking for specific patterns across multiple files.Handle Paths Carefully: Always use paths relative to the project root once a project is registered.
Use Query Templates: Before running a complex query, call tsm_list_query_templates_tool to see if a pre-defined template exists that matches your goal.