---

What is it?

WLADY_CODE indexes your project, builds a dependency graph, and exposes 27 MCP tools that any compatible AI assistant (Claude, Cursor, etc.) can call to navigate, analyze, and reason about code with surgical precision.

It also spins up a local 3D galaxy visualization at http://localhost:9750 where every file is a star and every dependency is a luminous nebula edge.

┌──────────────────────────────────────────────────────────────────┐
│                        WLADY_CODE MCP                            │
│                                                                  │
│  ┌──────────────────┐   ┌────────────────┐   ┌────────────────┐  │
│  │     Indexer      │──▶│   SQLite DB    │◀──│  27 MCP Tools  │  │
│  │ Tree-sitter AST  │   │ ~/.wlady-code  │   │                │  │
│  │ + regex fallback │   │   -mcp/        │   │ navigation     │  │
│  └──────────────────┘   │   wlady.db     │   │ impact         │  │
│                         └──────┬─────────┘   │ analysis       │  │
│  ┌──────────────────────────┐  │             │ architecture   │  │
│  │  Galaxy UI · :9750       │  │             │ search + RRF   │  │
│  └──────────────────────────┘  │             │ tracing · adr  │  │
│                                │             └────────────────┘  │
│  ┌─────────────────────────────┴──────────┐                      │
│  │  Embeddings  ·  snowflake-arctic-embed  │                      │
│  │  BM25 + vector → RRF hybrid search     │                      │
│  └────────────────────────────────────────┘                      │
└──────────────────────────────────────────────────────────────────┘

---

Why use it?

Question you ask the AI	Tool that answers it
"Where is function X defined?"	where
"If I change this function, what breaks?"	fn_impact
"What will this PR affect in production?"	diff_impact
"Are there dead code, god classes, or circular deps?"	audit
"How is this monorepo layered?"	get_architecture
"What's the call path between module A and B?"	path
"Find code that does something similar to X"	search_graph(semantic: true)
"Trace the execution flow from main"	execution_flow
"Show me all modules visually"	Galaxy UI at :9750

---

Features

Galaxy Visualization

The built-in web UI uses a stellar spectral color system — files are colored like real stars based on their connectivity:

Color	Spectral type	Meaning
Blue-white	O / B	Highly connected hubs — the system's core
White-yellow	A / F	Medium connectivity
Amber	G / K	Supporting files
Red	M	Leaf files — minimal dependencies

Edges use Canvas 2D additive blending (globalCompositeOperation: 'lighter'), making dense dependency clusters glow brighter — the same effect as Three.js AdditiveBlending. Where many imports converge, a nebula appears.

Side panel — 3 tabs:

Tab	Contents
Files	Collapsible file tree with live search. Click any file to fly to its node. Below the tree, a Symbols section shows all functions and classes in the selected file with their line numbers.
Filters	Language chips to show/dim nodes by language. Hop-depth filter (1 / 2 / 3) to focus the graph on the neighbourhood of the selected node using BFS with caching.
Modules	Community list, hotspot files (highest fan-in), and auto-detected entry points (main functions, controllers, routers, index files).

Controls:

Action	Effect
Drag	Rotate the graph
Scroll wheel	Zoom
Click node	Select + highlight its direct connections
Double-click node	Open source code with syntax highlighting
Click symbol in panel	Jump to that function/class in the code panel
Click community	Highlight all files in that module
Double-click empty space	Resume auto-rotation
Esc	Close code panel

The code panel displays line numbers, highlights the exact line range of the selected symbol, auto-scrolls to it, and uses Prism.js syntax highlighting with explicit grammar loading for 18+ languages. Includes an "Open in VS Code" button via the vscode://file/ protocol.

AST Parser — Tree-sitter

Symbol extraction is powered by Tree-sitter, providing a full AST-based parse for 11 languages with automatic fallback to the regex heuristic parser when a grammar isn't available.

Language	Parser
JavaScript, TypeScript, TSX	Tree-sitter
Python, Java, Go, Rust	Tree-sitter
C#, C++, PHP, Ruby	Tree-sitter
All other supported languages	Regex fallback

