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

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 and 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): 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, the cbm_ui_config_load() function populates a cbm_ui_config_t structure:

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. 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 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, graph.js, and 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 traverses the daemon's internal codebase memory structures and serializes them into a JSON payload:

{
  "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 file loads the D3.js library and the custom 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 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:

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

Manual Configuration:

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

{
  "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, storing settings in ~/.cache/codebase-memory-mcp/config.json.
• The server layer (src/ui/server.c) serves static assets from src/ui/static/ and exposes the /api/graph endpoint implemented in src/ui/api.c.
• Client-side rendering uses D3.js (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 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 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. 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, while the interactive D3.js logic—including force-directed layout, zoom, pan, and click handlers—resides in src/ui/static/graph.js. The base HTML structure that loads these dependencies is src/ui/static/index.html.

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