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

> Learn the seven essential requirements for integrating a new agent surface in Codebase-Memory-MCP. Discover the architectural components you need for seamless integration.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-15

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/gen-ui-licenses.py) and [`install-git-hooks.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```python

# 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:

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

```

Finally, add regression tests following the established C pattern:

```c
// 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/_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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/client_surfaces.json) drives the generic installer and documentation generation.
- **Test coverage** in [`tests/test_agent_clients.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.