feat(mcp): ast_search hint + acronym expansion + call graph rollup (v0.11.4)

sdsrss · claude · sdsrss · commit 3d0cef629d67 · 2026-04-17T06:51:09.000+08:00
Integration-test pass against Claude Code surfaced three friction points
that forced a second round-trip or missed relevant nodes. All three fixed.
Additive — no schema change, no re-index.

1. ast_search generic fallback (tools.rs:1773-1826 + helpers.rs:82-102):
   zero-result queries with returns=Vec&lt;T&gt; now return {hint, suggested_query}
   pointing at the stripped inner type (Vec&lt;Relation&gt; → Relation, 7 matches).

2. FTS acronym expansion (search/acronyms.rs + queries.rs:1650-1666):
   RRF/BM25/FTS/AST/LSP/MCP/RPC/SQL/ORM/CTE/JWT/TTL/DAG/RBAC/CRUD/CORS
   expanded to full-form terms alongside original. Benchmark on
   "RRF fusion BM25": weighted_rrf_fusion rank 3 (previously absent top-5).

3. semantic_search acronym-heavy FTS bias (tools.rs:87-101):
   queries entirely of short UC tokens (≤3 tokens, ≤5 chars, [A-Z0-9])
   run with fts_weight=2.0, vec_weight=0.8 to let FTS5 token-exact match
   dominate where embeddings struggle.

4. get_call_graph rollup (tools.rs:426-519): dense graphs group by
   (file, direction), emit {count, names[], node_ids[], min/max_depth}
   sorted by count desc. Contract Δ: mode "compressed_call_graph" →
   "rollup_call_graph". Measured on ensure_indexed: 86 flat → 2 caller + 5
   callee rollups. node_ids preserved for get_ast_node drill-down.

