fix(mcp): 12-tool accuracy audit fixes (v0.11.1)

sdsrss · claude · sdsrss · commit c82eafa7a6f6 · 2026-04-17T04:24:34.000+08:00
Post-audit fixes surfacing from systematic testing of all 12 MCP tools.

Critical: find_references/impact_analysis/get_call_graph fuzzy fallback now
prefer exact name before substring — eliminates false-ambiguity reports for
names that are prefixes of others (e.g. handle_tool vs handle_tools_list).

Precision improvements:
- truncate_large_strings keeps arrays homogeneous; _array_truncations
  metadata records true pre-truncation length per field.
- project_map.hot_functions SQL restricted to function/method (structs no
  longer leak in); entry_points gain `kind` to distinguish main vs http_route.
- dependency_graph filters the synthetic &lt;external&gt; bucket.
- find_similar_code reports cutoff_applied/cutoff_dropped/hint when
  max_distance shortfalls below top_k.
- impact_analysis returns risk_level=UNKNOWN for type queries with zero
  call-graph callers instead of the misleading LOW.

Tests: +2 unit (helpers truncation), +6 integration (one per fix).
Full suite 343 passed, clippy 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.0"
+    "version": "0.11.1"
   },
   "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.0",
+      "version": "0.11.1",
       "author": {
         "name": "sdsrs"
       },
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,60 @@
 # Changelog
 
+## v0.11.1 — 12-tool accuracy audit: 1 critical bugfix + 5 precision improvements
+
+Post-audit fixes for tool output correctness. All changes are additive/tightening —
+no consumer schema breakage.
+
+### Fixes
+
+1. **`find_references` — critical bugfix for exact-name resolution.**
+   `resolve_fuzzy_name` was matching substrings before exact names, so
+   `find_references("handle_tool")` falsely reported ambiguity with
+   `handle_tools_list` / `handle_tools_call`. Now exact-name matches win first;
+   same-name-in-multiple-files still produces `Ambiguous` but scoped to exact
+   matches only. Same fix benefits `impact_analysis` and `get_call_graph`
+   fuzzy-fallback paths.
+
+2. **Centralized truncation keeps arrays homogeneous.** The
+   `centralized_compress` pipeline used to splice a string sentinel
+   (`"... [N items truncated]"`) into the middle of object arrays, breaking
+   type consistency for strict JSON consumers and hiding how much was dropped.
+   Arrays now truncate silently to `first-10 + last-5` (15 homogeneous items),
+   and a new `_array_truncations: {<field>: {original, kept}}` sibling records
+   the true pre-truncation length so callers can reconcile `count`/`total`
+   siblings against what was actually returned.
+
+3. **`project_map` schema sharpened.**
+   - `hot_functions` SQL tightened to `n.type IN ('function','method')` so
+     structs/classes no longer leak into the "hot functions" bucket.
+   - `entry_points[].kind` added: `"main"` for program entry points, `"http_route"`
+     for framework-registered handlers. Lets LLMs skip `main` when scanning the
+     HTTP surface without sniffing the `route` string.
+
+4. **`dependency_graph` filters the `<external>` sentinel.** The synthetic
+   bucket for unresolved imports now no longer surfaces as a fake file dependency.
+
+5. **`find_similar_code` reports cutoff-driven shortfalls.** When
+   `max_distance` drops candidates below `top_k`, the response now carries
+   `cutoff_applied: true`, `cutoff_dropped: N`, and a `hint` suggesting the
+   user widen `max_distance`. Also echoes `top_k` and `max_distance` in every
+   response for transparency.
+
+6. **`impact_analysis` on types returns `risk_level: "UNKNOWN"`.** When the
+   target is a struct/class/enum/interface/type_alias and the call graph finds
+   zero callers, the risk level is now `UNKNOWN` instead of `LOW` — so LLMs
+   don't mistake "call graph can't see type usage" for "no one uses this".
+   The existing type_warning still explains why and points to
+   `semantic_code_search` for broader coverage.
+
+### Test coverage
+
+- +2 unit tests in `src/mcp/server/helpers.rs` (truncation homogeneity,
+  no-op when arrays < 20).
+- +6 integration tests in `tests/integration.rs` covering each fix above.
+- Full suite: lib 221 + integration 41 + cli_e2e 50 + parser 19 + plugin 6 +
+  hardening 6 = 343 passed, clippy clean.
+
 ## v0.11.0 — auto-refresh stale decision table on plugin upgrade
 
 ### Migration note
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.0"
+version = "0.11.1"
 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.0",
