How to Enable the 3D Graph Visualization UI in codebase-memory-mcp

To enable the 3D graph visualization UI in codebase-memory-mcp, you must use a UI-enabled binary variant and start the server with the --ui flag, then access http://localhost:9749 in your browser.

The 3D graph visualization UI is an optional front-end component for the DeusData/codebase-memory-mcp repository that provides an interactive Three.js-based interface for exploring knowledge graphs. Unlike the default headless binary, this feature requires a specific UI-enabled build and explicit activation via command-line flags. The UI assets live in the graph-ui/ directory and are served by an embedded HTTP server when properly configured.

Obtaining the UI-Enabled Binary

The visualization interface is not included in the standard headless binary distribution. You must either download a pre-built UI variant or compile the project with UI support enabled.

Download a Pre-built Release

The maintainers distribute UI-enabled binaries as separate release artifacts with the -ui suffix (e.g., codebase-memory-mcp-ui-linux-amd64.tar.gz). These builds are available in the "Pre-built Binaries" section of the repository README. Download and extract the appropriate archive for your platform to obtain a binary with embedded UI assets.

Build from Source with the --with-ui Flag

To compile the UI yourself, clone the repository and execute the build script with the --with-ui flag. This process compiles the React/Three.js assets in graph-ui/ and embeds the graph-ui/dist/ directory into the final binary:

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh --with-ui

The build system, as defined in Makefile.cbm (line 716), handles the npm dependency installation (npm ci) and production build (npm run build) before embedding the assets into the C binary.

Starting the Server with UI Support

Once you have the UI-enabled binary, you must explicitly activate the embedded HTTP server using the --ui command-line flag. The server reads this flag (or corresponding configuration key) to determine whether to serve the React front-end.

Use the official installer with the --ui shortcut:

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

Or run the binary directly with explicit flags:

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

The embedded HTTP server implementation in src/ui/http_server.c initializes an Express-style server that listens on the specified port (default 9749) and serves the compiled UI assets from memory when --ui is set to true.

Exploring the 3D Interface

Once the server is running, open http://localhost:9749 in a modern web browser. The interface renders the knowledge graph as an interactive 3-D scene using React and Three.js.

The main rendering logic resides in graph-ui/src/components/GraphScene.tsx, which initializes a Three.js PerspectiveCamera, OrbitControls, and WebGL renderer to display the graph nodes and edges. For performance optimization with large datasets, the NodeCloud.tsx component implements instanced mesh handling to efficiently render thousands of nodes simultaneously.

The UI includes a settings menu (DisplaySettingsMenu.tsx) that allows real-time adjustment of contrast and brightness parameters, manipulating the Three.js scene properties directly.

Summary

• The 3D graph visualization UI requires a UI-enabled binary variant (either downloaded pre-built or compiled with --with-ui).
• Start the server with the --ui=true flag to activate the embedded HTTP server defined in src/ui/http_server.c.
• Access the interface at http://localhost:9749 (default port).
• The front-end is built with React and Three.js, with key components located in graph-ui/src/components/.
• The build process embeds graph-ui/dist/ assets into the binary, making the UI available without external dependencies at runtime.

Frequently Asked Questions

Is the 3D graph visualization UI included in the default binary?

No. The default headless binary does not contain UI assets. You must use a release artifact with the -ui suffix or build from source using scripts/build.sh --with-ui to embed the graph-ui/ assets into the binary.

What port does the visualization UI use?

By default, the HTTP server listens on port 9749. You can specify a custom port using the --port flag (e.g., codebase-memory-mcp --ui=true --port=8080).

Can I modify the UI without rebuilding the entire binary?

While the UI assets are embedded at compile time for distribution, you can run the UI in development mode separately. Navigate to graph-ui/, run npm install and npm start to launch the React development server, which will proxy API requests to the backend MCP server running independently.

Which technologies power the 3D graph visualization?

The UI is built with React for the interface layer and Three.js for 3-D rendering. The GraphScene.tsx component manages the Three.js scene graph, while NodeCloud.tsx uses instanced meshes for high-performance node rendering. The embedded server in src/ui/http_server.c serves these static assets when the --ui flag is enabled.

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