How the 14 MCP Tools in codebase-memory-mcp Work: Functions and Parameters Explained

The codebase-memory-mcp server exposes 14 deterministic JSON-RPC tools defined in src/mcp/mcp.c that query an in-memory SQLite knowledge graph, each accepting specific JSON parameters for structural search, semantic retrieval, and architecture analysis.

The DeusData/codebase-memory-mcp repository implements a Model Context Protocol (MCP) server that maintains a code knowledge graph in SQLite. These MCP tools function as pure functions: they receive JSON payloads, execute deterministic queries against the graph, and return results wrapped in MCP envelopes. Understanding the specific parameters each tool accepts is essential for AI coding agents to effectively navigate and analyze codebases.

MCP Tool Architecture and JSON-RPC Envelope

All 14 tools are registered in the tool table within [src/mcp/mcp.c], which maps tool names to their handler functions. The server communicates via JSON-RPC 2.0, wrapping every response in an MCP envelope structure handled by the mcp_format_tool_result function.

Clients send requests with this structure:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "search_graph",
  "params": {
    "name_pattern": "^handle.*"
  }
}

The server returns results wrapped in a content array:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{"type": "text", "text": "{\"nodes\":[...]}"}]
  }
}

Concrete tool implementations reside in [src/mcp/tools.c] (or similarly named companion files), while the CLI wrapper codebase-memory-mcp cli provides direct command-line access to each tool.

The 14 MCP Tools and Their Parameters

The tools are categorized by function: graph querying, path tracing, code analysis, system overview, and ADR management. Each tool accepts a JSON object where ⚙️ denotes required and 🔧 denotes optional parameters.

Graph Search and Query Tools

These tools retrieve nodes and relationships using structural patterns, vector similarity, or Cypher queries.

• search_graph: Performs structural regex searches across the graph. Requires name_pattern (regex string). Optionally accepts label (e.g., Function), min_degree (int), max_degree (int), and file (path glob).

• semantic_query: Executes vector-based similarity search using Nomic's nomic-embed-code embeddings. Requires query (plain-text string). Optionally accepts top_k (int, defaults to 10).

• query_graph: Runs Cypher-style queries against the SQLite graph view. Requires cypher (Cypher query string). Optionally accepts params (object of named parameters for query interpolation).

Call Path and Dependency Analysis

These tools trace relationships and detect changes across the codebase.

• trace_path (alias trace_call_path): Finds shortest call-graph paths between two symbols. Requires source and target (full symbol names). Optionally accepts max_hops (int) to limit traversal depth.

• resolve_imports: Maps import-style references to target nodes. Requires import_path (string, e.g., github.com/example/pkg).

• detect_changes: Maps uncommitted Git changes to affected graph symbols with impact classification (high/medium/low). Requires git_root (path to repository root). Optionally accepts include_untracked (boolean).

Code Retrieval and Quality Analysis

These tools extract source code and identify quality issues.

• get_code_snippet: Retrieves raw source text for a specific node. Requires either node_id (int) or symbol (fully-qualified string).

• dead_code: Identifies functions or symbols with zero inbound CALLS edges, excluding known entry points. Optionally accepts label (defaults to Function).

• cross_service_http: Links HTTP route definitions to their call-sites across services with confidence scoring. Optionally accepts service (string filter).

Architecture and System Overview

These tools provide high-level codebase metadata without requiring parameters.

• get_architecture: Returns a comprehensive snapshot including languages, packages, entry points, HTTP routes, hot spots, and clusters. Accepts an empty JSON object {}.

• list_languages: Returns the set of currently indexed programming languages. Accepts no parameters.

• graph_stats: Provides low-level statistics including node/edge counts, label distribution, and storage size. Accepts no parameters.

Architecture Decision Records (ADR) Management

These tools manage ADR nodes stored within the graph.

• manage_adr: Creates, reads, updates, or lists Architecture Decision Records. Requires action (create, read, update, or list). For read or update, provide adr_id (int). For create or update, provide title and content (strings).

• detect_adr_conflicts: Scans for duplicate or contradictory ADRs in the graph. Accepts no parameters.

Practical Usage Examples

The CLI wrapper accepts tool names and JSON payloads to demonstrate tool functionality.

Structural Search for Handler Functions

Search for functions ending in "handler" with at least one connection:

codebase-memory-mcp cli search_graph '{"name_pattern":"^.*handler$","label":"Function","min_degree":1}'

Tracing Call Paths

Find the shortest path from main to db_write with a hop limit:

codebase-memory-mcp cli trace_path '{"source":"main","target":"db_write","max_hops":10}'

Parameterized Cypher Queries

List all routes calling a specific service using named parameters:

codebase-memory-mcp cli query_graph \
  '{"cypher":"MATCH (r:Route)-[:CALLS]->(s:Service) WHERE s.name = $svc RETURN r.path","params":{"svc":"payment"}}'

Key Source Files for Implementation Details

File	Purpose
[src/mcp/mcp.c]	Central dispatcher containing the tool registry table and mcp_format_tool_result envelope handling.
[src/mcp/tools.c]	Concrete implementations of each tool's graph querying logic.
[README.md]	High-level feature overview and concise tool listing.
[docs/llms.txt]	JSON schemas and tool specifications for LLM integration.
[tests/test_mcp.c]	Unit tests demonstrating expected parameters and edge cases for each tool.

Summary

• The 14 MCP tools in codebase-memory-mcp provide deterministic, JSON-RPC interfaces to a SQLite knowledge graph.
• Tool registration and envelope formatting occur in src/mcp/mcp.c, while implementations reside in the src/mcp/ directory.
• Required parameters (⚙️) include search patterns, symbol names, and action types, while optional parameters (🔧) filter results or modify behavior.
• Vector search uses Nomic embeddings via semantic_query, while query_graph supports standard Cypher syntax.
• Zero-parameter tools like get_architecture and graph_stats provide immediate codebase intelligence without configuration.

Frequently Asked Questions

What is the difference between search_graph and semantic_query?

search_graph performs deterministic regex matching against node names and structural properties like degree counts, while semantic_query uses vector embeddings (Nomic nomic-embed-code) to find conceptually similar code based on natural language meaning rather than exact text matches.

How does the MCP envelope format work?

According to the src/mcp/mcp.c implementation, every tool response is wrapped in a standard MCP envelope containing a content array with a text object: {"content": [{"type": "text", "text": "<inner-json>"}]}. This format ensures compatibility with MCP clients and AI agents expecting standardized content blocks.

Can query_graph execute any Cypher statement?

The query_graph tool accepts Cypher-style syntax but executes against a SQLite-backed graph view rather than a native graph database. It supports parameterized queries via the params object to prevent injection, but complex Cypher features (like variable-length path patterns) may be limited by the underlying SQLite implementation.

What are Architecture Decision Records (ADRs) in this context?

ADRs are special graph nodes managed by manage_adr and detect_adr_conflicts that store architectural decisions as structured content within the knowledge graph. They allow AI agents to track why specific code patterns exist and detect when new changes contradict existing documented decisions.

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