docs(mcp): reconcile agent guidance + smoke to the real tool surface

The MCP surface is the deterministic structural set — the GraphRAG `ask`
tool was dropped (it remains available on the HTTP /api/chat path), and
get_callers/get_callees/get_dependencies were consolidated into a single
`get_neighbors(relation, direction)` with `get_file_neighbors` and
`find_symbol` added.

Update AGENTS.md, README.md, and the init-agent templates
(claude_mcp_section.md, cursorrules.template) to the seven registered
tools: index_repo, search_code, find_symbol, get_neighbors,
get_file_neighbors, impact_analysis, find_path. Fix scripts/mcp_smoke.py
so its expected tool set and the tools it exercises match (search_code
now takes `query`, callers come from get_neighbors direction=IN).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: DvirDukhan

AGENTS.md

@@ -157,9 +157,9 @@ cgraph info [--repo <name>]              # Repo stats + metadata
 
 ## MCP server (for agents)
 
-`cgraph-mcp` exposes the code graph over MCP stdio. Eight tools:
-`index_repo`, `search_code`, `get_callers`, `get_callees`,
-`get_dependencies`, `impact_analysis`, `find_path`, `ask`.
+`cgraph-mcp` exposes the code graph over MCP stdio. Seven tools:
+`index_repo`, `search_code`, `find_symbol`, `get_neighbors`,
+`get_file_neighbors`, `impact_analysis`, `find_path`.
 
 Drop the canonical agent guidance into any repo:
 
