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

> Discover the fourteen JSON-RPC 2.0 MCP tools in codebase-memory-mcp for programmatic graph store interaction. Query, index, trace, and manage your codebase efficiently.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: api-reference
- Published: 2026-07-05

---

**The DeusData/codebase-memory-mcp server exposes fourteen JSON-RPC 2.0 MCP tools defined in [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c#L187-L194).

## Usage Examples

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

```typescript
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.c) and [`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h).