# How the Codebase Memory MCP Graph Visualization UI at localhost:9749 Works

> Explore the codebase memory MCP graph visualization UI at localhost:9749. Understand how D3.js and a JSON API render interactive codebase memory models.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: internals
- Published: 2026-07-28

---

**The graph visualization UI at localhost:9749 functions as an embedded HTTP server that serves static D3.js assets and exposes a JSON API endpoint (`/api/graph`) to render the codebase memory model as an interactive, force-directed graph.**

The **Codebase-Memory-MCP** daemon includes an optional web interface for exploring the in-memory code graph. When enabled, this **graph visualization UI at localhost:9749** provides a browser-based interface showing nodes (files, symbols, definitions) and edges (imports, calls, references) derived from the project's internal data structures.

## Architecture Overview

The implementation consists of three distinct layers working in sequence:

- **Configuration Layer** ([`src/ui/config.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/config.h) and [`src/ui/config.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/config.c)): Manages persistent settings stored in `~/.cache/codebase-memory-mcp/config.json`, including the `ui_enabled` boolean and `ui_port` integer (defaulting to 9749).
- **HTTP Server Layer** ([`src/ui/server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/server.c)): Creates the TCP listener on the configured port and registers route handlers for static assets and API endpoints.
- **Front-End Renderer** (`src/ui/static/`): Delivers the HTML, CSS, and JavaScript (D3.js) that fetches graph data and renders the interactive visualization.

## Server Initialization and Configuration

### Configuration Loading

On daemon startup, the system initializes a default configuration structure before loading user preferences from disk. In [`src/ui/config.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/config.c), the `cbm_ui_config_load()` function populates a `cbm_ui_config_t` structure:

```c
cbm_ui_config_t cfg = { .ui_enabled = false, .ui_port = CBM_UI_DEFAULT_PORT };
cbm_ui_config_load(&cfg);

```

The configuration persists across restarts in JSON format at `~/.cache/codebase-memory-mcp/config.json`, allowing users to modify `ui_enabled` and `ui_port` values directly.

### Daemon Startup Sequence

If `cfg.ui_enabled` evaluates to true, the daemon invokes `cbm_ui_start(&cfg)` from [`src/ui/server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/server.c). This function initializes the HTTP server using the lightweight `cbm_http_*` function family, binding to the specified port (9749 by default) and registering route handlers before entering the event loop.

## HTTP Server and API Endpoints

### Route Registration

The server implemented in [`src/ui/server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/server.c) handles two primary route categories:

1. **Static Asset Delivery**: Requests to `/` and `/static/*` serve bundled files from the `src/ui/static/` directory, including [`index.html`](https://github.com/DeusData/codebase-memory-mcp/blob/main/index.html), [`graph.js`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph.js), and [`style.css`](https://github.com/DeusData/codebase-memory-mcp/blob/main/style.css).
2. **API Endpoints**: The `/api/graph` endpoint provides dynamic graph data serialization.

### The Graph API Endpoint

When the front-end requests **GET** `/api/graph`, the handler defined in [`src/ui/api.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/api.c) traverses the daemon's internal codebase memory structures and serializes them into a JSON payload:

```json
{
  "nodes": [{ "id": "file1.c", "type": "file" }, …],
  "edges": [{ "source": "file1.c", "target": "file2.c", "type": "import" }, …]
}

```

This endpoint transforms the internal CBM data structures into a format consumable by the D3.js visualization library, including node identifiers, types, and relationship metadata.

## Client-Side Rendering with D3.js

The front-end stack resides entirely in `src/ui/static/` and requires no external build step. The [`index.html`](https://github.com/DeusData/codebase-memory-mcp/blob/main/index.html) file loads the D3.js library and the custom [`graph.js`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph.js) script, which executes the following sequence:

1. **Data Fetch**: Issues an asynchronous request to `/api/graph` to retrieve the JSON graph representation.
2. **Simulation Setup**: Constructs D3 node and link objects, initializing a force-directed simulation with physics parameters for optimal layout.
3. **Interactive Controls**: Implements pan, zoom, and drag behaviors, allowing users to rearrange nodes and explore the graph topology.
4. **Metadata Display**: Renders hover tooltips and side-panel details when users select specific nodes, showing file paths, symbol types, and relationship contexts.

The [`style.css`](https://github.com/DeusData/codebase-memory-mcp/blob/main/style.css) file provides minimal styling for the visualization canvas, tooltips, and UI controls, ensuring the interface remains responsive across different screen sizes.

## Enabling and Configuring the UI

Users can activate the **graph visualization UI at localhost:9749** through two methods:

**Command Line Activation:**

```bash
./cbm-daemon --ui=on --port=9749

```

**Manual Configuration:**

Edit `~/.cache/codebase-memory-mcp/config.json` directly:

```json
{
  "ui_enabled": true,
  "ui_port": 9749
}

```

The daemon reads these values on startup, conditionally spawning the HTTP server only when `ui_enabled` is true. This design allows the visualization to remain dormant during headless operation or CI/CD pipelines.

## Summary

- The **graph visualization UI at localhost:9749** integrates a lightweight HTTP server directly into the Codebase-Memory-MCP daemon, activated via configuration flags.
- Configuration persistence is handled by [`src/ui/config.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/config.c), storing settings in `~/.cache/codebase-memory-mcp/config.json`.
- The server layer ([`src/ui/server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/server.c)) serves static assets from `src/ui/static/` and exposes the `/api/graph` endpoint implemented in [`src/ui/api.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/api.c).
- Client-side rendering uses D3.js ([`src/ui/static/graph.js`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/static/graph.js)) to display force-directed graphs of nodes (files, symbols) and edges (imports, references).
- No external services are required; the UI operates entirely within the daemon process using the default port 9749 or a user-specified alternative.

## Frequently Asked Questions

### How do I change the port for the graph visualization UI?

Modify the `ui_port` value in `~/.cache/codebase-memory-mcp/config.json` or pass the `--port` flag when starting the daemon (e.g., `./cbm-daemon --ui=on --port=8080`). The `cbm_ui_config_load()` function in [`src/ui/config.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/config.c) loads this value during initialization, and `cbm_ui_start()` binds the HTTP server accordingly.

### What data structure does the `/api/graph` endpoint return?

The endpoint returns a JSON object containing two arrays: `nodes` (with `id` and `type` properties representing files and symbols) and `edges` (with `source`, `target`, and `type` properties representing relationships like imports or calls). This format is generated in [`src/ui/api.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/api.c) by serializing the daemon's internal CBM data structures.

### Can I access the graph UI without enabling the full daemon?

No. The HTTP server is spawned by the daemon process itself via `cbm_ui_start()` in [`src/ui/server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/server.c). The UI is not a standalone application; it requires the daemon to be running to serve the `/api/graph` endpoint with live codebase memory data.

### Which files control the appearance and interactivity of the graph?

The visualization styling is defined in [`src/ui/static/style.css`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/static/style.css), while the interactive D3.js logic—including force-directed layout, zoom, pan, and click handlers—resides in [`src/ui/static/graph.js`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/static/graph.js). The base HTML structure that loads these dependencies is [`src/ui/static/index.html`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/static/index.html).