Requirements for Integrating a New Agent Surface in Codebase-Memory-MCP

Integrating a new agent surface in Codebase-Memory-MCP requires seven mandatory architectural components: a detectable marker, conditional activation logic, minimal permissions, hook scripts, declarative metadata, test coverage, and documentation.

Codebase-Memory-MCP (CBM) treats every agent surface as a plug-in that connects external tools—such as editors, IDEs, or CI runners—with the MCP core. Successfully integrating a new agent surface demands adherence to a strict architectural contract that ensures automatic detection, secure sandboxing, and seamless installation. The following requirements govern how new surfaces are registered in pkg/pypi/src/codebase_memory_mcp/_client_surfaces.py and validated across the repository.

The 7 Requirements for Agent Surface Integration

1. Detectable Marker

Every surface must expose a file, binary, config entry, or environment variable that unambiguously signals the target client's presence on the host machine. This marker allows the generic install command to automatically enable the surface only when the client actually exists, preserving safety and avoiding noisy "client not found" errors. According to the client-surface matrix in README.md, CBM currently supports 43 automatic and conditional client surfaces using this detection pattern.

2. Conditional Activation Logic

Implement a detection function (conventionally named should_activate_<client>()) that checks the marker against platform constraints such as OS, architecture, or version. In pkg/pypi/src/codebase_memory_mcp/_client_surfaces.py, each surface registers a ClientSurfaceSpec instance containing this activation logic, guaranteeing that the surface activates only under the correct circumstances (e.g., Windows-only hooks or Linux-only LSP integrations).

3. Minimal Permissions

Surfaces must request only the filesystem paths, environment variables, or network ports they strictly require. The core MCP respects the CBM_ALLOWED_ROOT sandbox environment variable defined in docs/CONFIGURATION.md, and the install routine writes hook files into per-client directories under ~/.config/mcp/ to maintain a tight security posture.

4. Hook Scripts or Integration Files

Provide concrete bridge scripts—written in shell, PowerShell, or language-specific snippets—that forward editor events (file open, save, close) to the MCP server. These templates typically reside in the scripts/ folder; reference existing examples such as gen-ui-licenses.py and install-git-hooks.sh for implementation patterns. The installer copies these files into the client's configuration directory during activation.

5. Declarative Metadata

Submit a JSON or YAML entry declaring the surface's name, detection marker, activation function reference, and list of hook files. This metadata resides in pkg/pypi/src/codebase_memory_mcp/client_surfaces.json and allows the generic installer to enumerate all available surfaces without hard-coding individual implementations.

6. Test Coverage

Include at least one automated test that simulates both the presence and absence of the detectable marker, verifying that hook files are written or skipped accordingly. The test harness in tests/test_agent_clients.c demonstrates the validation pattern used by existing surfaces to prevent regression when core installation features change.

7. Documentation

Add a "client-surface" section to README.md (or a dedicated Markdown file under docs/) describing the marker, required dependencies, and any manual configuration steps. The README's support table is auto-generated from client_surfaces.json, ensuring your documentation stays synchronized with the implementation.

Implementation Walkthrough

To satisfy all seven requirements, create the following artifacts in the specified locations:

First, implement the activation logic in the central registry:

# pkg/pypi/src/codebase_memory_mcp/_client_surfaces.py

def should_activate_vim():
    # Example of a marker: presence of a .vimrc file in $HOME

    return os.path.exists(os.path.expanduser("~/.vimrc"))

# Register the new surface

client_surfaces.append(
    ClientSurfaceSpec(
        name="vim",
        marker="~/.vimrc",
        activation_func=should_activate_vim,
        hook_templates=["scripts/vim/codec.mcp.vim"],
    )
)

Next, declare the metadata for the generic installer:

{
  "name": "vim",
  "marker": "~/.vimrc",
  "hooks": [
    "scripts/vim/codec.mcp.vim"
  ]
}

Finally, add regression tests following the established C pattern:

// tests/test_agent_clients.c (new test)
TEST_CASE("vim surface activates only when .vimrc exists") {
    // Simulate absence
    unsetenv("HOME");
    REQUIRE(!should_activate_vim());

    // Simulate presence
    setenv("HOME", "/tmp/fakehome", 1);
    touch("/tmp/fakehome/.vimrc");
    REQUIRE(should_activate_vim());
}

Summary

• Detectable markers enable automatic client discovery without manual configuration.
• Conditional activation functions in _client_surfaces.py ensure platform-specific safety.
• Minimal permissions respect the CBM_ALLOWED_ROOT sandbox and limit filesystem exposure.
• Hook scripts provide the concrete integration bridge between editors and the MCP server.
• Declarative metadata in client_surfaces.json drives the generic installer and documentation generation.
• Test coverage in tests/test_agent_clients.c prevents regression in the installation flow.
• Documentation updates ensure downstream users understand installation prerequisites.

Frequently Asked Questions

What is the purpose of the detectable marker requirement?

The detectable marker requirement ensures that the generic install command can automatically verify whether the target client (such as Vim, VS Code, or a CI runner) is actually present on the host machine before attempting to install hooks. This prevents installation failures and avoids cluttering systems with integrations for software that is not installed, as documented in the client-surface matrix in README.md.

How does Codebase-Memory-MCP ensure security when integrating new agent surfaces?

Security is enforced through the minimal permissions requirement and the CBM_ALLOWED_ROOT sandbox environment variable described in docs/CONFIGURATION.md. Surface integrations may only request the specific filesystem paths, environment variables, or network ports they need, and the installer confines all hook files to per-client directories under ~/.config/mcp/ to prevent unauthorized access to sensitive system areas.

Where do I register the activation logic for a new agent surface?

Register the activation logic in pkg/pypi/src/codebase_memory_mcp/_client_surfaces.py by implementing a should_activate_<client>() function and appending a ClientSurfaceSpec instance to the client_surfaces list. This Python module serves as the central registry where the generic installer looks up detection functions before installing hook templates.

What testing pattern should I follow for new surface integrations?

Follow the pattern established in tests/test_agent_clients.c by writing a test case that simulates both the presence and absence of your detectable marker (using environment variables or temporary files) and asserts that should_activate_<client>() returns the correct boolean value. This ensures the surface correctly handles missing dependencies and avoids false activations.

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