# Main Entry Point for DeusData codebase-memory-mcp: Architecture and Execution Flow

> Discover the main entry point for DeusData codebase-memory-mcp in src/main.c. Understand its architecture and execution flow. This article details initialization and dispatch processes.

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

---

**The main entry point for DeusData codebase-memory-mcp is located in [`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c), defining `int main(int argc, char **argv)`, which initializes the custom allocator, processes command-line arguments, and dispatches execution to the MCP server, CLI tool, or UI server, while Windows builds use a thin wrapper in [`src/launcher/windows_launcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/launcher/windows_launcher.c) to forward to this common implementation.**

Understanding the **main entry point** of the `codebase-memory-mcp` repository is essential for developers integrating the Model Context Protocol (MCP) server or contributing to its core runtime. The initialization sequence follows a strict order to ensure memory safety and cross-platform compatibility before determining which operational mode to launch.

## Entry Point Architecture

The repository uses a dual-file approach to handle platform differences while maintaining a single unified implementation logic.

### Core Implementation in src/main.c

The canonical **main entry point** resides in [`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c) with the standard POSIX signature:

```c
/* src/main.c – entry point */
int main(int argc, char **argv) {
    /* 1️⃣ Initialise the custom allocator (must be first) */
    cbm_alloc_init();

    /* 2️⃣ On POSIX record the parent PID for the watchdog */
#ifndef _WIN32
    pid_t process_initial_ppid = getppid();
#endif

    /* 3️⃣ On Windows convert UTF‑8 arguments */
#ifdef _WIN32
    {
        int win_argc = 0;
        char **win_argv = cbm_win_utf8_argv(&win_argc);
        if (win_argv) {
            argc = win_argc;
            argv = win_argv;
        }
    }
#endif

    /* 4️⃣ Parse command‑line flags ( --ui, --port, --tool‑profile, etc.) */
    /* flag handling omitted for brevity */

    /* 5️⃣ Decide which mode to run:
       • MCP JSON‑RPC server (default)
       • One‑shot CLI tool ( `codebase-memory-mcp cli …` )
       • Version / help output
       • UI server launch */
    /* mode dispatch omitted for brevity */

    return EXIT_SUCCESS;
}

```

According to the source code, **`cbm_alloc_init()`** must execute as the first statement to bind the custom memory allocator before any other operations allocate resources.

### Windows Launcher Wrapper

Windows builds provide a platform-specific wrapper in [`src/launcher/windows_launcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/launcher/windows_launcher.c) that ensures proper CRT initialization:

```c
/* src/launcher/windows_launcher.c */
int main(void) {
    /* Forward to the common entry point after Windows‑specific setup */
    return codebase_memory_mcp_main();
}

```

This wrapper merely ensures the correct entry signature for the Windows CRT and immediately forwards execution to the common implementation used by POSIX builds.

## Execution Flow and Initialization Sequence

The **main entry point** executes a five-phase initialization sequence before dispatching to operational logic:

1. **Allocator Binding** – `cbm_alloc_init()` establishes the custom memory management layer, which is mandatory for all subsequent heap operations.
2. **Parent Watchdog Setup** – On POSIX systems, the process stores the initial parent PID via `getppid()` to enable automatic termination if the parent process dies.
3. **Windows UTF-8 Conversion** – When `_WIN32` is defined, the raw Unicode command-line arguments are converted to UTF-8 using `cbm_win_utf8_argv(&win_argc)`, replacing the standard `argc`/`argv` values.
4. **Flag Parsing** – The runtime processes configuration flags including `--ui`, `--port`, `--tool-profile`, and `--help`.
5. **Mode Dispatch** – Based on parsed arguments, control transfers to the JSON-RPC MCP server (default), one-shot CLI tool, version printer, or optional 3-D graph UI server.

## Operational Modes Triggered at Entry

The **main entry point** supports four distinct execution paths determined by command-line arguments:

| Goal | Command | Execution Trigger |
|------|---------|-------------------|
| Run the full MCP server (default) | `codebase-memory-mcp` | Starts a JSON‑RPC server on stdin/stdout |
| Run a single tool via CLI | `codebase-memory-mcp cli index_repository '{"repo_path":"/my/project"}'` | Executes the `index_repository` tool and exits |
| Enable the optional UI | `codebase-memory-mcp --ui=true --port=9749` | Starts the built‑in 3‑D graph UI on the given port |
| Show version or help | `codebase-memory-mcp --version` or `--help` | Prints the binary version or usage information |

## Summary

- The **main entry point** is defined in [`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c) as `int main(int argc, char **argv)`.
- **Windows builds** use a wrapper in [`src/launcher/windows_launcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/launcher/windows_launcher.c) that calls `codebase_memory_mcp_main()`.
- **Initialization order** is strict: custom allocator first, followed by platform-specific setup (PPID capture on POSIX, UTF-8 conversion on Windows), then argument parsing.
- The entry point dispatches to four operational modes: MCP server, CLI tool, UI server, or help/version output based on parsed flags.

## Frequently Asked Questions

### Where is the main entry point defined in the codebase-memory-mcp repository?

The **main entry point** is defined in [`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c) with the function signature `int main(int argc, char **argv)`. Windows-specific builds also include a wrapper entry point in [`src/launcher/windows_launcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/launcher/windows_launcher.c) that forwards to the common implementation.

### What is the first operation performed when codebase-memory-mcp starts?

The very first operation is **`cbm_alloc_init()`**, which initializes the custom memory allocator. According to the source code comments, this must execute before any other initialization to ensure all subsequent memory allocations use the project's managed heap.

### How does the Windows entry point differ from POSIX systems?

On Windows, the entry point in [`windows_launcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/windows_launcher.c) converts the native Unicode command-line arguments to UTF-8 using `cbm_win_utf8_argv()` before forwarding to the common logic, while POSIX systems immediately capture the parent PID with `getppid()` for watchdog functionality. Both platforms ultimately execute the same dispatch logic in [`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c).

### What operational modes can the main entry point dispatch to?

The entry point can dispatch to four modes: an **MCP JSON-RPC server** (default for IDE integration), a **one-shot CLI tool** for single command execution, a **3-D graph UI server** when `--ui` is specified, or **help/version** printers. The mode is determined by parsing command-line flags immediately after platform initialization completes.