Semantic Embeddings & Hybrid Search

search_graph supports a hybrid BM25 + vector search mode that finds semantically similar code even when it doesn't share keywords with the query.

How it works:

1. Each symbol is embedded with snowflake-arctic-embed-xs (22M params, 384 dims, ~90 MB, runs fully locally via ONNX Runtime)
2. At query time: BM25 ranks + cosine similarity ranks are fused via Reciprocal Rank Fusion (RRF)
3. Results surface symbols semantically related to the query — not just lexically matching ones

Enable it per project at index time:

index_repository(path: "/my/project", embeddings: true)

Then search:

search_graph(project_id: "...", query: "authentication token validation", semantic: true)

Embeddings are incremental — only new/modified symbols are re-embedded on subsequent runs.

Execution Flow Tracing

Automatically detect and visualize how your application executes from its entry points.

list_entry_points(project_id: "...")

execution_flow(project_id: "...", entry_point: "main", depth: 5)

Entry points are detected by: role classification, name patterns (main, handler, router, start, …), file conventions (index.ts, app.ts, server.ts, …), and HTTP route registration patterns.

The call tree is rendered depth-first with cycle detection (↩ marker) and file:line references at each node.

Docker Support

Run WLADY_CODE in any environment without a local Node.js install:

# Build and start
WORKSPACE_PATH=/path/to/your/repo docker compose up

# Galaxy UI opens at http://localhost:9750

Or with plain Docker:

docker build -t wlady-code-mcp .
docker run -i --rm \
  -p 9750:9750 \
  -v wlady-db:/root/.wlady-code-mcp \
  -v /path/to/repo:/workspace:ro \
  wlady-code-mcp

MCP Tools Reference

Indexing (4 tools)

Tool	Description
index_repository	Index a full project or update incrementally. Pass embeddings: true to generate semantic embeddings (downloads ~90 MB model on first run).
list_projects	List all indexed projects
delete_project	Remove a project from the index
detect_changes	Detect files modified since last index

Navigation (5 tools)

Tool	Description
where	Find where a symbol is defined
context	Full symbol context: definition, callers, callees
path	Shortest call path between two symbols
trace_path	All paths upstream/downstream from a symbol
map	Module map and project structure

Search (4 tools)

Tool	Description
search_code	Grep-like text search across all source files
search_graph	BM25 symbol search. Pass semantic: true for hybrid BM25+vector search with RRF (requires embeddings).
query_graph	Direct graph query with filters (kind, role, complexity, file pattern)
brief	Short summary of a file or module

Process Tracing (2 tools)

Tool	Description
execution_flow	Trace the call tree from an entry point (or auto-detect). Depth-limited BFS with cycle detection.
list_entry_points	Detect likely entry points: main functions, HTTP handlers, controllers, routers

Impact Analysis (3 tools)

Tool	Description
fn_impact	All callers affected by modifying a function
diff_impact	Current git diff → affected symbols
branch_compare	Symbol-level comparison between two branches

Quality & Analysis (4 tools)

Tool	Description
audit	Full audit: dead code, god files, high complexity, circular deps
complexity	Cyclomatic + cognitive complexity report per symbol
roles	Classify symbols by role (entry / core / utility / adapter / dead / leaf)
communities	Community/cluster detection in the graph

Architecture (3 tools)

Tool	Description
get_architecture	High-level view: layers, modules, graph stats
manifesto	Manage quality rules (complexity thresholds, etc.)
check	Evaluate codebase against manifesto rules (PASS / WARN / FAIL)

Architecture Decision Records (3 tools)

Tool	Description
adr_list	List all recorded architecture decisions
adr_create	Record a new architecture decision
adr_update	Update the status of an existing decision

---

Supported Languages

TypeScript · JavaScript · Java · Kotlin · Python · Go · Rust · C · C++ · C# · PHP · Ruby · Swift · Dart · HTML · CSS/SCSS · JSON · YAML · SQL · Bash

---

Installation

Prerequisites

• Node.js 18+
• Claude Desktop, Cursor, or any MCP-compatible client

