Skip to content

fix(serve): resolve an exact node id before ranking (#5343) - #5344

Open
Ayushraj06-bit wants to merge 1 commit into
Graphify-Labs:v8from
Ayushraj06-bit:fix/mcp-exact-node-id-5343
Open

Ayushraj06-bit wants to merge 1 commit into
Graphify-Labs:v8from
Ayushraj06-bit:fix/mcp-exact-node-id-5343

Conversation

@Ayushraj06-bit

@Ayushraj06-bit Ayushraj06-bit commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

What does this PR do?

Fixes #5343.

get_node and get_neighbors could not reach a node by its exact id when that id tokenizes like its own source path. With the graph from the issue, get_node({"node_id": "docs_example-skill_SKILL.md"}) returned docs_example_skill_skill, and get_neighbors on the same id showed no references edge. Querying the shared label is refused as ambiguous with "Retry with the full node id.", and retrying with the full id returned the wrong node.

Both tools (and explain, and sections.py) resolve through _resolve_single_node, which ranks _find_node_tiers matches. docs_example-skill_SKILL.md tokenizes to the same words as docs/example-skill/SKILL.md, so both nodes from that file land in the source-path tier, ahead of the exact-id check. _tier_refusal treats a file-path tier as "the file node followed by its members", so it isn't refused, and the L1 node wins on graph order.

A node id names exactly one node, so _resolve_single_node now returns the query as-is when it is a node id, before ranking. Label queries go through the same tiers as before, so the shared label above is still refused as ambiguous.

I kept the change to the shared resolver rather than reordering the tiers in _find_node_tiers: that would not help here (the other node from the same file stays in the source-path tier), and it would change ranking for query, affected and path too. #3055 makes the same exact-id-first choice for the path endpoints; this PR doesn't touch those.

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Tests or CI
  • Refactor
  • Security fix

Verification & Invariants

Invariant: a query that is exactly a node id resolves to that node, which is what the ambiguity refusals already tell callers to do. The one behavior change: an exact id now resolves even when it would also have tied with other nodes in the exact or source-path tier. Ids are unique, so that tie was never a real ambiguity.

  • Read the CONTRIBUTING.md guide.
  • Reproduced the issue and identified the invariant.
  • Made the smallest fix necessary.
  • Added a regression test.
  • Kept the PR description synchronized with the final implementation.
  • Documented any limitations / unsupported cases explicitly.

Limitation: the match is exact and case-sensitive, like node ids themselves. A lowercased or partial id still goes through the ranked tiers as before.

How was this tested?

The issue's graph, through the real MCP tools (_build_http_app + TestClient), on v8 340268a7:

before:
  get_node node_id=docs_example-skill_SKILL.md  ->  ID: docs_example_skill_skill
  get_neighbors relation_filter=references      ->  (no lines)
after:
  get_node node_id=docs_example-skill_SKILL.md  ->  ID: docs_example-skill_SKILL.md
  get_neighbors relation_filter=references      ->  --> example-skill/SKILL.md [references] [EXTRACTED]
                                                    <-- example-skill/SKILL.md [references] [EXTRACTED]
  get_node label=example-skill/SKILL.md         ->  Ambiguous: ... matches 2 nodes ... (unchanged)

New test test_resolve_single_node_takes_an_exact_node_id_before_ranking:

fix reverted: AssertionError: assert ('docs_exampl..._skill', None) == ('docs_exampl...ILL.md', None)
fix applied:  1 passed
uv run pytest tests/test_serve.py tests/test_serve_http.py tests/test_explain_cli.py \
  tests/test_explain_same_file_tie.py tests/test_path_type_member.py \
  tests/test_truncation_full_answer.py <section tests>        -> 320 passed
uv run pytest tests/
  before: 11415 passed, 16 failed, 282 skipped, 1 xfailed
  after:  11416 passed, 16 failed, 282 skipped, 1 xfailed
  (the same 16 hooks/watch/memoization tests fail on unmodified v8 on Windows)
uv run ruff check .                                            -> All checks passed!
uv run pyright graphify/serve.py tests/test_serve.py           -> same 86 errors as unmodified v8, none new

(Windows 11, Python 3.11.9.)

Graphify-specific checklist

  • I updated generated skill artifacts (uv run python -m tools.skillgen --bless) when changing their source fragments. (No fragments touched.)
  • I confirmed that AST/structural extraction remains deterministic (no ambient state dependencies like ENV variables).
  • I reviewed changes for security implications (no unsafe interpolation into shell/Python).
  • I confirmed that no API keys or local-only graph data are included.
  • (If applicable) I disclosed AI authorship in my commit messages.

get_node and get_neighbors (and explain) resolve through
_resolve_single_node, which ranks _find_node_tiers matches. An id that
tokenizes like its own source path, such as docs_example-skill_SKILL.md
for docs/example-skill/SKILL.md, lands in the source-path tier next to
that file's L1 node, and a file-path tier is taken as precedence rather
than a tie, so the L1 node won and the requested node was unreachable.
The ambiguity refusal for the shared label tells the caller to retry
with the full node id, which then returned the wrong node.

A node id names exactly one node, so return it before ranking. Label
queries are unchanged.
@github-actions

Copy link
Copy Markdown

Thanks for the pull request, @Ayushraj06-bit. A maintainer will review it soon.

Want to talk it through while it is in review? Come join us on our Discord server. For longer-form discussion there is also GitHub Discussions.

A couple of things that speed up review: make sure the test suite passes on Python 3.11 and 3.13, and that the change keeps extraction deterministic.

@github-actions github-actions Bot added the contributor Pull request from a returning community contributor label Nov 19, 2026

@graphify-labs graphify-labs Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Graphify code review View in Graphify

Review completed · 811a20a7d8f5

Tip

Merge confidence: 5/5 · Looks safe to merge · 🟠 High impact
No issues reported

The resolver now checks for an exact node ID before ranked label and source-path matches.

Full summary

The resolver now checks for an exact node ID before ranked label and source-path matches. That shared behavior affects CLI explanations, section lookup, and the get_node and get_neighbors tools.

Code graph and static checks · 971 functions depend on this change

Impact & health

Impact — 971 functions depend on the 485 functions this change touches.

Health — this change adds coupling hotspots:

  • worse: _resolve_single_node() — 26 callers, 3 callees

Formal checks — 971 functions this change can affect weren't formally checked in this review. Formal checks are informational only.

Gate & verification

✅ PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

  • verification_scope: 740 function(s) in the blast radius were not formally verified this run

Test selection

28 of 593 test file(s) selected (5%) via static blast radius.

  • tests/test_4874_jvm_resolution.py — impact
  • tests/test_affected_cli.py — impact
  • tests/test_affected_path_file_node.py — impact
  • tests/test_affected_seed_reference_forms.py — impact
  • tests/test_benchmark.py — impact
  • tests/test_benchmark_raw_graph.py — impact
  • tests/test_benchmark_real_query.py — impact
  • tests/test_confidence_score_output.py — impact
  • tests/test_edge_also_seen.py — impact
  • tests/test_explain_same_file_tie.py — impact
  • tests/test_extract.py — impact
  • tests/test_file_label_disambiguation.py — impact
  • tests/test_graph_context_cache_reload.py — impact
  • tests/test_markdown_sections.py — impact
  • tests/test_mcp_graph_view_cache.py — impact
  • tests/test_path_cli.py — impact
  • tests/test_path_confidence.py — impact
  • tests/test_path_type_member.py — impact
  • tests/test_query_induced_edges.py — impact
  • tests/test_query_mcp_direction.py — impact
  • tests/test_query_names_its_graph.py — impact
  • tests/test_query_seed_order.py — impact
  • tests/test_query_seeds.py — impact
  • tests/test_query_source_first.py — impact
  • tests/test_serve.py — impact, changed-test
  • tests/test_serve_http.py — impact
  • tests/test_terraform.py — impact
  • tests/test_truncation_full_answer.py — impact

Selection is safe under the controlled-regression assumption; always-run tests + a periodic full run are the backstops. Advisory — it never changes the check verdict.

Every flagged function

  • _resolve_single_node() in graphify/serve.py:2276 · 26 callers, 3 callees: 26 callers depend on it (afferent coupling)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

contributor Pull request from a returning community contributor

Projects

None yet

Development

Successfully merging this pull request may close these issues.

MCP get_neighbors can resolve an exact node ID to a different file node

1 participant