feat: Add find_nodes_by_name tool and project-aware functions

- Introduced `find_nodes_by_name` tool for searching nodes by partial name within the current project context.
- Implemented `count_nodes_for_project` function for health checks to ensure nodes are indexed per project.
- Updated README to reflect project scoping and usage of SurrealDB functions.
- Enhanced GraphQL schema and SurrealDB functions to support new features.
- Added tests for new functionalities to ensure correctness and reliability.

Author: jruokola

README.md

@@ -627,6 +627,8 @@ After indexing your codebase, AI agents can use these agentic workflows (require
 
 These multi-step workflows typically take 30–90 seconds to complete because they traverse the code graph and build detailed reasoning summaries.
 
+**Project scoping:** MCP tool calls and SurrealDB functions are project-isolated. The server picks `CODEGRAPH_PROJECT_ID` (falls back to your current working directory); use a distinct value per workspace when sharing one Surreal instance, or you’ll blend graph results across projects. If you update the schema, re-apply `schema/codegraph.surql` so the project-aware functions are available.
+
 ### Quick Start
 
 ```bash

crates/codegraph-graph/Cargo.toml

@@ -18,7 +18,7 @@ chrono = { workspace = true }
 sha2 = { workspace = true }
 
 # SurrealDB support (optional, default on via feature flag)
-surrealdb = { version = "2.2", optional = true }
+surrealdb = { version = "2.2", optional = true, features = ["kv-mem"] }
 dotenvy = { version = "0.15", optional = true }
 tokio = { workspace = true, optional = true, features = ["macros", "rt-multi-thread"] }
 

crates/codegraph-graph/src/graph_functions.rs

@@ -3,6 +3,7 @@
 
 use codegraph_core::{CodeGraphError, Result};
 use serde::{Deserialize, Serialize};
+use serde_json::json;
 use std::sync::Arc;
 use surrealdb::{engine::any::Any, Surreal};
 use tracing::{debug, error};
@@ -269,6 +270,60 @@ impl GraphFunctions {
 
         Ok(result)
     }
+
+    /// Count nodes for the current project (used for health checks)
+    pub async fn count_nodes_for_project(&self) -> Result<usize> {
+        let mut response = self
+            .db
+            .query("SELECT VALUE count() FROM nodes WHERE project_id = $project_id")
+            .bind(("project_id", self.project_id.clone()))
+            .await
+            .map_err(|e| {
+                CodeGraphError::Database(format!(
+                    "count_nodes_for_project query failed: {}",
+                    e
+                ))
+            })?;
+
+        let count: Option<usize> = response.take(0).map_err(|e| {
+            CodeGraphError::Database(format!("Failed to deserialize count: {}", e))
+        })?;
+
+        Ok(count.unwrap_or(0))
+    }
+
+    /// Find nodes by (partial) name within the current project
+    pub async fn find_nodes_by_name(
+        &self,
+        needle: &str,
+        limit: usize,
+    ) -> Result<Vec<NodeReference>> {
+        let max = limit.clamp(1, 50) as i64;
+
+        debug!(
+            "Calling fn::find_nodes_by_name({}, project={}, limit={})",
+            needle, self.project_id, max
+        );
+
+        let result: Vec<NodeReference> = self
+            .db
+            .query("RETURN fn::find_nodes_by_name($project_id, $needle, $limit)")
+            .bind(("project_id", self.project_id.clone()))
+            .bind(("needle", needle.to_string()))
+            .bind(("limit", max))
+            .await
+            .map_err(|e| {
+                error!("Failed to call find_nodes_by_name: {}", e);
+                CodeGraphError::Database(format!("find_nodes_by_name failed: {}", e))
+            })?
+            .take(0)
+            .map_err(|e| {
+                error!("Failed to deserialize find_nodes_by_name results: {}", e);
+                CodeGraphError::Database(format!("Deserialization failed: {}", e))
+            })?;
+
+        Ok(result)
+    }
 }
 
 // ============================================================================
@@ -416,4 +471,50 @@ mod tests {
         let json = serde_json::to_string(&node).unwrap();
         assert!(json.contains("test_function"));
     }
+
+    #[cfg(feature = "surrealdb")]
+    #[tokio::test]
+    async fn count_nodes_for_project_filters_by_project() {
+        use surrealdb::opt::auth::Root;
+
+        let db: Surreal<Any> = Surreal::init();
+        db.connect("mem://").await.unwrap();
+        db.use_ns("test").use_db("test").await.unwrap();
+        db.signin(Root {
+            username: "root",
+            password: "root",
+        })
+        .await
+        .ok(); // mem engine ignores auth
+
+        // Two projects, only one should be counted
+        db.query("CREATE nodes CONTENT $doc")
+            .bind((
+                "doc",
+                json!({
+                    "id": "nodes:a1",
+                    "name": "A1",
+                    "project_id": "proj-a"
+                }),
+            ))
+            .await
+            .unwrap();
+
+        db.query("CREATE nodes CONTENT $doc")
+            .bind((
+                "doc",
+                json!({
+                    "id": "nodes:b1",
+                    "name": "B1",
+                    "project_id": "proj-b"
+                }),
+            ))
+            .await
+            .unwrap();
+
+        let gf = GraphFunctions::new_with_project_id(Arc::new(db), "proj-a");
+        let count = gf.count_nodes_for_project().await.unwrap();
+
+        assert_eq!(count, 1, "Should only count nodes in proj-a");
+    }
 }

crates/codegraph-mcp/src/autoagents/agent_builder.rs

@@ -504,6 +504,7 @@ impl CodeGraphAgentBuilder {
 
         // Manually construct all 6 tools with the executor (Arc-wrapped for sharing)
         let tools: Vec<Arc<dyn ToolT>> = vec![
+            Arc::new(FindNodesByName::new(executor_adapter.clone())),
             Arc::new(GetTransitiveDependencies::new(executor_adapter.clone())),
             Arc::new(GetReverseDependencies::new(executor_adapter.clone())),
             Arc::new(TraceCallChain::new(executor_adapter.clone())),

crates/codegraph-mcp/src/autoagents/tools/graph_tools.rs

@@ -329,6 +329,61 @@ impl ToolRuntime for GetHubNodes {
     }
 }
 
+/// Parameters for find_nodes_by_name
+#[derive(Serialize, Deserialize, ToolInput, Debug)]
+pub struct FindNodesByNameArgs {
+    #[input(description = "Partial function/file name to search for (case-insensitive)")]
+    needle: String,
+    #[input(description = "Maximum number of results (1-50, default: 10)")]
+    #[serde(default = "default_find_limit")]
+    limit: i32,
+}
+
+fn default_find_limit() -> i32 {
+    10
+}
+
+/// Find nodes by (partial) name within project scope
+#[tool(
+    name = "find_nodes_by_name",
+    description = "Search for nodes by partial name or file path within the current project. Returns IDs to use with other graph tools.",
+    input = FindNodesByNameArgs,
+)]
+pub struct FindNodesByName {
+    executor: Arc<GraphToolExecutorAdapter>,
+}
+
+impl FindNodesByName {
+    pub fn new(executor: Arc<GraphToolExecutorAdapter>) -> Self {
+        Self { executor }
+    }
+}
+
+#[async_trait::async_trait]
+impl ToolRuntime for FindNodesByName {
+    async fn execute(&self, args: serde_json::Value) -> Result<serde_json::Value, ToolCallError> {
+        let typed_args: FindNodesByNameArgs = serde_json::from_value(args)?;
+
+        let result = self
+            .executor
+            .execute_sync(
+                "find_nodes_by_name",
+                serde_json::json!({
+                    "needle": typed_args.needle,
+                    "limit": typed_args.limit
+                }),
+            )
+            .map_err(|e| {
+                ToolCallError::RuntimeError(Box::new(std::io::Error::new(
+                    std::io::ErrorKind::Other,
+                    e,
+                )))
+            })?;
+
+        Ok(result)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

crates/codegraph-mcp/src/dependency_analysis_prompts.rs

@@ -11,6 +11,7 @@ pub const DEPENDENCY_ANALYSIS_TERSE: &str = r#"You are an expert code dependency
 OBJECTIVE: Analyze dependency relationships efficiently using minimal tool calls.
 
 AVAILABLE TOOLS:
+0. find_nodes_by_name(needle, limit) - Resolve user-mentioned component to exact node IDs (must run first if ID unknown)
 1. get_transitive_dependencies(node_id, edge_type, depth) - Get dependencies of a node
 2. detect_circular_dependencies(edge_type) - Find circular dependency cycles
 3. trace_call_chain(from_node, max_depth) - Trace function call sequences
@@ -38,7 +39,7 @@ EXECUTION PATTERN:
 CRITICAL RULES:
 - NO HEURISTICS: Only report what tools show, never assume or infer
 - NO REDUNDANCY: Each tool call must provide new information
-- EXTRACT NODE IDS: Use exact IDs from tool results (e.g., "nodes:123")
+- EXTRACT NODE IDS: Use find_nodes_by_name to resolve IDs; then use exact IDs from tool results (e.g., "nodes:123")
 - BE DIRECT: No verbose explanations, just essential findings
 "#;
 
@@ -52,6 +53,7 @@ pub const DEPENDENCY_ANALYSIS_BALANCED: &str = r#"You are an expert code depende
 OBJECTIVE: Analyze dependency relationships systematically, building complete understanding of impact and coupling.
 
 AVAILABLE TOOLS:
+0. find_nodes_by_name(needle, limit) - Resolve names/paths to exact node IDs (run first if ID not already known)
 1. get_transitive_dependencies(node_id, edge_type, depth) - Get all dependencies up to depth
    - Use depth=2-3 for balanced analysis
    - Edge types: Calls, Imports, Uses, Extends, Implements, References
@@ -98,7 +100,7 @@ SYSTEMATIC APPROACH:
 
 CRITICAL RULES:
 - NO HEURISTICS: Only report structured data from tools
-- EXTRACT IDS: Always use exact node IDs from tool results (format: "nodes:123")
+- EXTRACT IDS: Resolve with find_nodes_by_name, then use exact node IDs from tool results (format: "nodes:123")
 - BUILD CHAINS: Connect findings to show dependency paths
 - QUANTIFY IMPACT: Use metrics (Ca, Ce, Instability) not vague terms
 - CITE SOURCES: Reference specific tool results for all claims

crates/codegraph-mcp/src/graph_tool_executor.rs

@@ -170,6 +170,7 @@ impl GraphToolExecutor {
                 self.execute_get_reverse_dependencies(parameters.clone())
                     .await?
             }
+            "find_nodes_by_name" => self.execute_find_nodes_by_name(parameters.clone()).await?,
             _ => {
                 return Err(
                     McpError::Protocol(format!("Tool not implemented: {}", tool_name)).into(),
@@ -343,6 +344,30 @@ impl GraphToolExecutor {
         }))
     }
 
+    /// Execute find_nodes_by_name
+    async fn execute_find_nodes_by_name(&self, params: JsonValue) -> Result<JsonValue> {
+        let needle = params["needle"]
+            .as_str()
+            .ok_or_else(|| McpError::Protocol("Missing needle".to_string()))?;
+
+        let limit = params["limit"].as_i64().unwrap_or(10) as usize;
+
+        let result = self
+            .graph_functions
+            .find_nodes_by_name(needle, limit)
+            .await
+            .map_err(|e| McpError::Protocol(format!("find_nodes_by_name failed: {}", e)))?;
+
+        Ok(json!({
+            "tool": "find_nodes_by_name",
+            "parameters": {
+                "needle": needle,
+                "limit": limit
+            },
+            "result": result
+        }))
+    }
+
     /// Get all available tool schemas for registration
     pub fn get_tool_schemas() -> Vec<crate::ToolSchema> {
         GraphToolSchemas::all()

crates/codegraph-mcp/src/graph_tool_schemas.rs

@@ -25,6 +25,7 @@ impl GraphToolSchemas {
             Self::calculate_coupling_metrics(),
             Self::get_hub_nodes(),
             Self::get_reverse_dependencies(),
+            Self::find_nodes_by_name(),
         ]
     }
 
@@ -186,6 +187,32 @@ impl GraphToolSchemas {
         }
     }
 
+    /// Schema for find_nodes_by_name function
+    pub fn find_nodes_by_name() -> ToolSchema {
+        ToolSchema {
+            name: "find_nodes_by_name".to_string(),
+            description: "Search for nodes by (partial) name or file path within the current project context. \
+                Use this to resolve human-readable function or file names to concrete node IDs before other graph queries.".to_string(),
+            parameters: json!({
+                "type": "object",
+                "properties": {
+                    "needle": {
+                        "type": "string",
+                        "description": "Partial name or file path fragment to search for (case-insensitive name match, file_path contains match)"
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum number of results (1-50, defaults to 10)",
+                        "minimum": 1,
+                        "maximum": 50,
+                        "default": 10
+                    }
+                },
+                "required": ["needle"]
+            }),
+        }
+    }
+
     /// Get schema by name
     pub fn get_by_name(name: &str) -> Option<ToolSchema> {
         Self::all().into_iter().find(|s| s.name == name)
@@ -204,7 +231,7 @@ mod tests {
     #[test]
     fn test_all_schemas_valid() {
         let schemas = GraphToolSchemas::all();
-        assert_eq!(schemas.len(), 6, "Should have exactly 6 tool schemas");
+        assert_eq!(schemas.len(), 7, "Should have exactly 7 tool schemas");
 
         for schema in schemas {
             assert!(!schema.name.is_empty(), "Schema name should not be empty");
@@ -232,13 +259,14 @@ mod tests {
     #[test]
     fn test_tool_names() {
         let names = GraphToolSchemas::tool_names();
-        assert_eq!(names.len(), 6);
+        assert_eq!(names.len(), 7);
         assert!(names.contains(&"get_transitive_dependencies".to_string()));
         assert!(names.contains(&"detect_circular_dependencies".to_string()));
         assert!(names.contains(&"trace_call_chain".to_string()));
         assert!(names.contains(&"calculate_coupling_metrics".to_string()));
         assert!(names.contains(&"get_hub_nodes".to_string()));
         assert!(names.contains(&"get_reverse_dependencies".to_string()));
+        assert!(names.contains(&"find_nodes_by_name".to_string()));
     }
 
     #[test]

crates/codegraph-mcp/src/official_server.rs

@@ -563,6 +563,23 @@ impl CodeGraphMCPServer {
             Arc::new(GraphFunctions::new(storage.db()))
         };
 
+        // Health check: ensure the active project has indexed nodes
+        match graph_functions.count_nodes_for_project().await {
+            Ok(0) => tracing::warn!(
+                "Project '{}' has zero nodes indexed. Ensure CODEGRAPH_PROJECT_ID matches the indexed project and rerun `codegraph index`.",
+                graph_functions.project_id()
+            ),
+            Ok(count) => tracing::info!(
+                "Project '{}' has {} indexed nodes available for analysis",
+                graph_functions.project_id(),
+                count
+            ),
+            Err(e) => tracing::warn!(
+                "Could not verify project data presence: {}. Continuing without blocking.",
+                e
+            ),
+        }
+
         // Create GraphToolExecutor
         let tool_executor = Arc::new(crate::GraphToolExecutor::new(graph_functions));