feat(mcp): add codegraph_index_health diagnostics tool

Agents had no cheap way to check whether the current index is stale or
empty before trusting a "no results" answer, or to see what other projects
share the same on-disk graph database. Reuses existing infrastructure
(the _registry:<slug> entries persist_graph already writes, graph_db_generation(),
GitExecutor::head_commit(), IndexState::all_hashes()) rather than adding new
storage.

Returns current node/edge counts, generation, last-indexed time, a short git
HEAD hint, a cheap re-hash-based staleness check against already-tracked
files (no directory walk — that's what a real reindex is for), the other
namespaces sharing this machine's graph.db, and suggested_next_queries when
something looks off. Also surfaces codegraph_index_health as a suggested
next query on a degraded codegraph_reindex_workspace response.

Author: Znbiz

crates/codegraph-server/src/mcp/server.rs

@@ -3478,14 +3478,109 @@ impl McpServer {
                     )
                 };
 
-                Ok(serde_json::json!({
+                let mut response = serde_json::json!({
                     "status": status,
                     "message": message,
                     "files_indexed": total,
                     "files_parsed": parsed,
                     "files_skipped": total - parsed,
                     "node_count_after": node_count_after,
                     "auto_retried_with_force": auto_retried
+                });
+                if degraded {
+                    if let Some(obj) = response.as_object_mut() {
+                        obj.insert(
+                            "suggested_next_queries".to_string(),
+                            serde_json::json!([
+                                "codegraph_index_health — inspect workspace_root, .codegraphignore \
+                                 exclusions, and files_changed_since_index before retrying",
+                            ]),
+                        );
+                    }
+                }
+                Ok(response)
+            }
+
+            // ==================== Index Health ====================
+            "codegraph_index_health" => {
+                let (node_count, edge_count) = {
+                    let graph = self.backend.graph.read().await;
+                    (graph.node_count(), graph.edge_count())
+                };
+
+                let workspace_root = self
+                    .backend
+                    .workspace_folders
+                    .first()
+                    .map(|p| p.display().to_string());
+
+                let workspace_revision_hint = self
+                    .backend
+                    .workspace_folders
+                    .first()
+                    .and_then(|ws| crate::git_mining::GitExecutor::new(ws).ok())
+                    .and_then(|g| g.head_commit().ok())
+                    .map(|h| h[..8.min(h.len())].to_string());
+
+                // Cheap staleness check: re-hash only files we already know
+                // about (no directory walk) and count content drift. Doesn't
+                // catch brand-new/deleted files — that needs a full walk,
+                // which is what reindex itself does; this stays cheap on
+                // purpose so it's safe to call before every risky operation.
+                let files_changed_since_index = {
+                    let state = self.backend.index_state.lock().await;
+                    state
+                        .all_hashes()
+                        .iter()
+                        .filter(|(path, &stored_hash)| {
+                            match std::fs::read(path) {
+                                Ok(content) => {
+                                    crate::indexer::Indexer::hash_content(&content) != stored_hash
+                                }
+                                Err(_) => true, // file removed/unreadable since indexing
+                            }
+                        })
+                        .count()
+                };
+                let files_tracked = self.backend.index_state.lock().await.len();
+
+                let registry = McpBackend::list_indexed_projects().unwrap_or_default();
+                let (index_generated_at, other_namespaces): (Option<u64>, Vec<serde_json::Value>) = {
+                    let mut generated_at = None;
+                    let mut others = Vec::new();
+                    for project in registry {
+                        let slug = project.get("slug").and_then(|v| v.as_str()).unwrap_or("");
+                        if slug == self.backend.project_slug {
+                            generated_at = project.get("last_indexed").and_then(|v| v.as_u64());
+                        } else {
+                            others.push(project);
+                        }
+                    }
+                    (generated_at, others)
+                };
+
+                let potentially_stale = node_count == 0 || files_changed_since_index > 0;
+
+                let mut suggested_next_queries: Vec<&str> = Vec::new();
+                if node_count == 0 {
+                    suggested_next_queries.push("codegraph_reindex_workspace(force=true)");
+                } else if files_changed_since_index > 0 {
+                    suggested_next_queries.push("codegraph_reindex_workspace(force=false)");
+                }
+
+                Ok(serde_json::json!({
+                    "namespace": self.backend.project_slug,
+                    "workspace_root": workspace_root,
+                    "node_count": node_count,
+                    "edge_count": edge_count,
+                    "generation": crate::memory::graph_db_generation(),
+                    "index_generated_at": index_generated_at,
+                    "workspace_revision_hint": workspace_revision_hint,
+                    "files_tracked": files_tracked,
+                    "files_changed_since_index": files_changed_since_index,
+                    "potentially_stale": potentially_stale,
+                    "other_namespaces": other_namespaces,
+                    "suggested_next_queries": suggested_next_queries,
                 }))
             }
 

crates/codegraph-server/src/mcp/tools.rs

@@ -142,10 +142,11 @@ pub fn get_all_tools() -> Vec<Tool> {
         find_dead_imports_tool(),
         // Ops Struct Tools (1)
         find_implementors_tool(),
-        // Admin Tools (3)
+        // Admin Tools (4)
         reindex_workspace_tool(),
         index_files_tool(),
         index_directory_tool(),
+        index_health_tool(),
         // PR / Change Analysis (1)
         pr_context_tool(),
         // Docs Tools (7)
@@ -1236,6 +1237,18 @@ fn reindex_workspace_tool() -> Tool {
     }
 }
 
+fn index_health_tool() -> Tool {
+    Tool {
+        name: "codegraph_index_health".to_string(),
+        description: Some("Cheap health/freshness check for the current index — no full reindex, safe to call before any risky sequence of queries. USE WHEN: you got surprisingly few/no results and want to know whether the index is stale or empty before assuming the code doesn't exist, or before a multi-step task where you want to confirm the index is trustworthy up front. Returns: namespace, workspace_root, node_count, edge_count, generation, index_generated_at (unix seconds of last persist), workspace_revision_hint (short git HEAD, if a git repo), files_tracked, files_changed_since_index (cheap re-hash of already-tracked files — does not detect brand-new/deleted files, that needs a full reindex), potentially_stale, other_namespaces (other indexed projects sharing this machine's graph database, for cross-namespace comparison), and suggested_next_queries when the index looks unhealthy. No parameters.".to_string()),
+        input_schema: ToolInputSchema {
+            schema_type: "object".to_string(),
+            properties: None,
+            required: None,
+        },
+    }
+}
+
 fn index_files_tool() -> Tool {
     let mut properties = HashMap::new();
     properties.insert(
@@ -1801,14 +1814,14 @@ mod tests {
     fn test_get_all_tools_count() {
         let tools = get_all_tools();
         // Analysis: 12 (incl. probe_symbol), Search: 8, Navigation: 3, Memory: 7,
-        // Dead Imports: 1, Ops: 1, Admin: 3, Docs: 7, PR: 1 = 43 community tools
+        // Dead Imports: 1, Ops: 1, Admin: 4 (incl. index_health), Docs: 7, PR: 1 = 44 community tools
         // (12 premium tools moved to pro edition: scan_security, analyze_coupling, find_unused_code,
         //  find_duplicates, find_similar, cluster_symbols, compare_symbols, cross_project_search,
         //  mine_git_history, mine_git_history_for_file, search_git_history)
         assert_eq!(
             tools.len(),
-            43,
-            "Expected 43 community tools, got {}",
+            44,
+            "Expected 44 community tools, got {}",
             tools.len()
         );
     }