What Cypher Query Subset Does Codebase-Memory-MCP Support?

Codebase-Memory-MCP supports a read-only subset of the OpenCypher language that includes MATCH, WHERE, RETURN, aggregations, functions, and UNION, but excludes all write operations like CREATE, DELETE, MERGE, and SET.

Codebase-Memory-MCP ships with a built-in Cypher query engine that translates a specific Cypher query subset into SQL for its internal SQLite graph store. This implementation focuses exclusively on read-only graph traversals and analytical operations, making it ideal for querying codebases without risk of mutation.

Core Supported Clauses

The parser recognizes standard read clauses defined in the keyword table in src/cypher/cypher.c (lines 36-45). These include:

• MATCH – Pattern matching for nodes and relationships
• WHERE – Filtering conditions
• RETURN – Output projection
• WITH – Subquery result passing
• ORDER BY – Result sorting
• SKIP and LIMIT – Pagination control
• DISTINCT – Duplicate elimination

Pattern Matching and Traversal

The engine supports comprehensive graph traversal patterns. Node syntax follows (var:Label {props}), parsed by the parse_node function (lines 44-55). Relationship patterns include directional arrows (->, <-, -[]-) and variable-length hops.

Variable-length traversals use the syntax -[:TYPE*min..max]-> with a configurable maximum depth. The CYP_MAX_DEPTH constant defaults to 10 hops. Implementation details reside in parse_rel and parse_hop_range (lines 96-110).

Label alternation (:A|B|C) is supported and stored as pipe-separated strings, handled in lines 58-81.

Filtering and Predicates

The WHERE clause supports complex boolean logic through parse_condition_expr (lines 108-139). Available operators include:

• Boolean operators: AND, OR, XOR, NOT
• Comparison operators: =, <>, =~, >, <, >=, <=
• String operators: CONTAINS, STARTS WITH, ENDS WITH
• List operator: IN
• Null checks: IS NULL, IS NOT NULL
• Label tests: n:Label
• Existence checks: EXISTS { (v)-[:TYPE]->() }

Comparison operators are processed in parse_comparison_op (lines 90-119).

Aggregations and Functions

Aggregate functions are detected via is_aggregate_tok and parsed in parse_aggregate_item (lines 191-199, 271-285). Supported aggregates include:

• COUNT, SUM, AVG, MIN, MAX
• COLLECT (with optional DISTINCT)

Scalar and introspection functions available through scalar_func_canonical (lines 133-140) and parse_named_func_item (lines 181-190) include:

• labels(), type(), id(), keys(), properties()
• toInteger(), toFloat(), toBoolean()
• size(), length(), trim(), ltrim(), rtrim(), reverse()
• toLower(), toUpper(), toString()

Multi-argument functions like coalesce(), substring(), replace(), left(), and right() are handled via multiarg_func_canonical (lines 144-151) and parse_multiarg_func_item (lines 239-260).

Result Shaping and Composition

The RETURN clause supports AS aliasing, implemented in parse_return_item (lines 240-250). Result ordering uses ORDER BY … ASC/DESC.

UNION and UNION ALL combine multiple query results (parsed around line 1810 in parse_post_where), though nested UNION recursion is not supported.

CASE expressions follow the standard CASE WHEN … THEN … ELSE … END pattern, implemented in parse_case_expr (lines 224-260).

Practical Query Examples

-- Simple match with label alternation and property filter
MATCH (f:Function|Method {language: "Go"})
WHERE f.name CONTAINS "parse"
RETURN f.name AS function, f.file, f.line
ORDER BY f.line ASC
LIMIT 20

-- Variable-length path (up to 5 hops) with direction
MATCH (src:File)-[:IMPORT*1..5]->(dst:File)
WHERE src.path STARTS WITH "/src/"
RETURN src.path, dst.path

-- Aggregate + CASE
MATCH (c:Class)-[:HAS_METHOD]->(m:Method)
WHERE c.package = "github.com/DeusData"
RETURN c.name,
       COUNT(m) AS method_count,
       CASE WHEN COUNT(m) > 10 THEN "Large" ELSE "Small" END AS size
ORDER BY method_count DESC

-- UNION of two independent queries
MATCH (p:Project {name: "MCP"})
RETURN p.name, "project" AS type
UNION
MATCH (l:Language {name: "C"})
RETURN l.name, "language" AS type

Explicitly Unsupported Features

Write operations are tokenized but rejected with "unsupported Cypher feature" errors via unsupported_clause_error (lines 196-225). These include:

• Write clauses: CREATE, DELETE, MERGE, SET, REMOVE, DETACH
• Procedural: CALL, UNWIND, FOREACH
• Schema commands: DROP, CONSTRAINT
• Sub-queries and nested structures
• List indexing ([…]) and map literals

Implementation Architecture

The Cypher engine is implemented across these key files:

• src/cypher/cypher.h – Token definitions and public API
• src/cypher/cypher.c – Lexer, parser, and executor (~300+ lines) containing functions like parse_node, parse_condition_expr, and parse_aggregate_item
• src/mcp/mcp.c – CLI entry point exposing the query_graph tool (lines 370-395)
• src/cli/cli.c – Help text with Cypher examples (lines 461-521)

Summary

• Codebase-Memory-MCP implements a read-only Cypher subset for querying code graphs stored in SQLite.
• Supported features include MATCH with variable-length paths, WHERE with complex predicates, aggregations, scalar/multi-arg functions, CASE expressions, and UNION.
• All write operations (CREATE, DELETE, MERGE, SET) are explicitly blocked by the unsupported_clause_error handler.
• The parser is defined in src/cypher/cypher.c with strict validation ensuring only analytical queries execute.

Frequently Asked Questions

Does Codebase-Memory-MCP support CREATE or DELETE statements?

No. The engine explicitly rejects all write-oriented clauses including CREATE, DELETE, MERGE, SET, REMOVE, and DETACH. Attempting to use these triggers an "unsupported Cypher feature" error from the unsupported_clause_error function in src/cypher/cypher.c.

What is the maximum depth for variable-length path queries?

The default maximum depth is 10 hops, controlled by the CYP_MAX_DEPTH constant. You can specify ranges like *1..5 in relationship patterns, which are parsed by parse_hop_range in src/cypher/cypher.c (lines 96-110).

Can I use sub-queries or UNWIND in my Cypher queries?

No. Sub-queries, UNWIND, and FOREACH are not supported. The parser only handles single-statement read queries and will reject any nested query structures or list unwinding operations according to the implementation in src/cypher/cypher.c.

Which string functions are available in the supported Cypher subset?

The engine supports CONTAINS, STARTS WITH, ENDS WITH, toLower(), toUpper(), toString(), trim(), ltrim(), rtrim(), reverse(), substring(), replace(), left(), and right(). These are handled in parse_string_func_item and parse_multiarg_func_item within src/cypher/cypher.c.

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