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

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

xcode-select --install

Linux (Debian/Ubuntu):

sudo apt install build-essential zlib1g-dev

Repository Setup

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

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

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:

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

scripts/test.sh

This runs approximately 2,040 test cases covering pipeline integration (tests/test_pipeline.c), HTTP route linking (tests/test_httplink.c), MCP protocol handling (tests/test_mcp.c), and SQLite store validation (tests/test_store_*.c).

Linting and Security Checks

Run the linting pipeline before committing:

scripts/lint.sh

Perform the mandatory 8-layer security audit:

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 or Hybrid LSP resolution in src/pipeline/pass_*.c
• Documentation: Update 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.

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

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:

// 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, 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 or scripts/build.sh --with-ui for the visualizer
• Test using scripts/test.sh (~2,040 cases with ASan/UBSan)
• Validate code with 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 runs clang-tidy, cppcheck, and clang-format. These checks run automatically in CI and block merging if they fail.

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