Linux / macOS — better-sqlite3 and tree-sitter compile native bindings on install, so you need build tools:

# Debian / Ubuntu
sudo apt install python3 make g++

# Fedora / RHEL
sudo dnf install python3 make gcc-c++

# Arch
sudo pacman -S python make gcc

# macOS (Xcode CLI tools)
xcode-select --install

Quick Start — npx (recommended)

No clone or build step required. Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "wlady-code": {
      "command": "npx",
      "args": ["-y", "wlady-code-mcp"]
    }
  }
}

Or via the Claude Code CLI:

claude mcp add wlady-code -s user -- npx -y wlady-code-mcp

npx downloads and runs the latest published version automatically. No path configuration needed.

Build from Source

Only needed if you want to contribute or run a local development build:

git clone https://github.com/wladimania93/wlady-code-mcp
cd wlady-code-mcp
npm install --legacy-peer-deps   # required for tree-sitter grammar compatibility
npm run build

Then register the local build:

claude mcp add wlady-code -s user -- node "/absolute/path/to/wlady-code-mcp/dist/index.js"

Or manually in claude_desktop_config.json:

{
  "mcpServers": {
    "wlady-code": {
      "command": "node",
      "args": ["/absolute/path/to/wlady-code-mcp/dist/index.js"]
    }
  }
}

Index your first project

Ask your AI assistant:

Index the project at /path/to/my-project

Or call the tool directly:

index_repository(path: "/path/to/my-project", name: "My Project")

The galaxy visualization opens automatically at http://localhost:9750.

To enable semantic search:

index_repository(path: "/path/to/my-project", embeddings: true)

The first run downloads the snowflake-arctic-embed-xs model (~90 MB) into ~/.wlady-code-mcp/models/ and caches it for all future runs.

Environment variables

Variable	Value	Effect
WLADY_UI_PORT	number	Change UI port (default: 9750)
WLADY_UI_PORT	0	Disable the UI entirely

---

Troubleshooting

Node.js 24 — compilation error (tree-sitter)

Symptom: MSBuild exited with code 1 / node-gyp rebuild failed with #error "C++20 or later required." on Windows.

Cause: Some tree-sitter grammar packages (tree-sitter-cpp, tree-sitter-java, tree-sitter-ruby, etc.) ship .gyp build files that force /std:c++17, which conflicts with the C++20 requirement introduced in Node.js 24 (V8).

Fix: Use Node.js 22 LTS until the upstream grammar packages are updated.

# with nvm (recommended)
nvm install 22
nvm use 22

# verify
node -v   # should print v22.x.x

Node 24 is explicitly blocked in engines (<24.0.0) so npx and npm will warn you if your version is unsupported.

---

Peer dependency conflicts (ERESOLVE)

Symptom: npm ERR! ERESOLVE overriding peer dependency during install.

Cause: Some grammar packages declare peer requirements for older tree-sitter minor versions (e.g. ^0.21.x). The project ships a .npmrc with legacy-peer-deps=true to resolve this automatically. If you are cloning and building from source, this file is included.

If you hit the error anyway:

npm install --legacy-peer-deps

---

EBUSY during reinstallation (Windows)

Symptom: npm ERR! EBUSY: resource busy or locked on better-sqlite3.

Cause: A Node.js process (Claude Code, VS Code extension, or the MCP server itself) still holds the native .node DLL open.

Fix: Before running npm install or npm update:

1. Close VS Code (or any IDE with the MCP extension loaded)
2. Close Claude Desktop / Claude Code
3. Kill any running node process that may have loaded the MCP

Then retry the install.

---

Project Structure

