# How to Contribute to the Codebase-Memory-MCP Project: A Complete Developer's Guide

> Learn how to contribute to the codebase-memory-mcp project. Follow our guide for C development, DCO sign-off, security audits, and test cases before submitting your pull request.

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

---

**Contributing to codebase-memory-mcp requires a C development environment, DCO sign-off on all commits, and passing the 8-layer security audit and ~2040 test cases before submitting a pull request.**

Codebase-memory-mcp is a pure-C static binary that builds knowledge graphs from codebases using Tree-sitter parsers and a custom Hybrid LSP layer. Whether you want to fix bugs, add new MCP tools, or extend language support, this guide covers the complete workflow from environment setup to merged pull request.

## Understanding the Project Architecture

Before contributing, familiarize yourself with the repository's layered structure. The project separates concerns across nine distinct layers, each with specific source locations:

| Layer | Purpose | Source Location |
|-------|---------|-----------------|
| **Foundation** | Low-level utilities, allocators, hash tables | `src/foundation/` |
| **Store** | SQLite-backed graph storage with WAL and FTS5 | `src/store/` |
| **Cypher** | OpenCypher parser to SQL translator | `src/cypher/` |
| **MCP Server** | JSON-RPC 2.0 service exposing 14 tools | `src/mcp/` |
| **Pipeline** | Multi-pass indexing (AST → definitions → calls → HTTP links) | `src/pipeline/` |
| **Hybrid LSP** | Language-aware type resolution for Python, TypeScript, etc. | `src/pipeline/`, `internal/cbm/` |
| **Watcher** | Git-based auto-sync functionality | `src/watcher/` |
| **UI** | Optional 3-D graph visualizer | `src/ui/` |
| **Vendored** | Tree-sitter grammars, SQLite, dependencies | `internal/cbm/`, `vendored/` |

The entry point at [`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c) initializes both the MCP server and CLI interface, routing requests to the appropriate pipeline stages.

## Setting Up Your Development Environment

### Prerequisites

You need a C compiler, `make`, and `zlib` installed. Node.js 22+ is only required if building the UI component.

**macOS:**

```bash
xcode-select --install

```

**Linux (Debian/Ubuntu):**

```bash
sudo apt install build-essential zlib1g-dev

```

### Repository Setup

Clone the repository and enable the pre-commit hooks for DCO enforcement and security checks:

```bash
git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
git config core.hooksPath scripts/hooks

```

Run [`scripts/install-git-hooks.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/install-git-hooks.sh) to install the DCO hook locally and automate sign-off requirements.

## Building the Project

### Standard Build

Compile the static binary using the provided build script:

```bash
scripts/build.sh

```

The executable outputs to `build/c/codebase-memory-mcp`.

### UI-Enabled Build

For the optional 3-D graph visualizer, add the UI flag:

```bash
scripts/build.sh --with-ui

```

This requires Node.js 22+ and bundles the WebGL-based frontend located in `src/ui/`.

## Testing and Quality Assurance

Codebase-memory-mcp maintains strict quality standards. All contributions must pass the full test suite and security audit.

### Running the Test Suite

Execute the comprehensive test harness with AddressSanitizer (ASan) and UndefinedBehaviorSanitizer (UBSan):

```bash
scripts/test.sh

```