Tests: 230 lib + 44 integration + 8 new unit (strip_outer_generic ×4,
expand_acronym ×4) — all green. cargo clippy -D warnings clean.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "AST knowledge graph plugin for Claude Code — semantic search, call graph, HTTP tracing, impact analysis",
-    "version": "0.11.3"
+    "version": "0.11.4"
   },
   "plugins": [
     {
       "name": "code-graph-mcp",
       "source": "./claude-plugin",
       "description": "AST knowledge graph for intelligent code navigation — auto-indexes your codebase and provides semantic search, call graph traversal, HTTP route tracing, and impact analysis via MCP tools",
-      "version": "0.11.3",
+      "version": "0.11.4",
       "author": {
         "name": "sdsrs"
       },
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,63 @@
 # Changelog
 
+## v0.11.4 — Integration-friction fixes: ast_search hint + acronym expansion + call graph rollup
+
+Integration-test pass against Claude Code found three specific friction points
+where tool responses forced a second round-trip or missed relevant nodes.
+All three fixed. Additive — no schema change, no re-index.
+
+### Fixes
+
+1. **`ast_search` generic-fallback hint.** When `returns="Vec<Relation>"` yields
+   zero hits because the codebase uses `Vec<ParsedRelation>`, the response now
+   carries `hint` + `suggested_query` instead of a bare `count: 0`. Example:
+   `{ "count": 0, "hint": "No match for returns='Vec<Relation>'. Substring
+   'Relation' has 7 matches — try that.", "suggested_query": {"returns":
+   "Relation", "type": "fn"} }`. Strip rule: innermost `<…>` wins; multi-param
+   types take the last comma-separated param. See
+   `src/mcp/server/helpers.rs::strip_outer_generic`.
+
+2. **Acronym query expansion.** `fts5_search` preprocessing now expands
+   common CS/IR/DB acronyms into full-form terms alongside the original:
+   `RRF` → `RRF` + `reciprocal` + `rank` + `fusion`; same for `BM25`, `FTS`,
+   `AST`, `LSP`, `MCP`, `RPC`, `SQL`, `ORM`, `CTE`, `JWT`, `TTL`, `DAG`,
+   `RBAC`, `CRUD`, `CORS`. Benchmark before/after on query `"RRF fusion BM25"`:
+   `weighted_rrf_fusion` now appears at rank 3 (previously absent from top-5).
+   New static dict in `src/search/acronyms.rs`; expansions deduped via the
+   existing BTreeSet pass.
+
+3. **`semantic_code_search` acronym-heavy FTS bias.** Queries that are entirely
+   short uppercase tokens (≤3 tokens, each ≤5 chars, all `[A-Z0-9]`) now run
+   with `fts_weight=2.0, vec_weight=0.8` instead of the default `1.0/1.2`.
+   Rationale: embeddings handle letter-exact acronyms poorly while FTS5's
+   token-exact match is reliable; shift the weight toward the precise channel.
+
+4. **`get_call_graph` file-level rollup replaces `compressed_call_graph`.**
+   When the flat node list exceeds `COMPRESSION_TOKEN_THRESHOLD` (previously
+   this mode dumped the raw list anyway), group by `(file_path, direction)`
+   and emit `{file, count, names[], node_ids[], min_depth, max_depth}` sorted
+   by count desc. New mode string `"rollup_call_graph"`. Measured on
+   `ensure_indexed` (86 nodes): previously 86 flat entries → now 2 caller
+   rollups + 5 callee rollups, preserving `node_ids` for `get_ast_node`
+   drill-down. Contract Δ: consumers matching on
+   `mode == "compressed_call_graph"` must update to `"rollup_call_graph"`.
+
+### Tests
+
+- `strip_outer_generic` unit tests (4/4) cover `Vec<T>`, nested generics,
+  multi-param (`Result<T, E>`), and no-bracket cases.
+- `acronyms::expand_acronym` unit tests (4/4) cover case-insensitivity,
+  unknown tokens, `BM25` numeric acronym, and an FTS-length-filter guardrail.
+- 230 lib tests + 44 integration tests all green.
+
+### Internal
+
+New module `src/search/acronyms.rs`. `strip_outer_generic` in
+`src/mcp/server/helpers.rs`. All other edits localized to `tool_ast_search`,
+`tool_semantic_search`, and `format_call_graph_response` in
+`src/mcp/server/tools.rs`, plus one flat_map augmentation in
+`storage::queries::fts5_search_impl`.
+
 ## v0.11.3 — Doc: "hidden but callable" clarified (Claude Code vs. raw MCP)
 
 User-facing: no behavior change; corrects a misleading claim in the adopted
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "code-graph-mcp"
-version = "0.11.3"
+version = "0.11.4"
 edition = "2021"
 
 [features]
diff --git a/claude-plugin/.claude-plugin/plugin.json b/claude-plugin/.claude-plugin/plugin.json
@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.11.3",
+  "version": "0.11.4",
   "keywords": [
     "code-graph",
     "ast",
diff --git a/npm/darwin-arm64/package.json b/npm/darwin-arm64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-darwin-arm64",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "code-graph-mcp binary for macOS ARM64",
   "license": "MIT",
   "repository": {
diff --git a/npm/darwin-x64/package.json b/npm/darwin-x64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-darwin-x64",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "code-graph-mcp binary for macOS x64",
   "license": "MIT",
   "repository": {
diff --git a/npm/linux-arm64/package.json b/npm/linux-arm64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-linux-arm64",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "code-graph-mcp binary for Linux ARM64",
   "license": "MIT",
   "repository": {
diff --git a/npm/linux-x64/package.json b/npm/linux-x64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-linux-x64",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "code-graph-mcp binary for Linux x64",
   "license": "MIT",
   "repository": {
diff --git a/npm/win32-x64/package.json b/npm/win32-x64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-win32-x64",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "code-graph-mcp binary for Windows x64",
   "license": "MIT",
   "repository": {
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "MCP server that indexes codebases into an AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing",
   "license": "MIT",
   "repository": {
@@ -34,10 +34,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.11.3",
-    "@sdsrs/code-graph-linux-arm64": "0.11.3",
-    "@sdsrs/code-graph-darwin-x64": "0.11.3",
-    "@sdsrs/code-graph-darwin-arm64": "0.11.3",
-    "@sdsrs/code-graph-win32-x64": "0.11.3"
+    "@sdsrs/code-graph-linux-x64": "0.11.4",
+    "@sdsrs/code-graph-linux-arm64": "0.11.4",
+    "@sdsrs/code-graph-darwin-x64": "0.11.4",
+    "@sdsrs/code-graph-darwin-arm64": "0.11.4",
+    "@sdsrs/code-graph-win32-x64": "0.11.4"
   }
 }
diff --git a/src/mcp/server/helpers.rs b/src/mcp/server/helpers.rs
@@ -79,6 +79,30 @@ pub(super) fn normalize_type_filter_mcp(input: &str) -> Vec<String> {
     result.into_iter().map(String::from).collect()
 }
 
+/// Strip one layer of generic brackets, returning the most informative inner type.
+/// Used by `tool_ast_search` to offer "did you mean?" hints when a returns-filter
+/// like `Vec<Relation>` yields zero results.
+///
+/// Examples:
+///   "Vec<Relation>"          -> Some("Relation")
+///   "Result<Vec<Relation>>"  -> Some("Relation")   (innermost <> wins via rfind)
+///   "Result<T, E>"           -> Some("E")          (last comma-separated param)
+///   "HashMap<K, V>"          -> Some("V")
+///   "&[T]"                   -> None
+///   "String"                 -> None
+pub(super) fn strip_outer_generic(s: &str) -> Option<String> {
+    let last_lt = s.rfind('<')?;
+    let after_lt = &s[last_lt + 1..];
+    let first_gt = after_lt.find('>')?;
+    let inner = after_lt[..first_gt].trim();
+    let candidate = inner.rsplit(',').next().unwrap_or(inner).trim();
+    if candidate.is_empty() || candidate == s {
+        None
+    } else {
+        Some(candidate.to_string())
+    }
+}
+
 /// Centralized compression for tool results that exceed the token threshold.
 /// Handlers that already produce custom compressed output (with a "mode" key)
 /// are left unchanged. For other results, this truncates large string values
@@ -255,4 +279,28 @@ mod tests {
         assert!(out.get("_array_truncations").is_none(),
             "_array_truncations should only appear when arrays truncated");
     }
+
+    #[test]
+    fn strip_outer_generic_simple() {
+        assert_eq!(strip_outer_generic("Vec<Relation>"), Some("Relation".into()));
+        assert_eq!(strip_outer_generic("Option<T>"), Some("T".into()));
+    }
+
+    #[test]
+    fn strip_outer_generic_nested_picks_innermost() {
+        assert_eq!(strip_outer_generic("Result<Vec<Relation>>"), Some("Relation".into()));
+    }
+
+    #[test]
+    fn strip_outer_generic_multi_param_takes_last() {
+        assert_eq!(strip_outer_generic("HashMap<K, V>"), Some("V".into()));
+        assert_eq!(strip_outer_generic("Result<T, E>"), Some("E".into()));
+    }
+
+    #[test]
+    fn strip_outer_generic_no_brackets_returns_none() {
+        assert_eq!(strip_outer_generic("String"), None);
+        assert_eq!(strip_outer_generic("&[T]"), None);
+        assert_eq!(strip_outer_generic(""), None);
+    }
 }
diff --git a/src/mcp/server/tools.rs b/src/mcp/server/tools.rs
@@ -82,9 +82,23 @@ impl McpServer {
 
         // RRF fusion (FTS + Vec when available, FTS-only otherwise)
         // k=30: sharper rank sensitivity than default 60 (top results matter more)
-        // fts=1.0, vec=1.2: slightly favor vector similarity since FTS is now stronger
-        // with name_tokens and type columns in v2 schema
-        let fused = weighted_rrf_fusion(&fts_search, &vec_search, 30, fetch_count as usize, 1.0, 1.2);
+        // Default fts=1.0, vec=1.2: slightly favor vector similarity since FTS is now stronger
+        // with name_tokens and type columns in v2 schema.
+        //
+        // Acronym-heavy override: queries that are entirely short uppercase tokens
+        // (≤3 tokens, each ≤5 chars, all [A-Z0-9]) are letter-exact identifiers —
+        // embeddings handle them poorly (training corpora rarely teach "RRF" ≈
+        // "reciprocal rank fusion"), while FTS5's token-exact match is reliable.
+        // Shift the weight toward FTS to let the precise channel dominate.
+        let is_acronym_heavy = !meaningful_tokens.is_empty()
+            && meaningful_tokens.len() <= 3
+            && meaningful_tokens.iter().all(|t| {
+                let len_ok = t.chars().count() <= 5;
+                let shape_ok = t.chars().all(|c| c.is_ascii_uppercase() || c.is_ascii_digit());
+                len_ok && shape_ok
+            });
+        let (fts_weight, vec_weight) = if is_acronym_heavy { (2.0, 0.8) } else { (1.0, 1.2) };
+        let fused = weighted_rrf_fusion(&fts_search, &vec_search, 30, fetch_count as usize, fts_weight, vec_weight);
 
         // Match confidence: penalize when search signals are weak
         let match_confidence = {
@@ -424,11 +438,87 @@ impl McpServer {
 
         let est_tokens = crate::sandbox::compressor::estimate_json_tokens(&json!(all_nodes));
         if est_tokens > COMPRESSION_TOKEN_THRESHOLD {
+            // File-level rollup: group by (file_path, direction), emit counts + a small
+            // sample of names/node_ids + depth range. Previously this path returned
+            // `mode: compressed_call_graph` with the raw flat list (which still ate
+            // tokens). The rollup collapses dense fanouts (e.g. 12 handlers in one
+            // tools.rs file → one line with count=12 + first-10 node_ids), while
+            // preserving the node_ids needed for `get_ast_node` drill-down.
+            use std::collections::BTreeMap;
+            const SAMPLE_LIMIT: usize = 10;
+
+            struct Rollup {
+                names: Vec<String>,
+                node_ids: Vec<i64>,
+                min_depth: i64,
+                max_depth: i64,
+            }
+
+            let mut groups: BTreeMap<(String, String), Rollup> = BTreeMap::new();
+            for node in &all_nodes {
+                let file = node["file_path"].as_str().unwrap_or("").to_string();
+                let dir = node["direction"].as_str().unwrap_or("").to_string();
+                let name = node["name"].as_str().unwrap_or("").to_string();
+                let node_id = node["node_id"].as_i64().unwrap_or(0);
+                let depth = node["depth"].as_i64().unwrap_or(0);
+                let entry = groups.entry((file, dir)).or_insert(Rollup {
+                    names: Vec::new(), node_ids: Vec::new(),
+                    min_depth: depth, max_depth: depth,
+                });
+                entry.names.push(name);
+                entry.node_ids.push(node_id);
+                entry.min_depth = entry.min_depth.min(depth);
+                entry.max_depth = entry.max_depth.max(depth);
+            }
+
+            let mut caller_entries: Vec<(usize, serde_json::Value)> = Vec::new();
+            let mut callee_entries: Vec<(usize, serde_json::Value)> = Vec::new();
+            let mut caller_total = 0usize;
+            let mut callee_total = 0usize;
+
+            for ((file, direction), rollup) in groups {
+                let count = rollup.names.len();
+                let truncated = count > SAMPLE_LIMIT;
+                let names: Vec<String> = rollup.names.iter().take(SAMPLE_LIMIT).cloned().collect();
+                let node_ids: Vec<i64> = rollup.node_ids.iter().take(SAMPLE_LIMIT).copied().collect();
+                let entry = json!({
+                    "file": file,
+                    "count": count,
+                    "names": names,
+                    "node_ids": node_ids,
+                    "min_depth": rollup.min_depth,
+                    "max_depth": rollup.max_depth,
+                    "sample_truncated": truncated,
+                });
+                if direction == "callers" {
+                    caller_total += count;
+                    caller_entries.push((count, entry));
+                } else {
+                    callee_total += count;
+                    callee_entries.push((count, entry));
+                }
+            }
+
+            // Sort by count desc so the densest files appear first.
+            caller_entries.sort_by(|a, b| b.0.cmp(&a.0));
+            callee_entries.sort_by(|a, b| b.0.cmp(&a.0));
+            let caller_rollups: Vec<serde_json::Value> = caller_entries.into_iter().map(|(_, v)| v).collect();
+            let callee_rollups: Vec<serde_json::Value> = callee_entries.into_iter().map(|(_, v)| v).collect();
+
             return Ok(json!({
-                "mode": "compressed_call_graph",
-                "message": "Call graph exceeded token limit. Use get_ast_node(node_id) to expand individual nodes.",
+                "mode": "rollup_call_graph",
+                "message": "Call graph is dense; returned as file-level rollup. Pick any node_id and call get_ast_node(node_id) to expand a specific symbol.",
                 "function": function_name,
-                "results": all_nodes,
+                "direction": direction,
+                "total_nodes": all_nodes.len(),
+                "callers": {
+                    "rollups": caller_rollups,
+                    "total_count": caller_total,
+                },
+                "callees": {
+                    "rollups": callee_rollups,
+                    "total_count": callee_total,
+                },
             }));
         }
 
@@ -1766,10 +1856,43 @@ impl McpServer {
             })
         }).collect();
 
-        Ok(json!({
+        let mut response = json!({
             "results": items,
             "count": items.len(),
-        }))
+        });
+
+        // Generic-fallback hint: when returns_filter has angle brackets and zero hits,
+        // retry with the inner-most type as a suggestion so the caller sees "did you mean Relation?"
+        // rather than an empty response.
+        if items.is_empty() {
+            if let Some(rf) = returns_filter {
+                if let Some(inner) = strip_outer_generic(rf) {
+                    let normalized = type_filter.map(normalize_type_filter_mcp);
+                    let type_refs: Option<Vec<&str>> = normalized.as_ref()
+                        .map(|v| v.iter().map(|s| s.as_str()).collect());
+                    let retry = queries::get_nodes_with_files_by_filters(
+                        self.db.conn(), type_refs.as_deref(),
+                        Some(&inner), params_filter, 100,
+                    )?;
+                    if !retry.is_empty() {
+                        let n = retry.len();
+                        let plural = if n == 1 { "" } else { "es" };
+                        response["hint"] = json!(format!(
+                            "No match for returns='{}'. Substring '{}' has {} match{} — try that.",
+                            rf, inner, n, plural
+                        ));
+                        let mut suggested = serde_json::Map::new();
+                        suggested.insert("returns".to_string(), json!(inner));
+                        if let Some(tf) = type_filter { suggested.insert("type".to_string(), json!(tf)); }
+                        if let Some(pf) = params_filter { suggested.insert("params".to_string(), json!(pf)); }
+                        if let Some(q) = query { suggested.insert("query".to_string(), json!(q)); }
+                        response["suggested_query"] = serde_json::Value::Object(suggested);
+                    }
+                }
+            }
+        }
+
+        Ok(response)
     }
 
     pub(super) fn tool_find_dead_code(&self, args: &serde_json::Value) -> Result<serde_json::Value> {
diff --git a/src/search/acronyms.rs b/src/search/acronyms.rs
diff --git a/src/search/mod.rs b/src/search/mod.rs
diff --git a/src/storage/queries.rs b/src/storage/queries.rs

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@sdsrs/code-graph-darwin-arm64",`
`3`		`- "version": "0.11.3",`
	`3`	`+ "version": "0.11.4",`
`4`	`4`	`"description": "code-graph-mcp binary for macOS ARM64",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@sdsrs/code-graph-darwin-x64",`
`3`		`- "version": "0.11.3",`
	`3`	`+ "version": "0.11.4",`
`4`	`4`	`"description": "code-graph-mcp binary for macOS x64",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@sdsrs/code-graph-linux-arm64",`
`3`		`- "version": "0.11.3",`
	`3`	`+ "version": "0.11.4",`
`4`	`4`	`"description": "code-graph-mcp binary for Linux ARM64",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@sdsrs/code-graph-linux-x64",`
`3`		`- "version": "0.11.3",`
	`3`	`+ "version": "0.11.4",`
`4`	`4`	`"description": "code-graph-mcp binary for Linux x64",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@sdsrs/code-graph-win32-x64",`
`3`		`- "version": "0.11.3",`
	`3`	`+ "version": "0.11.4",`
`4`	`4`	`"description": "code-graph-mcp binary for Windows x64",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": {`