APIs Available for Interacting with the Graph Store in codebase-memory-mcp

The DeusData/codebase-memory-mcp server exposes fourteen JSON-RPC 2.0 MCP tools defined in src/mcp/mcp.c that enable programmatic indexing, Cypher querying, code path tracing, and project management against its SQLite-backed graph store.

The DeusData/codebase-memory-mcp repository implements a Model Context Protocol (MCP) server that maintains a persistent knowledge graph of codebases. All APIs available for interacting with the graph store are exposed as typed JSON-RPC methods registered in the static TOOLS[] array and advertised via the tools/list capability. These tools provide the complete public surface for agents to build, query, and analyze the indexed graph data stored in per-project SQLite databases.

MCP Tool Architecture

The server defines its entire API surface in the TOOLS[] array inside src/mcp/mcp.c. Each entry specifies a method name, input JSON schema, and description. The function mcp_add_tool_def (lines 28-30) attaches a generic output schema ({"type":"object","additionalProperties":true}) to every tool definition. Clients discover available methods through the cbm_mcp_tools_list and cbm_mcp_tools_list_page handlers, which serialize the TOOLS[] array into the MCP protocol's tools/list response.

Indexing and Data Ingestion APIs

index_repository

index_repository builds or updates a knowledge graph from a local repository path. It accepts repo_path (required) and optional parameters mode (full, moderate, fast, or cross-repo), target_projects, name, and persistence. This tool is defined at src/mcp/mcp.c#L14-L38.

ingest_traces

ingest_traces imports runtime trace data to enrich the graph with observed call frequencies. It requires project and an array of traces objects containing caller, callee, and count fields. Implementation resides at src/mcp/mcp.c#L195-L201.

Query and Search APIs

search_graph

search_graph executes structured graph searches by label, name regex, BM25 full-text, or semantic keyword vector. Required input is project; optional filters include query, label, name_pattern, file_pattern, and pagination controls (limit/offset). See src/mcp/mcp.c#L39-L74.

query_graph

query_graph runs openCypher-compatible read-only queries against the graph. It requires project and query (Cypher string), with an optional max_rows parameter (defaulting to 100,000). The implementation is at src/mcp/mcp.c#L75-L98.

search_code

search_code provides grep-like text search over indexed files, enriched with graph context. Required parameters are project and pattern; optional filters include file_pattern, path_filter, mode, and limit. Defined at src/mcp/mcp.c#L150-L167.

Navigation and Retrieval APIs

trace_path

trace_path performs BFS traversal of call or data-flow edges, including cross-service HTTP and async routes. It requires project and function_name, with optional direction, depth, and mode parameters. Source: src/mcp/mcp.c#L99-L118.

get_code_snippet

get_code_snippet retrieves source code for a fully qualified symbol. Inputs are project (required), qualified_name (required), and optional include_neighbors. Located at src/mcp/mcp.c#L119-L124.

get_graph_schema

get_graph_schema returns node labels, edge types, and property definitions for a project. It requires only project. Implementation: src/mcp/mcp.c#L125-L132.

get_architecture

get_architecture summarizes high-level project structure including packages, services, and clusters. It requires project and accepts optional path and aspects filters. See src/mcp/mcp.c#L133-L149.

Project Management APIs

list_projects

list_projects returns names of all projects with stored .db files in the MCP cache directory. It accepts no parameters. Defined at src/mcp/mcp.c#L168-L170.

delete_project

delete_project permanently removes a project's SQLite store and cached data. Requires project. Source: src/mcp/mcp.c#L171-L174.

index_status

index_status queries the current indexing state (queued, running, or completed) for a project. Requires project. See src/mcp/mcp.c#L175-L177.

Analysis and Documentation APIs

detect_changes

detect_changes analyzes Git diffs to identify impacted symbols with risk classification. Requires project; optional parameters include scope, depth, base_branch, and since. Located at src/mcp/mcp.c#L178-L186.

manage_adr

manage_adr creates, reads, or updates Architecture Decision Records. Requires project and mode (enum), with optional content and sections. Implementation: src/mcp/mcp.c#L187-L194.

Usage Examples

The following TypeScript demonstrates invoking these APIs via an MCP client:

import { McpClient } from 'codebase-memory-mcp';

// List available projects
const projList = await client.call('list_projects', {});
console.log('Indexed projects:', projList.results);

// Get the graph schema for a project
const schema = await client.call('get_graph_schema', { project: 'myproj' });
console.log('Node labels:', schema.labels);
console.log('Edge types:', schema.edgeTypes);

// Search for all functions matching a regex
const functions = await client.call('search_graph', {
  project: 'myproj',
  label: 'Function',
  name_pattern: '^handle.*',
  limit: 50,
});
functions.results.forEach(fn => console.log(fn.qualified_name));

// Run a Cypher query to find hot paths
const cypher = `
MATCH (f:Function)-[:CALLS]->(g)
WHERE f.transitive_loop_depth >= 3
RETURN f.qualified_name, g.qualified_name
ORDER BY f.transitive_loop_depth DESC
LIMIT 20`;
const hot = await client.call('query_graph', { project: 'myproj', query: cypher });
hot.results.forEach(row => console.log(row));

// Retrieve source code for a specific symbol
const snippet = await client.call('get_code_snippet', {
  project: 'myproj',
  qualified_name: 'myproj.utils.parse_input',
});
console.log(snippet.code);

Summary

• Fourteen JSON-RPC tools defined in src/mcp/mcp.c provide the complete API surface for graph store interaction.
• Index management (index_repository, index_status, delete_project) controls the SQLite-backed persistence layer.
• Query capabilities include structured search (search_graph), openCypher (query_graph), and text search (search_code).
• Navigation tools (trace_path, get_code_snippet, get_architecture) enable code exploration and dependency analysis.
• All tools share a common input schema validation and generic object output format defined by mcp_add_tool_def.

Frequently Asked Questions

What protocol do these graph store APIs use?

The APIs use JSON-RPC 2.0 via the Model Context Protocol (MCP). All tools are registered in the TOOLS[] array within src/mcp/mcp.c and exposed through standard MCP methods like tools/list and tools/call.

How do I list available projects in the graph store?

Invoke the list_projects tool, which accepts no parameters and returns all project names that have a stored .db file in the MCP cache directory (~/.cache/codebase-memory-mcp/). This is implemented at lines 168-170 of src/mcp/mcp.c.

Can I execute custom Cypher queries against the graph?

Yes. The query_graph tool accepts an openCypher-compatible read-only query string via the query parameter and returns up to 100,000 rows by default (configurable via max_rows). This is the direct interface to the underlying SQLite graph store.

Where is the graph data physically stored?

The graph data is stored in SQLite databases (.db files) located in the MCP cache directory, typically ~/.cache/codebase-memory-mcp/. Each project has its own database file managed by the storage layer defined in src/store/store.c and src/store/store.h.

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