Skip to main content
Glama

WLADY_CODE MCP

Advanced codebase intelligence for AI assistants

Version Node MCP License

🌐 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?

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

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

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

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

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

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

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

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

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)

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

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


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

Available Tools

28 tools
adr_createC

Create a new Architecture Decision Record.

Inputs: title (required), project_id (required), status, context, +2 more.

adr_listC

List Architecture Decision Records (ADRs) for the project.

Inputs: project_id (required), number, status.

adr_updateB

Update an existing Architecture Decision Record.

Inputs: number (required), project_id (required), title, status, +3 more.

auditB

Audit the codebase for quality issues: dead code, high complexity, missing coverage, circular deps.

Inputs: project_id (required), checks.

branch_compareC

Compare symbols between two git branches to see what changed.

Inputs: base (required), head (required), project_id (required), project_path (required).

briefA

Get a brief overview of a file: its symbols, imports, and exports.

Inputs: file (required), project_id (required).

checkB

Run manifesto checks against the current codebase state. Returns PASS/WARN/FAIL per rule.

Inputs: project_id (required).

communitiesC

Detect code communities/clusters using graph connectivity analysis.

Inputs: project_id (required), min_size.

complexityB

Show complexity metrics for symbols in the project, sorted by complexity.

Inputs: project_id (required), file, limit, min_cyclomatic.

contextA

Get the context around a symbol: its definition, callers, callees, and file siblings.

Inputs: symbol (required), project_id (required), radius.

delete_projectB

Remove a project and all its indexed data from the database.

Inputs: project_id (required).

detect_changesB

Detect which files have changed since last index (using mtime/hash comparison).

Inputs: project_id (required).

diff_impactC

Analyze the impact of current git changes: which symbols are affected and who calls them.

Inputs: project_id (required), project_path (required), staged.

execution_flowA

Trace the execution flow from an entry point (or auto-detect entry points). Shows the call tree depth-first with cycle detection.

Inputs: project_id (required), depth, entry_point.

fn_impactB

Analyze the impact of changing a function: find all upstream callers affected.

Inputs: symbol (required), project_id (required), max_depth.

get_architectureB

Get a high-level architecture overview: layers, modules, dependency graph summary.

Inputs: project_id (required), project_path.

index_repositoryA

Index a code repository to build the symbol graph. Supports incremental updates.

Inputs: path (required), name, embeddings, force_rebuild.

list_entry_pointsA

Detect and list likely entry points in a project (main, handlers, HTTP routes, etc.).

Inputs: project_id (required), limit.

list_projectsB

List all indexed projects with their stats.

Inputs: no named parameters.

manifestoC

Manage project quality manifesto rules (thresholds for complexity, dead code, etc.).

Inputs: action (required), project_id (required), metric, rule_name, +2 more.

mapB

Get a structural map of the project: top files by connectivity, module clusters.

Inputs: project_id (required), limit.

pathC

Find the shortest call path between two symbols.

Inputs: to (required), from (required), project_id (required).

query_graphC

Run a raw SQL-like structured query against the symbol graph.

Inputs: project_id (required), limit, filter, order_by.

rolesB

Classify and display the roles of symbols in the project (entry, core, utility, adapter, dead, leaf).

Inputs: project_id (required), reclassify, filter_role.

search_codeA

Search source code text across all files in the project (grep-like).

Inputs: query (required), project_id (required), limit.

search_graphA

Search over the symbol graph. BM25 by default; pass semantic:true for hybrid BM25+vector search (requires embeddings to be generated during index_repository).

Inputs: query (required), project_id (required), kinds, limit, +1 more.

trace_pathB

Trace all call paths from a symbol (upstream callers or downstream callees).

Inputs: symbol (required), project_id (required), direction, max_depth.

whereC

Find where a symbol is defined.

Inputs: symbol (required), project_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 28 tools

    Disambiguation4/5

    Most tools are clearly distinct, but some overlap exists between trace_path and execution_flow, and between audit, check, and manifesto. Overall, the boundaries are well-defined.

    Naming Consistency3/5

    Naming is mostly lower_case with underscores, but patterns vary (verb_noun, noun_verb, single verb). Consistency is moderate; not chaotic but not uniform.

    Tool Count3/5

    28 tools is high but justified by the broad code analysis domain. It slightly exceeds the ideal range, but each tool serves a distinct purpose.

    Completeness5/5

    The tool set covers indexing, searching, architecture, impact analysis, quality checks, ADR management, and more. No obvious gaps for the stated purpose.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that transforms codebases into knowledge graphs using Neo4J, enabling AI assistants to understand code structure, relationships, and metrics for more context-aware assistance.
      28
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Cross-repository code knowledge graph MCP server for Java, Kotlin, JavaScript, and TypeScript. Indexes source code into embedded KuzuDB via tree-sitter and exposes 30+ tools for call-flow tracing, multi-hop taint analysis (OWASP/CWE/PCI/STIG), entry-point reachability filtering, performance hotspot detection, and license compliance β€” without reading source files. 95% fewer tokens vs source-read
      33
      2
      MIT