How the codebase-memory-mcp Installer Configures 43 Client Surfaces

The codebase-memory-mcp installer automatically discovers and configures 43 distinct client surfaces through a three-stage pipeline of detection, safe configuration writing, and validation, ensuring MCP hooks are established for languages and tools ranging from Python and Cargo to Docker and Git without overwriting existing user settings.

The DeusData codebase-memory-mcp repository ships with a robust CLI installer that eliminates manual setup by intelligently scanning your repository to configure 43 different client surfaces—the specific entry points where the Multi-Client Processor (MCP) interfaces with your project. According to the source code in src/cli/cli.c, the installer differentiates between automatically detected surfaces and conditional ones, writing durable context entries and agent metadata only to installer-managed safe zones while strictly preserving user configuration.

What Are the 43 Client Surfaces?

The 43 surfaces represent a comprehensive matrix of language-specific agents and environment-specific hooks. These include package managers like npm, pip, Cargo, Maven, and Gradle; programming languages such as Python, TypeScript, Go, Rust, Java, C/C++, C#, and PHP; and development tools including Git, VS Code, and Docker.

Automatic vs. Conditional Surfaces

Each surface falls into one of two categories:

• Automatic surfaces activate immediately when the installer detects characteristic repository markers. For example, the presence of package.json triggers the npm client surface, while Cargo.toml activates the Rust/Cargo surface.
• Conditional surfaces require additional platform-specific markers beyond just a configuration file. These might need both a pyproject.toml and a virtual environment directory, or a go.mod alongside a valid GOPATH entry.

The canonical list documenting all 43 surfaces resides in docs/llms.txt, which serves as the LLMs matrix mapping detection markers to internal client_surface_t table entries. This same list appears in the CLI help output (codebase-memory-mcp --help) and is validated by test assertions in tests/test_cli.c at lines 2471-2524.

The Three-Stage Installation Process

The installer operates through a strict pipeline defined in src/cli/cli.c, ensuring each surface is detected, configured, and validated before the process completes.

Stage 1: Detection in src/cli/cli.c

The detection logic scans the repository for client-specific markers using file-presence checks and directory-marker validation. The code at lines 2420-2540 implements the detection loop that populates the surface list.

/* src/cli/cli.c – part of the detection loop */
if (file_exists("package.json")) {
    add_surface(SURFACE_NPM);   // marks the npm client as "automatic"
}

The installer identifies supported surfaces by checking for well-known files like pom.xml, .git, Dockerfile, and language-specific caches. Users can override detection using explicit flags such as --enable-surface=<name> to force conditional surfaces.

Stage 2: Configuration with Ownership-Aware Helpers

Once detected, the installer writes MCP hooks, durable-context entries, and agent-metadata to JSON, TOML, or YAML configuration files. The core write logic resides in src/cli/config_yaml_edit.h (lines 45-55) and src/cli/config_toml_edit.h (lines 51-61), which expose "installer-managed mapping entry" helpers.

/* src/cli/config_yaml_edit.h – safe write helper */
bool yaml_edit_add_installer_entry(yaml_document *doc,
                                   const char *path,
                                   const char *key,
                                   const char *value)
{
    if (!installer_owns(path, key)) return false;   // guardrail
    return yaml_node_set_scalar(doc, key, value);
}

/* src/cli/cli.c – invoking the helper for npm */
yaml_edit_add_installer_entry(yaml_doc, "mcp.yaml",
                              "npm.hooks", "install,postinstall");

These helpers ensure the installer only touches files it owns, leaving any user-provided configuration untouched.

Stage 3: Validation and Reporting

After writing configurations, the installer validates that no foreign files were altered and that every configured surface is properly documented. The validation code in src/cli/cli.c checks for symlinked agent roots, foreign same-name entries, and aborts if a surface cannot be safely configured.

The process concludes by printing a concise summary listing all configured surfaces:

/* src/cli/cli.c – after all writes */
printf("Configured %d automatic/conditional client surfaces:\n", surface_count);
for (int i = 0; i < surface_count; ++i) {
    printf("  - %s\n", surface_names[i]);
}

This generates output similar to:

Configured 43 automatic/conditional client surfaces:
  - npm
  - pip
  - cargo
  - maven
  - gradle
  ...

Safety Guardrails and Ownership

The installer implements strict safety mechanisms to prevent configuration corruption. Before writing any entry, the installer_owns() function verifies that the target file is either non-existent or was previously managed by the installer. If a surface fails any guardrail—such as detecting a symlinked agent root or a foreign same-name entry—the installer aborts with a clear error message. This ownership-aware approach ensures that running the installer multiple times remains idempotent and safe, never unintentionally overwriting custom user settings.

Summary

• 43 client surfaces are automatically configured by the codebase-memory-mcp installer, covering languages, package managers, and development tools.
• Three-stage pipeline: Detection in src/cli/cli.c, configuration via config_yaml_edit.h and config_toml_edit.h, and validation with ownership checks.
• Safety-first design: The installer only modifies "installer-managed mapping entries" and aborts if it encounters foreign configuration files.
• Canonical documentation: The complete surface matrix lives in docs/llms.txt and is validated by tests in tests/test_cli.c at lines 2471-2524.
• Explicit overrides: Users can force conditional surfaces using --enable-surface=<name> flags.

Frequently Asked Questions

What exactly is a "client surface" in codebase-memory-mcp?

A client surface is a specific entry point or interface through which the MCP (Multi-Client Processor) interacts with your project. Each surface corresponds to a particular tool, language, or environment—such as npm for Node.js, pip for Python, or Git for version control—that requires specific hooks and metadata to function within the codebase-memory-mcp ecosystem.

How does the installer prevent overwriting my existing configuration?

The installer uses ownership-aware helpers defined in src/cli/config_yaml_edit.h and src/cli/config_toml_edit.h that check installer_owns() before writing any data. It only modifies files marked as "installer-managed mapping entries" and aborts the process if it detects user-created configurations or foreign same-name entries, ensuring your existing settings remain untouched.

Can I manually enable a surface that wasn't auto-detected?

Yes. While the installer automatically detects most surfaces by scanning for characteristic files like package.json or Cargo.toml, you can force a conditional surface using the command-line flag --enable-surface=<name>. This is useful for platform-specific surfaces that require additional markers beyond simple file presence.

Where is the definitive list of the 43 supported surfaces maintained?

The canonical list is maintained in docs/llms.txt within the repository root, which serves as the LLMs matrix mapping detection markers to surface configurations. This documentation is synchronized with the installer binary through test assertions in tests/test_cli.c (lines 2471-2524) and is reproduced in the CLI help output when you run codebase-memory-mcp --help.

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