feat(mcp): auto-traversal hint, wrong_dialect arm, JS-runtime wrapper note

[amitdeshmukh]

Summary

Three round-2 wins teaching GraphJin's DSL through structured contracts instead of per-consumer prompt prose.

find_path — auto-traversal hint (commit 6565d0d)

• get_query_syntax.patterns.metric_by_dimension gains an auto_traversal_note that teaches the collapsed shape ({ <dimension> { <fact> { sum(...) } } }) and tells agents to call find_path first to confirm a single FK path exists.
• find_path emits collapsed_example_query, collapsed_example_query_compiles, an optional repair warning, and a collapsed_note whenever the path has intermediates. Both the full and collapsed examples run through validateExampleQuery, so the response proves auto-traversal compiles on this schema instead of just claiming it.

fix_query_error — wrong_dialect arm (commit 6ef6f7e)

• New named arm catches Hasura/PostgREST aggregate leaks: the aggregation: argument and the <table>_aggregate field suffix.
• Repair shows GraphJin's leaf-field aggregate shape (sum_<col> / sum(expr: { mul: [...] })) with placeholder column names so it stays generic across schemas.
• Closes a kind: "generic" re-discovery loop that hit every model in our test except Pro.

get_js_runtime_api — MCP wrapper one-liner (commit 6ef6f7e)

• One Notes entry distinguishes in-runtime results (gj.tools.* returns decoded objects) from direct MCP-caller results (result.structuredContent or JSON.parse(result.content[0].text)).
• Single sentence at the wrapper layer beats per-tool noise on every tool description.

Skipped from the same feedback round

• Per-table suggested_aggregates[] (mul: [unitprice, orderqty] etc.) — pattern-matches column names to guess business metrics; collides with the framework-generic rule and produces nonsense on non-ecommerce schemas.
• Pre-substituting columns into aggregations.usage — agent failures here are training-data priors winning at the substitution step, not missing data.
• Per-tool MCP wrapper hints — protocol-mandated wrapper, fixed at the workflow layer instead.

CLI (graphjin cli schema path, graphjin cli fix-query-error) inherits the new fields automatically since they're thin runToolCmd wrappers; MCP/CLI parity tests stay green.

Test plan

• go test ./serv/... — full suite green
• go test ./cmd/... -run TestMCPCLI — parity tests green
• TestHandleFindPath_CollapsedExample — 2-hop chain (category → product → orderitem) yields a compiling collapsed query that names only the endpoints
• TestHandleFindPath_DirectRelationship — single-hop paths omit the collapsed fields
• TestCanonicalQueryPatterns — extended to assert metric_by_dimension.AutoTraversalNote mentions auto-traversal and find_path
• TestBuildFixQueryErrorRepair_Arms / wrong_dialect_argument — unknown argument 'aggregation' routes to wrong_dialect with sum(expr:) repair
• TestBuildFixQueryErrorRepair_Arms / wrong_dialect_aggregate_suffix — orders_aggregate { aggregate { count } } source + table not found error routes to wrong_dialect with orders extracted

🤖 Generated with Claude Code