wlady-code-mcp/
├── src/
│   ├── index.ts              # MCP entry point + UI server bootstrap
│   ├── types.ts              # Shared types
│   ├── db/                   # SQLite access layer + schema (incl. embeddings table)
│   ├── parser/
│   │   ├── index.ts          # Parser orchestrator (tree-sitter → regex fallback)
│   │   ├── tree-sitter.ts    # AST parser for 11 languages
│   │   └── languages.ts      # Language configs for regex fallback
│   ├── embeddings/
│   │   └── embedder.ts       # snowflake-arctic-embed-xs singleton, batch embedding
│   ├── indexer/              # Index orchestrator + incremental updates + embedding generation
│   ├── graph/                # BFS, DFS, shortest path, cycle detection
│   ├── search/
│   │   ├── bm25.ts           # BM25 full-text search engine
│   │   └── hybrid.ts         # RRF: BM25 + vector search fusion
│   ├── analysis/
│   │   ├── complexity.ts     # Cyclomatic + cognitive complexity
│   │   ├── roles.ts          # Symbol role classifier
│   │   └── entry-points.ts   # Entry point detection (name/file/body patterns)
│   ├── git/                  # Git integration (diff, branch compare)
│   ├── tools/                # All 27 MCP tool handlers (one file per category)
│   └── visualization/
│       ├── graph-data.ts     # SQLite → graph data queries
│       ├── server.ts         # HTTP server :9750 + /api/file endpoint
│       └── template.ts       # Self-contained UI (HTML + CSS + JS, ~34 KB)
├── Dockerfile                # Multi-stage alpine build
├── docker-compose.yml        # Compose with workspace volume + DB persistence
└── dist/                     # Compiled output (run after npm run build)

---

Tech Stack

Layer	Technology
Runtime	Node.js 18+ · ES Modules
MCP	@modelcontextprotocol/sdk
Database	better-sqlite3 (embedded, synchronous)
AST Parsing	tree-sitter + 11 language grammars (MIT)
Embeddings	@huggingface/transformers · snowflake-arctic-embed-xs (Apache-2.0)
Git	simple-git
File watching	chokidar
Visualization	Canvas 2D · Prism.js
HTTP server	Node.js built-in http (no Express)
Container	Docker · Alpine Linux

---

Inspiration & Credits

WLADY_CODE was built by combining and extending the best of three excellent projects:

codebase-memory-mcp

The visual philosophy: represent a codebase as a galaxy where file importance maps to stellar spectral type, and dependency density creates glowing nebulae via additive color blending. The O/B/A/F/G/K/M spectral color system and the 3D graph architecture are directly inspired by their React + Three.js + Bloom implementation. Our version reimplements it with native Canvas 2D — eliminating build dependencies and serving a fully self-contained UI from the MCP process itself.

ops-codegraph-tool

The analysis philosophy: treat a codebase as a queryable knowledge graph, with specialized tools for navigation (where is X, what calls Y), impact analysis (if I change Z, what breaks), and quality auditing (dead code, complexity, circular dependencies). The modular handler structure by category and the real-time git integration are directly influenced by this project.

GitNexus

The precision philosophy: AST-level parsing with Tree-sitter for accurate symbol extraction across languages, local vector embeddings for semantic code search, and Reciprocal Rank Fusion to combine keyword and semantic rankings into a single high-quality result set. The approach to embedding storage, the RRF fusion algorithm, and the entry-point tracing patterns were designed with GitNexus as a reference for what best-in-class code intelligence looks like.

The synthesis: an MCP that sees code as a graph (codegraph), renders it as a galaxy (codebase-memory), and understands it semantically (GitNexus) — all inside a single server, MIT licensed, with no external services required.

---

Changelog

v0.3.0

• Galaxy UI — major panel overhaul inspired by GitNexus:
  • Left panel with 3 tabs: Files, Filters, Modules
  • Collapsible file tree with live search
  • Symbol list per file (functions/classes with line numbers)
  • Language filter chips (toggle dimming by language)
  • Hop-depth BFS filter (1/2/3 hops from selected node, cached)
  • Modules tab: communities, hotspot files, auto-detected entry points
  • Status bar showing project name, node count, edge count
• Code panel: line numbers, highlighted symbol range, auto-scroll, fixed text color on dark background
• New API endpoints: /api/symbols, /api/entry-points

v0.2.0

• Tree-sitter AST parser for 11 languages
• Semantic embeddings + hybrid BM25/vector search (RRF)
• Execution flow tracing (execution_flow, list_entry_points)
• Docker support
• 27 MCP tools

---