What Is the Purpose of the src Directory in DeusData/codebase-memory-mcp

The src directory contains the complete C implementation of the code-intelligence engine, housing all functional modules—from the JSON-RPC MCP server and multi-pass indexing pipeline to the graph storage and optional UI—that compile into a single static binary.

The src directory serves as the core implementation layer of the codebase-memory-mcp project, a repository that provides 14 Model Context Protocol (MCP) tools for code analysis. According to the DeusData/codebase-memory-mcp source code, this directory mirrors the logical architecture described in the README, containing every module required to build the zero-dependency binary. By centralizing all implementation code under src/, the project enforces a strict separation between the engine's source code and ancillary resources such as documentation, build scripts, and UI assets stored elsewhere.

Core Architecture of the src Directory

The src directory implements a layered architecture that spans from low-level platform abstractions to high-level MCP tool handlers. Unlike projects that split logic across multiple top-level folders, codebase-memory-mcp consolidates its entire code-intelligence engine within this single directory, enabling the build system (scripts/build.sh) to compile every source file into one self-contained executable.

Entry Point and JSON-RPC Dispatcher

The binary's lifecycle begins in src/main.c, which parses command-line arguments and initializes the JSON-RPC dispatcher. This file handles the startup sequence for both the MCP server mode and CLI operations, routing incoming tool calls to the appropriate handlers implemented throughout the src/ tree.

MCP Server Implementation

While the project documentation references an src/mcp/ path conceptually, the actual MCP server logic is compiled from source files distributed within src/ that implement the 14 MCP tools. These include index_repository for crawling codebases, search_graph for querying the knowledge graph, and trace_execution for runtime validation. The server handles client communication and tool dispatch without requiring external runtime dependencies.

Multi-Pass Indexing Pipeline

The src/pipeline/pipeline.c file orchestrates the core indexing workflow that transforms raw source code into a queryable graph. This component runs a series of sequential passes: syntactic parsing, definition extraction, call-graph construction, HTTP link resolution, and test configuration analysis. The pipeline exposes a public API via src/pipeline/pipeline.h, which the MCP server uses to trigger repository indexing on demand.

Graph Storage and Cypher Engine

Graph persistence is managed through modules under src/store/*, which handle the SQLite database interactions for the knowledge graph. Read-only Cypher-like queries are parsed and executed by the engine implemented in src/cypher/*, allowing agents to traverse relationships between code entities without modifying the underlying storage.

File Discovery and Change Watching

The src/watcher/watcher.c module implements the background file system monitor. It reads .gitignore and .cbmignore patterns to exclude irrelevant files, then detects changes to keep the index synchronized with the repository. This watcher integrates with src/git/git_context.c for change-detection and diff-based impact analysis.

Runtime Trace Ingestion

Execution traces from external processes are accepted through modules in src/traces/*. This subsystem validates graph edges against actual runtime behavior and enriches the knowledge graph with dynamic call information that static analysis cannot determine.

Embedded UI Server

When launched with the --ui flag, the optional 3-D graph visualization is served by code compiled from src/ui/, specifically src/ui/server.c. This embedded web server runs alongside the MCP server, providing a visual interface to the underlying graph data without requiring a separate frontend build process.

Foundation Layer

Cross-platform abstractions reside in src/foundation/, providing utilities used by every other module. Key files include src/foundation/log.c for structured logging, src/foundation/mem.c for memory management wrappers, and src/foundation/compat_fs.c for filesystem compatibility across POSIX and Windows systems. This layer ensures the entire codebase compiles and runs consistently across platforms.

How src Enables the Zero-Dependency Binary

The src directory is organized as a self-contained C codebase that eliminates external runtime dependencies. By including all necessary components—from the SQLite-based graph storage (src/graph_buffer/graph_buffer.c and src/store/*) to the Hybrid LSP semantic type resolution in src/semantic/semantic.c—within this single directory, the build system can statically link everything into one binary. This design fulfills the project's "zero-dependency" claim, allowing the MCP server to function in isolated environments without requiring separate database installations, Node.js runtimes, or Python interpreters.

Practical Usage Examples

The following commands demonstrate how the implementation files in src/ translate into runtime functionality:

Launch the MCP server on port 9749, utilizing the entry point and dispatcher logic in src/main.c:

codebase-memory-mcp --port=9749

Trigger repository indexing through the pipeline implemented in src/pipeline/pipeline.c:

codebase-memory-mcp cli index_repository '{"repo_path":"/path/to/my/project"}'

Execute a graph query using the storage and Cypher engine compiled from src/store/* and src/cypher/*:

codebase-memory-mcp cli search_graph '{"project":"my-project","label":"Function","name_pattern":"^handle_.*"}'

Start the MCP server with the optional UI frontend served by src/ui/server.c:

codebase-memory-mcp --ui=true --port=9749

Summary

• The src directory houses the complete implementation of the codebase-memory-mcp engine, from low-level platform abstractions to high-level MCP tools.
• Key components include the entry point (src/main.c), multi-pass indexing pipeline (src/pipeline/pipeline.c), file watcher (src/watcher/watcher.c), and embedded UI server (src/ui/).
• The foundation layer (src/foundation/) provides cross-platform compatibility for threads, logging, and memory management.
• All modules compile into a single static binary with no external dependencies, enabled by the self-contained C codebase architecture.
• The directory structure strictly separates implementation code from documentation and build scripts, simplifying the build process defined in scripts/build.sh.

Frequently Asked Questions

What programming language is used in the src directory?

The src directory is implemented entirely in C, providing low-level control over memory management and system calls. This choice enables the zero-dependency static binary compilation, with platform-specific abstractions handled in files like src/foundation/compat_fs.c rather than relying on external runtime environments.

How does the src directory structure support the zero-dependency claim?

By containing all functional modules—including the SQLite graph storage, file system watchers, and JSON-RPC server—within src/, the project eliminates external runtime requirements. The build system compiles all src/ files into a single executable that embeds its own database engine and platform compatibility layers, requiring no additional installations on the target system.

Is the UI server code located in the src directory?

Yes, the optional 3-D graph visualization UI is implemented within src/ui/, specifically in files like src/ui/server.c. This code is compiled conditionally and launches when the --ui=true flag is provided, serving the frontend from the same binary that runs the MCP server rather than requiring a separate web server or Node.js process.

What is the relationship between src/pipeline/pipeline.c and the MCP tools?

The src/pipeline/pipeline.c file implements the core indexing logic that powers the index_repository MCP tool. When the MCP server receives an indexing request, it invokes the pipeline API defined in src/pipeline/pipeline.h to execute the multi-pass analysis, making this file the central engine for the repository's code-intelligence capabilities.

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