add MCP v2 hints and find/search pagination echo

[HumanBean17]

Summary

• Add mcp_hints.py with the locked v1 road-sign catalog (Appendix A in propose/HINTS-ROAD-SIGNS-PROPOSE.md), dedupe-by-rendered-string, priority cap (≤5), and no graph/I/O.
• Extend MCP v2 outputs: hints on search / find / describe / neighbors; limit / offset echo on search and find (cleared on success=false); requested_edge_types echo on neighbors for empty-result hints.
• Wire handlers in mcp_v2.py, document in README, minimal tool description= updates in server.py, register mcp_hints in pyproject.toml.

Depends on PR-HINTS-A (stored OVERRIDES, ontology 13) already on master (#143).

Plan: plans/PLAN-HINTS.md § PR-B.

Test plan

• .venv/bin/ruff check .
• .venv/bin/pip install -e . then PATH=$PWD/.venv/bin:$PATH .venv/bin/python -m pytest tests -v (496 passed, 10 skipped)
• tests/test_mcp_hints.py — all 24 PR-B named scenarios
• Sentinel: mcp_hints.py has no KuzuGraph / _rows / run_search imports

Manual evidence

After indexing, a successful describe / find response includes hints and (for find/search) echoed limit / offset, e.g.:

PATH="$PWD/.venv/bin:$PATH" .venv/bin/python -c "
from kuzu_queries import KuzuGraph
from mcp_v2 import describe_v2, find_v2
g = KuzuGraph('tests/bank-chat-system/.kuzu')
# replace with a real sym: id from your graph
out = describe_v2(id='sym:...', graph=g)
print(out.model_dump(include={'hints', 'success'}))
"

Made with Cursor