WLADY_CODE MCP

Advanced codebase intelligence for AI assistants

🌐 English · Español

An MCP server that turns any codebase into a queryable knowledge graph — and renders it as an interactive galaxy.

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     │                      │
│  └────────────────────────────────────────┘                      │
└──────────────────────────────────────────────────────────────────┘

Related MCP server: Orihime

Why use it?

Features

Galaxy Visualization

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

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:

Controls:

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.

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

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

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

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

WLADY_CODE v0.3.0 · Built with Node.js · Powered by MCP