+  "version": "0.11.1",
   "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.0",
+  "version": "0.11.1",
   "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.0",
+  "version": "0.11.1",
   "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.0",
+  "version": "0.11.1",
   "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.0",
+  "version": "0.11.1",
   "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.0",
+  "version": "0.11.1",
   "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.0",
+  "version": "0.11.1",
   "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.0",
-    "@sdsrs/code-graph-linux-arm64": "0.11.0",
-    "@sdsrs/code-graph-darwin-x64": "0.11.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.11.0",
-    "@sdsrs/code-graph-win32-x64": "0.11.0"
+    "@sdsrs/code-graph-linux-x64": "0.11.1",
+    "@sdsrs/code-graph-linux-arm64": "0.11.1",
+    "@sdsrs/code-graph-darwin-x64": "0.11.1",
+    "@sdsrs/code-graph-darwin-arm64": "0.11.1",
+    "@sdsrs/code-graph-win32-x64": "0.11.1"
   }
 }
diff --git a/src/cli.rs b/src/cli.rs
@@ -1165,6 +1165,7 @@ pub fn cmd_map(project_root: &Path, args: &[String]) -> Result<()> {
                 "route": e.route,
                 "handler": e.handler,
                 "file": e.file,
+                "kind": e.kind,
             })).collect::<Vec<_>>(),
             "hot_functions": hot_functions.iter().map(|h| {
                 let mut obj = serde_json::json!({
diff --git a/src/mcp/server/helpers.rs b/src/mcp/server/helpers.rs
@@ -146,6 +146,11 @@ fn truncate_value_inner(value: serde_json::Value, budget: usize, depth: usize) -
                 .sum();
             let large_budget = budget.saturating_sub(small_fields_size);
 
+            // Record array truncations so consumers can reconcile `count`/`total`
+            // sibling fields against what was actually returned.
+            let mut array_truncations: serde_json::Map<String, serde_json::Value> =
+                serde_json::Map::new();
+
             let truncated: serde_json::Map<String, serde_json::Value> = map.into_iter()
                 .map(|(k, v)| {
                     let tv = match &v {
@@ -163,9 +168,15 @@ fn truncate_value_inner(value: serde_json::Value, budget: usize, depth: usize) -
                             }
                         }
                         serde_json::Value::Array(arr) if arr.len() > 20 => {
+                            let original = arr.len();
                             let mut kept: Vec<serde_json::Value> = arr[..10].to_vec();
-                            kept.push(json!(format!("... [{} items truncated]", arr.len() - 15)));
                             kept.extend_from_slice(&arr[arr.len()-5..]);
+                            // Keep array homogeneous — consumers can read
+                            // `_array_truncations[k]` for the original length.
+                            array_truncations.insert(k.clone(), json!({
+                                "original": original,
+                                "kept": kept.len(),
+                            }));
                             serde_json::Value::Array(kept)
                         }
                         serde_json::Value::Object(_) | serde_json::Value::Array(_) => {
@@ -176,11 +187,21 @@ fn truncate_value_inner(value: serde_json::Value, budget: usize, depth: usize) -
                     (k, tv)
                 })
                 .collect();
-            serde_json::Value::Object(truncated)
+
+            let mut final_map = truncated;
+            if !array_truncations.is_empty() {
+                final_map.insert(
+                    "_array_truncations".to_string(),
+                    serde_json::Value::Object(array_truncations),
+                );
+            }
+            serde_json::Value::Object(final_map)
         }
         serde_json::Value::Array(arr) if arr.len() > 20 => {
+            // Top-level array: truncate silently, keep homogeneous. The outer
+            // `truncate_large_strings` wrapper adds `_truncated` metadata only
+            // when the root is an object; top-level arrays cannot carry it.
             let mut kept: Vec<serde_json::Value> = arr[..10].to_vec();
-            kept.push(json!(format!("... [{} items truncated]", arr.len() - 15)));
             kept.extend_from_slice(&arr[arr.len()-5..]);
             serde_json::Value::Array(kept)
         }
@@ -194,3 +215,44 @@ fn truncate_value_inner(value: serde_json::Value, budget: usize, depth: usize) -
         other => other,
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn truncate_array_keeps_items_homogeneous_and_records_original_len() {
+        let items: Vec<serde_json::Value> = (0..50).map(|i| json!({
+            "id": i, "name": format!("item_{}", i),
+        })).collect();
+        let value = json!({
+            "count": 50,
+            "results": items,
+            "pad": "x".repeat(200_000),
+        });
+
+        let out = truncate_large_strings(value, 50);
+        let arr = out["results"].as_array().expect("results still an array");
+        for (i, v) in arr.iter().enumerate() {
+            assert!(v.is_object(), "results[{}] broke schema: {}", i, v);
+        }
+        let trunc = &out["_array_truncations"]["results"];
+        assert_eq!(trunc["original"], 50);
+        assert_eq!(trunc["kept"].as_u64().unwrap() as usize, arr.len());
+        assert_eq!(out["_truncated"], true);
+    }
+
+    #[test]
+    fn arrays_under_20_items_are_not_truncated() {
+        let items: Vec<serde_json::Value> = (0..10).map(|i| json!({"id": i})).collect();
+        let value = json!({
+            "results": items,
+            "pad": "y".repeat(200_000),
+        });
+        let out = truncate_large_strings(value, 50);
+        let arr = out["results"].as_array().unwrap();
+        assert_eq!(arr.len(), 10);
+        assert!(out.get("_array_truncations").is_none(),
+            "_array_truncations should only appear when arrays truncated");
+    }
+}
diff --git a/src/mcp/server/mod.rs b/src/mcp/server/mod.rs
@@ -762,11 +762,29 @@ impl McpServer {
     }
 
     /// Try fuzzy name resolution: returns the unique match, multiple suggestions, or nothing.
+    ///
+    /// Exact-name matches take precedence over substring matches. Without this,
+    /// `find_functions_by_fuzzy_name("handle_tool")` would return the exact
+    /// `handle_tool` alongside substring matches like `handle_tools_list` and
+    /// trigger false "ambiguous" reports in find_references/impact_analysis.
     fn resolve_fuzzy_name(&self, name: &str) -> Result<FuzzyResolution> {
         let candidates: Vec<_> = queries::find_functions_by_fuzzy_name(self.db.conn(), name)?
             .into_iter()
             .filter(|c| !is_test_symbol(&c.name, &c.file_path))
             .collect();
+        // Prefer exact name matches if any exist.
+        let exact: Vec<_> = candidates.iter().filter(|c| c.name == name).collect();
+        if exact.len() == 1 {
+            return Ok(FuzzyResolution::Unique(exact[0].name.clone()));
+        }
+        if exact.len() > 1 {
+            // Same name in multiple files — still ambiguous, but scope suggestions
+            // to the exact matches so callers disambiguate the real collision.
+            let suggestions = exact.iter().map(|c| json!({
+                "name": c.name, "file_path": c.file_path, "type": c.node_type,
+            })).collect();
+            return Ok(FuzzyResolution::Ambiguous(suggestions));
+        }
         if candidates.len() == 1 {
             Ok(FuzzyResolution::Unique(candidates.into_iter().next().unwrap().name))
         } else if !candidates.is_empty() {
diff --git a/src/mcp/server/tools.rs b/src/mcp/server/tools.rs
diff --git a/src/storage/queries.rs b/src/storage/queries.rs
diff --git a/tests/integration.rs b/tests/integration.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.0",`
	`3`	`+ "version": "0.11.1",`
`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.0",`
	`3`	`+ "version": "0.11.1",`
`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.0",`
	`3`	`+ "version": "0.11.1",`
`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.0",`
	`3`	`+ "version": "0.11.1",`
`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.0",`
	`3`	`+ "version": "0.11.1",`
`4`	`4`	`"description": "code-graph-mcp binary for Windows x64",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": {`