Contributing to codebase-memory-mcp: Expected Directory Structure Guide

The codebase-memory-mcp repository organizes source code, documentation, and build artifacts into distinct top-level directories, requiring contributors to place new C code in internal/cbm/, UI components in graph-ui/src/, and documentation in docs/ while following existing naming conventions.

The codebase-memory-mcp project by DeusData follows a modular layout that separates the core C implementation, TypeScript frontend, documentation, and build configuration. Understanding this directory structure is essential for contributors who want to add new language grammars, improve the visualization UI, or extend the testing infrastructure. This guide walks through the repository layout as defined in the CONTRIBUTING.md and source tree, ensuring your changes integrate cleanly with the existing build system.

Top-Level Directory Overview

At the root of the repository, you'll find configuration files and entry points that govern the build process and project metadata:

• Makefile.cbm – Primary build entry point for the C-based "cbm" component, defining compilation targets and test runners.
• flake.nix and flake.lock – Nix flakes for reproducible development environments, ensuring consistent dependencies across machines.
• install.sh and install.ps1 – Convenience scripts for installing the binary on Unix-like systems and Windows respectively.
• glama.json – Configuration for the Glama static analysis tool.
• CONTRIBUTING.md – Detailed contributor guidelines covering fork workflows, coding standards, and testing requirements.
• docs/ – Human-readable documentation including HTML pages, configuration guides, and evaluation plans.
• server.json – Example configuration for running a server instance of the tool.

Core Implementation in internal/cbm/

The heart of the project lives in internal/cbm/, which contains the Codebase Memory MCP library implementation. This directory houses C source files and headers that handle parsing, extraction, and graph generation.

Key files in this directory include:

• cbm.c and cbm.h – Core library entry points and public API definitions.
• grammar_*.c files – Tree-sitter grammar implementations for supported programming languages.
• extract_*.c files – Extraction utilities that parse source code into graph structures.

When contributing new language support, create files following the existing naming convention (e.g., grammar_foolang.c and grammar_foolang.h for a hypothetical "FooLang") and update the Makefile.cbm to include the new compilation units.

Frontend Visualization with graph-ui/

The graph-ui/ directory contains a Vite-based TypeScript application for visualizing code-graph queries. This is an isolated frontend module that builds independently from the C core.

Key configuration files here include:

• vite.config.ts – Build configuration for the development server and production bundling.
• tsconfig.json – TypeScript compiler settings.
• src/ – React components and UI logic for the graph visualization interface.

New UI components should be added to graph-ui/src/ following the existing React/TypeScript patterns, with styles and tests co-located according to the project's frontend conventions.

Documentation and Testing Infrastructure

Documentation resides exclusively in the docs/ directory, which contains markdown guides, HTML index files, and screenshots. The CONFIGURATION.md and EVALUATION_PLAN.md files live here, alongside index.html for the GitHub Pages site.

For testing, the test-infrastructure/ directory provides Docker-based integration testing. It contains:

• docker-compose.yml – Service definitions for reproducible test environments.
• Dockerfiles for setting up isolated test runners.
• Helper scripts for executing the full test suite.

The pkg/ directory houses packaging artifacts, including the Python wrapper for the binary located in pkg/pypi/ with its own README.md and setup.cfg.

Contribution Workflow and Build Commands

To contribute effectively, use the Nix-based development environment for consistency. The repository supports a standardized workflow for building, testing, and submitting changes.

First, clone the repository and enter the development shell:

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
nix develop

Build the project and run tests using the Makefile:

make build
make test

When adding a new grammar for language support:

1. Create the source files in internal/cbm/:

touch internal/cbm/grammar_newlang.c
touch internal/cbm/grammar_newlang.h

2. Add the new files to the Makefile.cbm, following the pattern of existing grammar_*.c entries.

3. Verify compilation:

make build

Submit your changes by creating a feature branch, committing with descriptive messages, and opening a Pull Request that references any relevant issues:

git checkout -b feature/add-newlang-grammar
git add internal/cbm/grammar_newlang.c internal/cbm/grammar_newlang.h Makefile.cbm
git commit -m "Add Tree-sitter grammar for NewLang"
git push origin feature/add-newlang-grammar

Summary

• Source code belongs in internal/cbm/ for C implementations and graph-ui/src/ for TypeScript UI components.
• Documentation updates go in the docs/ directory to ensure GitHub Pages compatibility.
• Build configuration is centralized in Makefile.cbm and flake.nix, which must be updated when adding new dependencies or source files.
• Testing relies on Docker environments in test-infrastructure/ to maintain reproducible CI results.
• New contributions should follow existing file naming conventions (e.g., grammar_<language>.c) and be validated with make test before submitting PRs.

Frequently Asked Questions

Where should I place new C code when contributing to codebase-memory-mcp?

Place new C source files and headers in the internal/cbm/ directory, following the existing naming pattern such as grammar_<language>.c for language parsers or extract_<feature>.c for extraction utilities. You must also register these files in the Makefile.cbm to ensure they compile with the rest of the project.

How do I set up a development environment for codebase-memory-mcp?

Use the provided Nix flake for a reproducible development environment by running nix develop in the repository root after cloning. Alternatively, you can use the install.sh (Unix) or install.ps1 (Windows) scripts for direct binary installation, though Nix is recommended for active development to match the CI environment.

What is the purpose of the graph-ui/ directory?

The graph-ui/ directory contains a standalone Vite-based TypeScript frontend for visualizing code graphs generated by the C core. It operates independently with its own build system (configured via vite.config.ts and tsconfig.json), allowing contributors to work on UI features without compiling the C components.

How are tests organized in the codebase-memory-mcp repository?

Integration and system tests are housed in test-infrastructure/ using Docker Compose to ensure consistent, isolated test environments across different machines. While unit tests for C code may be added within this directory or a dedicated tests folder, the Docker-based setup guarantees that CI runs match local test results, preventing "works on my machine" issues.

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