{"id":50699628,"url":"https://github.com/ralscha/tree-sitter-mcp","last_synced_at":"2026-06-09T08:32:49.958Z","repository":{"id":362874805,"uuid":"1254868383","full_name":"ralscha/tree-sitter-mcp","owner":"ralscha","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-06T09:28:15.000Z","size":64,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T11:13:36.910Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ralscha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-31T05:11:16.000Z","updated_at":"2026-06-06T09:28:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ralscha/tree-sitter-mcp","commit_stats":null,"previous_names":["ralscha/tree-sitter-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ralscha/tree-sitter-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralscha%2Ftree-sitter-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralscha%2Ftree-sitter-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralscha%2Ftree-sitter-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralscha%2Ftree-sitter-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ralscha","download_url":"https://codeload.github.com/ralscha/tree-sitter-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralscha%2Ftree-sitter-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34098932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T08:32:49.334Z","updated_at":"2026-06-09T08:32:49.952Z","avatar_url":"https://github.com/ralscha.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tree-sitter-mcp\n\nAn [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives AI assistants structured access to codebases via [tree-sitter](https://tree-sitter.github.io/). It can parse ASTs, extract symbols, run S-expression queries, find similar code, and analyze project structure through a standardized MCP interface.\n\n## Features\n\n- **20+ MCP tools** covering file ops, AST inspection, symbol extraction, text/regex search, tree-sitter queries, complexity analysis, and more\n- **Bundled parsers** for C, C++, Go, HTML, Java, JavaScript, JSON, PHP, Python, Ruby, and Rust\n- **Extension detection** for additional file types in project summaries and file filtering\n- **Project registry** to register multiple project directories and scope operations to each\n- **AST as JSON** with full or depth-limited abstract syntax trees\n- **Symbol extraction** using built-in query templates\n- **S-expression queries** with direct tree-sitter query execution\n- **Query builder** for combining query templates and adapting queries across languages\n- **Structural search** using AST fingerprinting and Jaccard similarity\n- **Parse tree caching** with configurable in-memory cache size and TTL\n- **Pre-parsing** via `--pre-parse` to warm the parse cache at startup\n- **YAML configuration** for cache size, file security limits, excluded dirs, and more\n- **Diagnostics** with `diagnose_config` for troubleshooting YAML config loading\n\n## Installation\n\nBuild from source with Go and Task:\n\n```sh\ntask build\n```\n\nThe binary is written to `bin/tree-sitter-mcp` or `bin/tree-sitter-mcp.exe` on Windows. Note that the build requires CGO to compile the bundled tree-sitter parsers, so ensure you have a C compiler installed and configured.\n\n## Usage\n\n### Command-line Flags\n\n```text\ntree-sitter-mcp [flags]\n\nFlags:\n  --config string       Path to YAML configuration file\n  --debug               Enable debug logging\n  --disable-cache       Disable parse tree caching\n  --pre-parse string    Pre-parse all source files in a directory at startup\n  --transport string    MCP transport: stdio or sse (default \"stdio\")\n  --http-addr string    HTTP listen address when using SSE (default \":8080\")\n  --sse-path string     SSE endpoint path when using SSE (default \"/sse\")\n  --version             Show version and exit\n```\n\n### Running as an MCP Server\n\nBy default, the server communicates over stdio. Configure your MCP client to launch it:\n\n```json\n{\n  \"mcpServers\": {\n    \"tree-sitter\": {\n      \"command\": \"/path/to/bin/tree-sitter-mcp\",\n      \"args\": [\"--config\", \"/path/to/config.yaml\"]\n    }\n  }\n}\n```\n\nTo serve MCP over SSE instead, run the server as an HTTP process:\n\n```sh\ntree-sitter-mcp --transport sse --http-addr :8080 --sse-path /sse\n```\n\nThen configure an SSE-capable MCP client to connect to:\n\n```text\nhttp://localhost:8080/sse\n```\n\nThe same settings can be provided with `MCP_TS_TRANSPORT`, `MCP_TS_HTTP_ADDR`, and `MCP_TS_SSE_PATH`.\n\n### Pre-parsing a Project\n\nUse `--pre-parse` to walk a directory and parse source files with bundled parsers into the cache before the MCP server starts accepting requests. This eliminates first-query latency for subsequent `get_ast`, `run_query`, and `get_symbols` calls.\n\n```sh\ntree-sitter-mcp --debug --pre-parse /path/to/project\n```\n\nHidden files/directories (`.git`, `.vscode`, etc.) and configured `excluded_dirs` are skipped. The server logs a summary after pre-parsing completes:\n\n```text\nPre-parsing project at /path/to/project ...\nPre-parse complete: 142 files scanned, 130 parsed, 10 skipped, 2 errors in 2.3s\n  go: 85 files\n  python: 30 files\nStarting tree-sitter MCP server (cache: true, max_file_size: 5MB, max_depth: 5)\n```\n\n## Configuration\n\nCreate a YAML config file. Defaults are used when no config file is supplied.\n\n```yaml\ncache:\n  enabled: true\n  max_size_mb: 100\n  ttl_seconds: 300\n\nsecurity:\n  max_file_size_mb: 5\n  allowed_extensions: []\n  excluded_dirs:\n    - .git\n    - node_modules\n    - __pycache__\n    - .venv\n    - venv\n    - .tox\n\nlanguage:\n  default_max_depth: 5\n  preferred_languages:\n    - go\n    - python\n\nlog_level: INFO\nmax_results_default: 100\n```\n\nEnvironment variable overrides currently supported:\n\n- `MCP_TS_LOG_LEVEL`\n- `MCP_TS_CACHE_MAX_SIZE_MB`\n- `MCP_TS_TRANSPORT`\n- `MCP_TS_HTTP_ADDR`\n- `MCP_TS_SSE_PATH`\n\n## MCP Tools\n\n### Project Management\n\n| Tool | Description |\n|------|-------------|\n| `register_project` | Register a project directory for code exploration |\n| `list_projects` | List all registered projects |\n| `remove_project` | Remove a registered project |\n| `analyze_project` | Analyze project structure: file counts, languages, top-level files |\n\n### File Operations\n\n| Tool | Description |\n|------|-------------|\n| `list_files` | List files in a project, filtered by basename/path glob, depth, and extensions |\n| `get_file` | Get file content with optional line range limits |\n| `get_file_metadata` | Get file metadata (size, modification time, language) |\n\n### AST \u0026 Parsing\n\n| Tool | Description |\n|------|-------------|\n| `get_ast` | Get the full AST for a file as nested JSON |\n| `get_node_at_position` | Find the AST node at a specific row/column |\n| `list_languages` | List available tree-sitter languages |\n| `check_language` | Check if a language parser is available |\n\n### Symbols\n\n| Tool | Description |\n|------|-------------|\n| `get_symbols` | Extract symbols from a file |\n| `find_usage` | Find usages of a symbol/identifier across project files |\n| `get_dependencies` | Find the dependencies/imports/includes of a file |\n\n### Search\n\n| Tool | Description |\n|------|-------------|\n| `find_text` | Search for text/regex in project files with file-pattern and context-line support |\n| `find_similar_code` | Find structurally similar code using AST fingerprinting |\n| `run_query` | Run a raw tree-sitter S-expression query on project files |\n\n### Queries\n\n| Tool | Description |\n|------|-------------|\n| `get_query_template` | Get a predefined tree-sitter query template |\n| `list_query_templates` | List available tree-sitter query templates |\n| `build_query` | Combine multiple templates/patterns into a compound query |\n| `adapt_query` | Adapt a query from one language to another by translating node types |\n| `get_node_types` | Get descriptions of common AST node types for a language |\n\n### Analysis\n\n| Tool | Description |\n|------|-------------|\n| `analyze_complexity` | Analyze line count, function count, and average function length |\n\n### Utilities\n\n| Tool | Description |\n|------|-------------|\n| `configure` | Dynamically reconfigure server settings at runtime |\n| `clear_cache` | Clear the parse tree cache, optionally scoped to project/file |\n| `diagnose_config` | Diagnose YAML configuration loading issues |\n\n## Language Support\n\nBundled tree-sitter parsers are available for AST, query, symbol, dependency, complexity, and similarity operations:\n\n| Language | Extensions |\n|----------|-----------|\n| C | `.c`, `.h` |\n| C++ | `.cpp`, `.cc`, `.hpp` |\n| Go | `.go` |\n| HTML | `.html` |\n| Java | `.java` |\n| JavaScript | `.js`, `.jsx` |\n| JSON | `.json` |\n| PHP | `.php` |\n| Python | `.py` |\n| Ruby | `.rb` |\n| Rust | `.rs` |\n\nThe server also recognizes these extensions for detection and project summaries, but parser-backed tools require a bundled or manually registered parser:\n\n| Language | Extensions |\n|----------|-----------|\n| C# | `.cs` |\n| TypeScript | `.ts`, `.tsx` |\n| Kotlin | `.kt` |\n| Swift | `.swift` |\n| Dart | `.dart` |\n| Scala | `.scala` |\n| Lua | `.lua` |\n| Haskell | `.hs` |\n| OCaml | `.ml` |\n| Elixir | `.ex`, `.exs` |\n| Clojure | `.clj` |\n| Elm | `.elm` |\n| Bash | `.sh` |\n| SQL | `.sql` |\n| YAML | `.yaml`, `.yml` |\n| CSS | `.css` |\n| SCSS | `.scss`, `.sass` |\n| Markdown | `.md` |\n| Protobuf | `.proto` |\n| XML | `.xml` |\n\n## Development\n\n```bash\n# Build\ntask build\n\n# Run tests\ntask test\n\n# Format code\ntask format\n\n# Lint (requires Docker)\ntask lint\n\n# Tidy dependencies\ntask tidy\n```\n\n## Demo: Eino Architecture Detective\n\nThe repository includes a runnable Eino demo in `demos/eino-architecture-detective`. It launches this MCP server over stdio, uses the MCP tools to gather tree-sitter evidence from a target codebase, and asks an OpenAI-compatible Eino chat model to produce an architecture report.\n\nCreate `.env` from `.env.example`, fill in `OPENAI_API_KEY`, then run:\n\n```bash\ntask demo:eino\n```\n\nYou can also point it at another project and add a focus question:\n\n```bash\ntask demo:eino TARGET=/path/to/project FOCUS=\"Where is the core domain logic?\"\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fralscha%2Ftree-sitter-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fralscha%2Ftree-sitter-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fralscha%2Ftree-sitter-mcp/lists"}