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

The main entry point for DeusData codebase-memory-mcp is located in 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 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 with the standard POSIX signature:

/* 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 that ensures proper CRT initialization:

/* 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 as int main(int argc, char **argv).
• Windows builds use a wrapper in 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 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 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 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.

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.

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