How the Graph Visualization UI Works in Codebase Memory MCP: Architecture and Setup Guide

The graph visualization UI is an optional React and Three.js frontend that renders an interactive 3D knowledge graph when enabled via the --ui flag, served by an embedded HTTP server on port 9749.

The graph visualization UI in the DeusData/codebase-memory-mcp repository provides a browser-based interface for exploring codebase relationships as interactive 3D networks. Unlike the default headless mode, this UI variant bundles a React application that communicates with the MCP daemon via JSON-RPC endpoints. Understanding the architecture and activation process allows developers to leverage visual graph analysis for large-scale codebases.

Architecture Overview

The UI implementation spans two distinct layers: a compiled React frontend and an embedded HTTP server written in C. When built with the UI variant, the binary serves static assets from graph-ui/dist/ while simultaneously exposing RESTful endpoints for graph data retrieval.

Core frontend components reside in the graph-ui/ directory and include:

• graph-ui/src/main.tsx – Boots the React application via createRoot(...).render(<App/>)
• graph-ui/src/App.tsx – Handles routing and tab selection (graph, stats, control) based on URL query parameters
• graph-ui/src/components/GraphScene.tsx – Manages the Three.js canvas, creating meshes for nodes and edges while handling camera interactions
• graph-ui/src/components/GraphTab.tsx – Controls the graph interface including node budgets, filtering toggles, and the detail sidebar
• graph-ui/src/hooks/useGraphData.ts – Wraps the /api/layout endpoint with streaming support and download progress tracking
• graph-ui/src/api/rpc.ts – Provides a minimal JSON-RPC client for tool invocation

The server-side implementation in src/ui/http_server.c registers HTTP routes including /api/layout, /api/repo-info, and /rpc, enabling the frontend to query the underlying knowledge graph.

Data Flow from Server to Screen

Understanding the request lifecycle clarifies how the system handles large graph layouts efficiently.

1. Static asset delivery – When accessing http://localhost:9749, the server serves the compiled React bundle from graph-ui/dist/
2. Layout computation – GraphTab invokes useGraphData().fetchOverview(), which triggers a GET request to /api/layout?project=…&max_nodes=…
3. Streaming response – The daemon processes the request, runs the layout algorithm, and streams a JSON payload containing node coordinates (x, y, z), edge mappings, and metadata
4. Scene construction – GraphScene.tsx receives the parsed data and instantiates Three.js meshes for each node and edge, applying display density settings from density.ts
5. State persistence – All UI preferences (node budgets, filter selections, panel widths) serialize to localStorage via helpers in GraphTab.tsx (lines 44-52)

Enabling the Graph Visualization UI

The UI is not included in default binary builds. You must install or build the UI-specific variant.

Installation via Install Script

The quickest method uses the official installer with the --ui flag:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh \
| bash -s -- --ui

This executes scripts/build.sh --with-ui, linking the React assets directly into the final executable.

Package Manager Installation

For Node.js or Python environments, set the CBM_VARIANT environment variable:

# npm installation

CBM_VARIANT=ui npm install -g codebase-memory-mcp

# PyPI installation

CBM_VARIANT=ui pip install codebase-memory-mcp

Manual Installation

Download the pre-built UI variant from the Releases page:

wget https://github.com/DeusData/codebase-memory-mcp/releases/download/vX.X.X/codebase-memory-mcp-ui-linux-x64.tar.gz
tar -xzf codebase-memory-mcp-ui-linux-x64.tar.gz

Starting the Server

Launch the UI-enabled daemon on the default port (9749):

codebase-memory-mcp --ui=true --port=9749

Verify the server is serving the interface:

curl -s http://localhost:9749 | grep "Codebase Memory"

Open your browser to http://localhost:9749, select a project from the Projects tab, then navigate to the Graph tab to explore the 3D visualization.

Key Implementation Details

Fetching Graph Data（useGraphData.ts）

The fetchLayout function streams large graph data while reporting progress. Located in graph-ui/src/hooks/useGraphData.ts (lines 43-84), it handles the chunked transfer from /api/layout:

import { fetchLayout } from "./hooks/useGraphData";

async function loadGraph(project: string) {
  const data = await fetchLayout(project, 5000, (prog) => {
    console.log(`Loaded ${prog.receivedBytes}/${prog.totalBytes} bytes`);
  });
  console.log(`Graph has ${data.nodes.length} nodes`);
}

Rendering the 3D Scene（GraphScene.tsx）

The GraphScene component in graph-ui/src/components/GraphScene.tsx initializes the Three.js scene, camera, and renderer. It creates instanced meshes for nodes and edges, optimizing memory usage for graphs containing hundreds of thousands of entities.

UI State Management（GraphTab.tsx）

Filter toggles and node budgets are managed in graph-ui/src/components/GraphTab.tsx. The following pattern handles label filtering (lines 13-20):

const toggleLabel = useCallback((label: string) => {
  setEnabledLabels((prev) => {
    const next = new Set(prev);
    next.has(label) ? next.delete(label) : next.add(label);
    return next;
  });
}, []);

Node budget preferences persist across sessions via localStorage:

function loadNodeBudget(project: string): number {
  const v = localStorage.getItem(`cbm-node-budget:${project}`);
  return v ? clampNodeBudget(parseInt(v, 10)) : GRAPH_RENDER_NODE_LIMIT;
}

Summary

• The graph visualization UI requires the UI variant build and is not included in default installations
• The architecture consists of a React frontend (graph-ui/src/) and an embedded HTTP server (src/ui/http_server.c)
• Data flows from the /api/layout endpoint through useGraphData.ts to the Three.js renderer in GraphScene.tsx
• Enable via --ui=true flag or install using --ui with the install script
• All state persists to localStorage for session continuity

Frequently Asked Questions

What port does the graph visualization UI use by default?

The UI server listens on port 9749 by default when started with --ui=true. You can override this using the --port flag.

Is the graph visualization UI included in the default installation?

No. The default binary is headless. You must install the UI variant using --ui with the install script, CBM_VARIANT=ui with package managers, or download the specific -ui release archive.

Which technologies power the 3D rendering?

The 3D visualization uses Three.js accessed via the GraphScene.tsx component, while the UI framework is React with Vite as the build tool, as configured in graph-ui/vite.config.ts.

How does the UI handle large codebases?

The system implements streaming JSON responses through the /api/layout endpoint, allowing the frontend to process graph data chunks progressively. Additionally, the node budget feature in GraphTab.tsx limits rendered entities to maintain interactive frame rates, with uncovered files represented in a "missed skeleton" view.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}