@@ -169,8 +169,9 @@ cgraph init-agent --force     # overwrite existing files
 ```
 
 See `api/mcp/templates/claude_mcp_section.md` for the full tool table
-and rules of thumb (start with `search_code`; prefer structural tools
-over `ask`; run `impact_analysis` before refactoring).
+and rules of thumb (start with `search_code`/`find_symbol`; use
+`get_neighbors` for who/what-calls; run `impact_analysis` before
+refactoring).
 
 Environment:
 

README.md

@@ -226,9 +226,9 @@ Then ask Claude things like *"what functions call analyze_sources?"* or *"find t
 
 For agents that speak the [Model Context Protocol](https://modelcontextprotocol.io)
 (Claude Code, Cursor, Cline, …), code-graph ships a stdio MCP server
-that exposes the knowledge graph as 8 first-class tools: `index_repo`,
-`search_code`, `get_callers`, `get_callees`, `get_dependencies`,
-`impact_analysis`, `find_path`, and `ask` (NL→Cypher via GraphRAG).
+that exposes the knowledge graph as 7 first-class tools: `index_repo`,
+`search_code`, `find_symbol`, `get_neighbors`, `get_file_neighbors`,
+`impact_analysis`, and `find_path`.
 
 Quickstart — Claude Code:
 

api/mcp/templates/claude_mcp_section.md

@@ -9,29 +9,26 @@ need to understand how symbols connect.
 | Tool | Call this when… | Example |
 |---|---|---|
 | `index_repo(path_or_url, branch?)` | **First** thing in a new repo; or after large changes outside your edits. Project name is **derived from the folder or repo URL** — read it back from the response. | `index_repo(path_or_url=".")` |
-| `search_code(prefix, project)` | You know part of a symbol name and need its id. | `search_code(prefix="processPay", project="myrepo")` |
-| `get_callers(symbol_id, project)` | "Who calls this?" — refactoring a function, tracking down a regression. | `get_callers(symbol_id=42, project="myrepo")` |
-| `get_callees(symbol_id, project)` | "What does this call?" — understanding a function before editing it. | `get_callees(symbol_id=42, project="myrepo")` |
-| `get_dependencies(symbol_id, project)` | All edges out of a symbol (CALLS + IMPORTS + DEFINES). | `get_dependencies(symbol_id=42, project="myrepo")` |
+| `search_code(query, project)` | You know part of a symbol name and need its id (hybrid prefix + ranked match). | `search_code(query="processPay", project="myrepo")` |
+| `find_symbol(name, project, file?)` | You know the exact symbol name (optionally in a given file) and want its id directly. | `find_symbol(name="processPayment", project="myrepo")` |
+| `get_neighbors(symbol_id, project, relation?, direction?)` | "Who calls this?" (`direction="IN"`), "What does this call?" (`direction="OUT"`), or other edges via `relation` (CALLS/IMPORTS/DEFINES). Replaces the old get_callers/get_callees/get_dependencies. | `get_neighbors(symbol_id=42, project="myrepo", direction="IN")` |
+| `get_file_neighbors(file, project)` | Symbols a file defines / depends on — "what's in this file and what does it touch?" | `get_file_neighbors(file="api/graph.py", project="myrepo")` |
 | `impact_analysis(symbol_id, project, direction, depth)` | **"What breaks if I change this?"** Transitive upstream callers. | `impact_analysis(symbol_id=42, project="myrepo", direction="IN", depth=3)` |
 | `find_path(source_id, dest_id, project)` | Show the call chain between two known symbols. | `find_path(source_id=10, dest_id=42, project="myrepo")` |
-| `ask(question, project)` | Open-ended natural-language question. **More expensive — use last.** | `ask(question="why does login fail when MFA is on?", project="myrepo")` |
 
 ## Rules of thumb
 
-1. **Start with `search_code`** to turn names into ids. Most tools take a `symbol_id`.
-2. **Prefer structural tools over `ask`.** `get_callers` is one cheap Cypher
-   hop; `ask` is two LLM round-trips. Use `ask` for fuzzy/conceptual
-   questions, not for "who calls X".
+1. **Start with `search_code` or `find_symbol`** to turn names into ids. Most tools take a `symbol_id`.
+2. **Use `get_neighbors` with `direction`** for who-calls / what-calls: `IN` = callers, `OUT` = callees. Pass `relation` for IMPORTS/DEFINES edges.
 3. **`impact_analysis` before refactoring.** Even when you think you know
    the answer — the transitive closure often surprises you.
 4. **`branch` is optional** but pass it when working on a feature branch
    so you query the right per-branch index.
 5. **Response shape.** Tools that return collections (`search_code`,
-   `get_callers`, `get_callees`, `get_dependencies`, `find_path`,
+   `find_symbol`, `get_neighbors`, `get_file_neighbors`, `find_path`,
    `impact_analysis`) put the array in `structuredContent.result` per
    the MCP spec. The text content is the same JSON for convenience.
-   `index_repo` and `ask` return a single object.
+   `index_repo` returns a single object.
 
 ## Environment
 

api/mcp/templates/cursorrules.template

@@ -6,22 +6,22 @@ understand how symbols connect.
 
 ## Tool selection
 
-- Symbol lookup by name: use `code-graph.search_code` (gives you the
-  numeric id every other tool needs).
-- "Who calls X?": `code-graph.get_callers`.
-- "What does X call?": `code-graph.get_callees`.
-- All outgoing edges (CALLS + IMPORTS + DEFINES): `code-graph.get_dependencies`.
+- Symbol lookup by name: use `code-graph.search_code` (hybrid prefix +
+  ranked match) or `code-graph.find_symbol` for an exact name — both give
+  you the numeric id every other tool needs.
+- "Who calls X?": `code-graph.get_neighbors` with `direction="IN"`.
+- "What does X call?": `code-graph.get_neighbors` with `direction="OUT"`.
+- Other edges (IMPORTS / DEFINES): `code-graph.get_neighbors` with the
+  matching `relation`.
+- What a file defines/touches: `code-graph.get_file_neighbors`.
 - Refactoring impact ("what breaks if I change X"):
   `code-graph.impact_analysis` with `direction="IN"`.
 - Call chain between two specific symbols: `code-graph.find_path`.
-- Natural-language question over the graph (expensive — last resort):
-  `code-graph.ask`.
 
 ## Rules
 
-- Always `search_code` first to resolve names to ids.
-- Prefer structural tools (`get_callers`, `find_path`, `impact_analysis`)
-  over `ask` for "who/what/where" questions.
+- Always `search_code`/`find_symbol` first to resolve names to ids.
+- Use `get_neighbors(direction=...)` for "who/what calls" questions.
 - Run `impact_analysis(direction="IN", depth=3)` before any non-trivial
   refactor.
 - Pass `branch` when on a feature branch.

scripts/mcp_smoke.py

@@ -2,7 +2,7 @@
 
 Spawns `cgraph-mcp` over stdio, lists tools, indexes the
 code-graph repo itself, and exercises `search_code`,
-`get_callers`, and `impact_analysis`. Prints a compact pass/fail line per
+`get_neighbors`, and `impact_analysis`. Prints a compact pass/fail line per
 tool.
 """
 
@@ -61,12 +61,11 @@ async def main() -> int:
             expected = {
                 "index_repo",
                 "search_code",
-                "get_callers",
-                "get_callees",
-                "get_dependencies",
+                "get_neighbors",
+                "get_file_neighbors",
+                "find_symbol",
                 "impact_analysis",
                 "find_path",
-                "ask",
             }
             missing = expected - set(tool_names)
             if missing:
@@ -92,10 +91,10 @@ async def main() -> int:
             branch_name = idx_payload["branch"]
             print(f"[index_repo] graph={idx_payload['graph_name']} project={project_name}")
 
-            print("[search_code] prefix='index_repo'")
+            print("[search_code] query='index_repo'")
             sr = await session.call_tool(
                 "search_code",
-                {"prefix": "index_repo", "project": project_name, "branch": branch_name},
+                {"query": "index_repo", "project": project_name, "branch": branch_name},
             )
             sr_payload = _pretty(sr)
             print(f"[search_code] -> {json.dumps(sr_payload)[:300]}")
@@ -116,20 +115,22 @@ async def main() -> int:
                 print(f"[search_code] picked id={first_id} name={hits[0].get('name')}")
 
             if first_id is not None:
-                print(f"[get_callers] id={first_id}")
+                print(f"[get_neighbors] id={first_id} direction=IN (callers)")
                 gc = await session.call_tool(
-                    "get_callers",
+                    "get_neighbors",
                     {
                         "symbol_id": first_id,
                         "project": project_name,
+                        "relation": "CALLS",
+                        "direction": "IN",
                         "branch": branch_name,
                     },
                 )
                 gc_payload = _pretty(gc)
                 # Some MCP servers return list payloads in structuredContent only.
                 gc_struct = getattr(gc, "structuredContent", None)
-                print(f"[get_callers] -> {json.dumps(gc_payload)[:300]} struct={json.dumps(gc_struct)[:200]}")
-                # Acceptable shapes: list of caller dicts, or {"callers": [...]}.
+                print(f"[get_neighbors] -> {json.dumps(gc_payload)[:300]} struct={json.dumps(gc_struct)[:200]}")
+                # Acceptable shapes: list of neighbor dicts, or {"result": [...]}.
                 callers = None
                 if isinstance(gc_payload, list):
                     callers = gc_payload
@@ -138,10 +139,10 @@ async def main() -> int:
                 elif isinstance(gc_struct, dict) and "result" in gc_struct:
                     callers = gc_struct["result"]
                 if callers is None:
-                    print("[FAIL] get_callers returned no recognizable payload")
+                    print("[FAIL] get_neighbors returned no recognizable payload")
                     fails += 1
                 else:
-                    print(f"[get_callers] {len(callers)} callers")
+                    print(f"[get_neighbors] {len(callers)} callers")
 
                 print("[impact_analysis] depth=2")
                 ia = await session.call_tool(