zheroz00/visual-tree-explorer

Visual Tree Explorer (VTE)

An MCP server for efficient codebase exploration. Provides file tree visualization, symbol extraction, and dependency analysis in a single tool call.

Why VTE?

Traditional codebase exploration requires multiple tool calls:

find . -name "*.ts"           # Find files
grep -r "function" src/       # Search content
cat src/index.ts              # Read file
# ... repeat for each file

VTE consolidates this into one call that returns a complete picture:

• File tree with sizes and line counts
• Code previews (configurable lines)
• AST-parsed symbols (functions, classes, interfaces)
• Import/export relationships
• Dependency graph with circular dependency detection

This reduces context usage and provides richer information than sequential grep/cat commands.

How It Works

1. Tree Traversal: Recursively walks the directory with configurable depth and skip patterns
2. Symbol Extraction: Uses TypeScript compiler API for accurate AST parsing (not regex)
3. Dependency Analysis: Builds import/export graph, detects circular dependencies, calculates module cohesion
4. Formatted Output: Returns structured ASCII tree or JSON

Symbol Extraction

VTE uses the TypeScript compiler API to parse code, providing:

• 100% accurate symbol detection (vs ~70% with regex)
• Proper handling of complex syntax (destructuring, re-exports)
• Export detection with ✓ exported markers
• Only top-level symbols (no noise from local variables)

Dependency Graph

When enabled, analyzes the entire codebase to provide:

• Import/export relationships per file
• Circular dependency detection with full paths
• Module clusters by directory
• Most-connected file identification

Parameters

Search Prefixes

• function:name - Find functions/methods
• content:text - Search file contents
• import:package - Find import statements
• regex:pattern - Regex matching

Default Skip Patterns

Automatically skips: node_modules, .git, dist, build, .next, out, coverage, .cache, *.log, .DS_Store, tmp, temp, __pycache__, .nyc_output, .turbo, .vercel, .netlify, package-lock.json, yarn.lock, pnpm-lock.yaml, *.d.ts

Example Output

└── 📁 src (13 files)
    ├── 📝 ast-symbols.ts (291 lines, 9.2KB)
    │   ├── 👁️ Preview:
    │   │   1: import { promises as fs } from 'fs';
    │   │   2: import path from 'path';
    │   ├── 🔷 Symbols:
    │   │   ├── ASTSymbol (interface)
    │   │   ├── extractASTSymbols (function) ✓ exported
    │   │   ├── shouldUseAST (function) ✓ exported
    ├── 📝 explorer.ts (704 lines, 20.0KB)
    │   ├── 👁️ Preview:
    │   │   1: import { promises as fs, Stats } from 'fs';
    │   │   2: import path from 'path';
    │   ├── 🔷 Symbols:
    │   │   ├── validatePath (function)
    │   │   ├── exploreTree (function) ✓ exported
    │   │   ├── traverseDirectory (function)
    │   │   └── ... (19 total)
    └── 📝 types.ts (326 lines, 9.7KB)
        ├── 🔷 Symbols:
        │   ├── ExploreTreeParams (interface) ✓ exported
        │   ├── TreeNode (interface) ✓ exported
        │   ├── SymbolKind (enum) ✓ exported
        │   └── ... (20 total)

With show_dependency_graph: true:

🕸️  13 files, 24 deps

🌟 Most Connected: explorer.ts

Recent Updates (v1.1)

• MCP SDK 1.23.0 - Updated from 0.5.0
• Symbol filtering - Only top-level symbols extracted (no local variables)
• Input validation - Bounded parameters prevent excessive output
• Path security - Validates paths, prevents traversal attacks and symlink escapes
• Output limits - max_symbols, symbols_only_exported parameters for lean output

v1.1 Symbol Reduction

The symbol extraction was rewritten to only capture top-level declarations, dramatically reducing output noise:

Why this matters: v1.0 extracted every const, let, and variable inside functions - noise that consumed context tokens without providing architectural insight. v1.1 extracts only what matters: exported functions, classes, interfaces, and top-level declarations.

Result: ~80% smaller output with the same useful information.

Architecture

src/
├── index.ts           # MCP server entry point
├── explorer.ts        # Main orchestrator with path validation
├── ast-symbols.ts     # TypeScript compiler API symbol extraction
├── symbols.ts         # Symbol extraction dispatcher
├── dependency-graph.ts # Import/export analysis
├── formatter.ts       # ASCII tree formatting
├── types.ts           # TypeScript interfaces
└── ...

Build

npm install && npm run build