mcp/tools.py: Cypher queries use non-existent REL table names (COUPLED_WITH, STEP_IN_PROCESS, MEMBER_OF)

[netztaucher]

Bug Description

mcp/tools.py uses [:COUPLED_WITH], [:STEP_IN_PROCESS], and [:MEMBER_OF] as KuzuDB REL table names in Cypher queries — but these tables do not exist. The schema uses a single REL TABLE GROUP called CodeRelation with a rel_type property.

The backend (core/storage/kuzu_backend.py) does it correctly — e.g. line 412:

"MATCH (n)-[r:CodeRelation]->(p:Process) "
"WHERE n.id IN $ids AND r.rel_type = 'step_in_process' "

But tools.py uses the incorrect pattern:

# Line 513 — fails with "Table COUPLED_WITH does not exist"
"MATCH (a:File)-[r:COUPLED_WITH]-(b:File) "

# Line 697 — fails with "Table STEP_IN_PROCESS does not exist"
"MATCH (n)-[:STEP_IN_PROCESS]->(p:Process), (n)-[:MEMBER_OF]->(c:Community) "

Affected Tools

• axon_coupling — 3 broken queries (lines 513, 844, 937)
• axon_communities — 2 broken queries (lines 697, 778)
• Also affects handle_review_risk and handle_file_context

Steps to Reproduce

1. pip install axoniq==1.0.1
2. Index a repository: axon index
3. Call the MCP tool axon_coupling or axon_communities
4. Error: Binder exception: Table COUPLED_WITH does not exist

Fix

Replace all [:COUPLED_WITH], [:STEP_IN_PROCESS], [:MEMBER_OF] in tools.py with [:CodeRelation] + WHERE r.rel_type = '...' filter — matching the pattern already used in kuzu_backend.py.

Example fix for coupling:

# Before (broken):
"MATCH (a:File)-[r:COUPLED_WITH]-(b:File) "
"WHERE a.file_path = '...' "

# After (working):
"MATCH (a:File)-[r:CodeRelation]-(b:File) "
"WHERE a.file_path = '...' AND r.rel_type = 'coupled_with' "

For the communities cross-process query (line 697), the multi-relationship MATCH must be split into sequential MATCHes since CodeRelation is a single REL TABLE GROUP:

# Before (broken):
"MATCH (n)-[:STEP_IN_PROCESS]->(p:Process), (n)-[:MEMBER_OF]->(c:Community) "
"WITH p.name AS proc, ..."

# After (working):
"MATCH (n)-[r_sip:CodeRelation]->(p:Process) "
"WHERE r_sip.rel_type = 'step_in_process' "
"WITH n, p "
"MATCH (n)-[r_mo:CodeRelation]->(c:Community) "
"WHERE r_mo.rel_type = 'member_of' "
"WITH p.name AS proc, ..."

Environment

• axoniq 1.0.1
• Python 3.12
• KuzuDB (via pip dependency)

Happy to submit a PR if helpful.

[sattva1]

Great write-up — hit the same issue independently and traced through the full codebase. Two additions:

Missing from Affected Tools: handle_explain

handle_explain (lines 750, 778) has the same bug — uses both [:MEMBER_OF] and [:STEP_IN_PROCESS] as table names:

# Line 750 — fails with "Table MEMBER_OF does not exist"
"MATCH (n)-[:MEMBER_OF]->(c:Community) WHERE n.id = '...'"

# Line 778 — same pattern, would fail with STEP_IN_PROCESS
"MATCH (n)-[:STEP_IN_PROCESS]->(p:Process) WHERE n.id = '...'"

So the full list of affected handlers is: handle_coupling, handle_communities, handle_review_risk, handle_file_context, and handle_explain.

Inconsistency within handle_file_context

Worth noting that handle_file_context actually has both patterns — the correct one at line 948:

"MATCH (n)-[r:CodeRelation]->(c:Community) WHERE r.rel_type = 'member_of'"

...and the broken one 11 lines earlier at line 937:

"MATCH (a:File)-[r:COUPLED_WITH]-(b:File)"

Looks like the community query was written (or fixed) separately from the coupling query in the same handler.