This runs approximately 2,040 test cases covering pipeline integration ([`tests/test_pipeline.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_pipeline.c)), HTTP route linking ([`tests/test_httplink.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_httplink.c)), MCP protocol handling ([`tests/test_mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_mcp.c)), and SQLite store validation (`tests/test_store_*.c`).

### Linting and Security Checks

Run the linting pipeline before committing:

```bash
scripts/lint.sh

```

Perform the mandatory 8-layer security audit:

```bash
make -f Makefile.cbm security

```

This includes static allow-list validation, binary scanning, and UI dependency auditing. CI automatically fails if these checks don't pass.

## Making Your Contribution

### Contribution Types

Choose your contribution path based on what you want to modify:

- **Bug fixes:** Correct logic errors in `src/*` or `internal/cbm/*`
- **New MCP tools:** Add JSON-RPC 2.0 tools in `src/mcp/` (requires prior issue discussion)
- **Language support:** Extend Tree-sitter extraction in [`internal/cbm/lang_specs.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/lang_specs.c) or Hybrid LSP resolution in `src/pipeline/pass_*.c`
- **Documentation:** Update [`README.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md) or files in `docs/`
- **Tests:** Add regression tests in `tests/*.c`

When adding language support, follow the specific procedure in the "Adding or Fixing Language Support" section of [`CONTRIBUTING.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/CONTRIBUTING.md).

### Code Changes and Language Support

For new pipeline passes or MCP tools, modify the relevant subdirectories:

- **New indexer passes:** Implement in `src/pipeline/` following the AST → definitions → calls → HTTP links pattern
- **MCP tools:** Add handlers in `src/mcp/` exposing the 14-tool interface
- **Language specs:** Update [`internal/cbm/lang_specs.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/lang_specs.c) for Tree-sitter grammar integration

## Submitting Your Work

### Commit Guidelines

All commits must include a Signed-off-by line to satisfy the Developer Certificate of Origin (DCO). Commit using the `-s` flag:

```bash
git add <files>
git commit -s -m "type(scope): concise description"

```

The pre-commit hooks will enforce this if configured properly.

### Pull Request Process

1. **Open an issue first** unless submitting a pure bug fix or test addition. Obtain maintainer feedback before coding major features.
2. **Reference the issue** in your PR title using `Fixes #123`.
3. **Keep changes atomic.** Submit one logical change per PR—avoid kitchen-sink submissions.
4. **Verify CI passes.** The pipeline automatically runs build, tests, lint, DCO check, and security audits.
5. **Address reviewer feedback.** Maintainers review code quality, security implications, and architectural fit before merging.

## Example: Adding a New Test

When contributing bug fixes or features, include tests in `tests/`. Here is a template for a new feature test:

```c
// tests/test_new_feature.c
#include "test.h"

TEST(new_feature_behaves_correctly) {
    // Arrange: set up a minimal repository
    init_repo("example.c", "int main(){ return 0; }");

    // Act: run the indexer
    int rc = run_tool("index_repository", "{ \"repo_path\": \".\" }");
    ASSERT_EQ(rc, 0);

    // Assert: query the graph for the Main function node
    char *result = run_tool("search_graph",
        "{ \"label\": \"Function\", \"name_pattern\": \"^main$\" }");
    ASSERT_STR_CONTAINS(result, "\"name\":\"main\"");
}

```

Add the file to `tests/`, run [`scripts/test.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/test.sh), and CI automatically includes it in future regression testing.

## Summary

- **Clone** the repository and install C compiler dependencies (zlib required, Node.js 22+ optional for UI)
- **Build** with [`scripts/build.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/build.sh) or `scripts/build.sh --with-ui` for the visualizer
- **Test** using [`scripts/test.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/test.sh) (~2,040 cases with ASan/UBSan)
- **Validate** code with [`scripts/lint.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/lint.sh) and `make -f Makefile.cbm security`
- **Commit** with `git commit -s` for DCO sign-off
- **Submit** issues before major PRs, reference them in titles, and keep changes atomic

## Frequently Asked Questions

### What programming language is codebase-memory-mcp written in?

Codebase-memory-mcp is written in **pure C** as a static binary. It uses Tree-sitter parsers for AST extraction and implements a custom Hybrid LSP layer for type resolution across multiple languages. The optional 3-D UI component requires Node.js 22+ but the core server and indexing pipeline are entirely C-based.

### Do I need to open an issue before submitting a pull request?

Yes, for feature additions and major changes. The contribution guidelines require opening an issue first (unless it's a pure bug fix or test addition) to obtain maintainer feedback. Bug fixes can proceed directly to PR but should reference any existing issues. This prevents wasted effort on features that may conflict with the project's architectural roadmap.

### How do I enable the 3D graph visualizer during development?

Build with the `--with-ui` flag: `scripts/build.sh --with-ui`. This compiles the optional WebGL-based visualizer located in `src/ui/`. You must have Node.js 22+ installed. The UI component allows interactive exploration of the knowledge graph but is not required for the core MCP server functionality.

### What security checks are required before submitting?

All PRs must pass an **8-layer security audit** via `make -f Makefile.cbm security`, which includes static allow-list validation, binary scanning, and UI dependency auditing. Additionally, [`scripts/lint.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/lint.sh) runs `clang-tidy`, `cppcheck`, and `clang-format`. These checks run automatically in CI and block merging if they fail.