Skip to content

fix(serve): better MCP tool descriptions, depth default 1, filename guard#402

Open
sdeonvacation wants to merge 1 commit intosafishamsi:v4from
sdeonvacation:feat/serve-mcp-improvements
Open

fix(serve): better MCP tool descriptions, depth default 1, filename guard#402
sdeonvacation wants to merge 1 commit intosafishamsi:v4from
sdeonvacation:feat/serve-mcp-improvements

Conversation

@sdeonvacation
Copy link
Copy Markdown

@sdeonvacation sdeonvacation commented Apr 16, 2026

What this changes

Three improvements to `graphify/serve.py` (the MCP server). All 433 tests pass, ruff clean.

1. Better tool descriptions with usage guidance

Tool descriptions now tell the LLM when to use and when not to:

  • `query_graph`: adds explicit "Do NOT use for: exact string literals, regex patterns, or property names — use grep/search tools for those instead"
  • `get_node` / `get_neighbors`: clarify they take symbol names, not filenames (e.g. `'DigestAuth'`, not `'auth.py'`)
  • `god_nodes`: adds "Best used once at session start for orientation. Not useful during targeted investigations."
  • `shortest_path`: adds "Use symbol names, not filenames."

Without this guidance, LLMs routinely pass filenames to `get_node` and get confusing "not found" errors.

2. `query_graph` depth default: 3 → 1

Depth 3 on a large code graph (400+ files) can return 500+ nodes in a single traversal, blowing the token budget and returning noise. Depth 1 returns a focused subgraph centered on the matching nodes. Users can increase if results are too sparse. Description updated accordingly.

3. Filename guard in `get_node` and `get_neighbors`

Before this change, passing `'auth.py'` to `get_node` returns `"No node matching 'auth.py' found."` — unhelpful.

After:
```
'auth.py' looks like a filename, not a symbol. Pass a class or function name instead. Symbols in that file: DigestAuth, BasicAuth, BearerAuth, NetRCAuth, Auth.
```

Two new helpers added — no new imports, no hardcoded extension lists:

  • `_is_filename(G, label)` — checks the graph itself: returns `True` if a node with that label exists whose `source_file` ends with the label. Works for any language graphify supports.
  • `_symbols_in_file(G, filename, limit=8)` — returns top-degree symbols from that file as a hint, filtered by the same `source_file.endswith` logic.

Checklist

  • All 433 existing tests pass
  • `ruff check` clean
  • No new imports or dependencies
  • Surgical changes — only `serve.py` modified (+70/-14 lines)

@sdeonvacation sdeonvacation force-pushed the feat/serve-mcp-improvements branch from 7e8a495 to 63828a9 Compare April 16, 2026 14:53
Three improvements to the MCP server (serve.py):

1. Better tool descriptions with usage guidance and anti-patterns.
   query_graph: explicit 'use for / do NOT use for' guidance.
   get_node / get_neighbors: note they take symbol names, not filenames.
   god_nodes: clarify 'orientation only, not during investigations'.

2. query_graph depth default 1 (was 3).
   Depth 3 on a large code graph can return 500+ nodes, blowing the
   token budget. Default 1 returns a focused subgraph; users can
   increase if needed. Description updated to say 'Start with 1'.

3. Filename guard in get_node and get_neighbors.
   When passed 'auth.py' instead of 'DigestAuth', both tools now return
   a helpful error and list the top symbols in that file, rather than
   silently returning 'not found'.
@sdeonvacation sdeonvacation force-pushed the feat/serve-mcp-improvements branch from 63828a9 to eace61b Compare April 16, 2026 14:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant