feat: set_project_root MCP tool — switch project within a running session (v0.8.2) (#86)

Users who start Claude Code from their home directory had no way to point
the RPG server at a specific project without restarting. The MCP server's
project_root was captured once at spawn and never updated; `cd` in the
session's shell only moved the Bash cwd, not the server.

New `set_project_root(path)` tool:
- Accepts tilde-expanded paths ("~/kairos-engine", "/abs/path")
- Canonicalizes and validates the path is a directory
- Swaps the server's active root atomically
- Loads the new root's .rpg/graph.json if present; reports "No graph — call
  build_rpg" if absent
- Resets lifting/hierarchy sessions, auto-sync markers, pending routing,
  and the embedding index — everything project-scoped
- Idempotent, non-destructive (annotations mark it as such)

Implementation:
- RpgServer.project_root field → project_root_cell: Arc<RwLock<PathBuf>>
- New async accessor RpgServer::project_root() returns a PathBuf snapshot
- Every tool handler and server method now reads project_root via
  self.project_root().await at call time (~50 sites converted)
- get_config_blocking → load_config, both made async
- staleness_detail made async

MCP tool count: 27 → 28. All 651 workspace tests pass.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: userFRM

.gemini/extensions/rpg/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "rpg-encoder",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Build and query semantic code graphs (Repository Planning Graphs) for AI-assisted code understanding. Provides entity search, dependency exploration, and autonomous LLM-driven semantic lifting.",
   "mcpServers": {
     "rpg-encoder": {

CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.8.2] - 2026-04-14
+
+### Added
+
+- **`set_project_root` MCP tool** — switch the active project root at runtime
+  without restarting the session. Loads the new root's `.rpg/graph.json` if
+  present, resets lifting/hierarchy sessions, auto-sync markers, and pending
+  routing state. Tilde-expands and canonicalizes the supplied path. Fixes the
+  common case where a session is launched from `$HOME` but the user wants to
+  work on `~/some-project` — previously the server's project root was locked
+  to the launch directory.
+- MCP tool count: 27 → 28.
+
+### Changed
+
+- `RpgServer::project_root` is now an async accessor backed by
+  `Arc<RwLock<PathBuf>>` (previously a static `PathBuf` field). All tool
+  handlers acquire a snapshot at call time, so each invocation reads whatever
+  `set_project_root` most recently set.
+- `get_config_blocking` renamed to `load_config` and made async.
+- `staleness_detail` made async (needed to acquire the new project-root lock).
+
 ## [0.8.1] - 2026-04-14
 
 ### Fixed

Cargo.lock

@@ -11,7 +11,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.8.1"
+version = "0.8.2"
 edition = "2024"
 license = "MIT"
 authors = ["userFRM"]

Cargo.toml

@@ -14,8 +14,8 @@ impl RpgServer {
         let session_guard = self.hierarchy_session.read().await;
         let session = session_guard.as_ref().unwrap();
 
-        let repo_name = self
-            .project_root
+        let root = self.project_root().await;
+        let repo_name = root
             .file_name()
             .and_then(|n| n.to_str())
             .unwrap_or("unknown");
@@ -90,8 +90,8 @@ impl RpgServer {
         let guard = self.graph.read().await;
         let graph = guard.as_ref().unwrap();
 
-        let repo_name = self
-            .project_root
+        let root = self.project_root().await;
+        let repo_name = root
             .file_name()
             .and_then(|n| n.to_str())
             .unwrap_or("unknown");

crates/rpg-mcp/src/hierarchy_helpers.rs

@@ -35,7 +35,7 @@ async fn main() -> Result<()> {
         if let Some(ref mut graph) = *lock
             && let (Some(base), Ok(head)) = (
                 &graph.base_commit.clone(),
-                rpg_encoder::evolution::get_head_sha(&server.project_root),
+                rpg_encoder::evolution::get_head_sha(&server.project_root().await),
             )
         {
             if *base != head {
@@ -51,7 +51,7 @@ async fn main() -> Result<()> {
                 let qcache_result =
                     rpg_parser::paradigms::query_engine::QueryCache::compile_all(&paradigm_defs);
                 let active_defs = rpg_parser::paradigms::detect_paradigms_toml(
-                    &server.project_root,
+                    &server.project_root().await,
                     &detected_langs,
                     &paradigm_defs,
                 );
@@ -66,13 +66,13 @@ async fn main() -> Result<()> {
                 });
                 match rpg_encoder::evolution::run_update(
                     graph,
-                    &server.project_root,
+                    &server.project_root().await,
                     None,
                     pipeline.as_ref(),
                 ) {
                     Ok(s) => {
                         graph.metadata.paradigms = paradigm_names;
-                        let _ = storage::save(&server.project_root, graph);
+                        let _ = storage::save(&server.project_root().await, graph);
                         eprintln!(
                             "  Auto-update complete: +{} -{} ~{}",
                             s.entities_added, s.entities_removed, s.entities_modified
@@ -85,7 +85,7 @@ async fn main() -> Result<()> {
             }
             // Seed auto-sync HEAD so the first query doesn't redundantly re-sync
             *server.last_auto_sync_head.write().await =
-                rpg_encoder::evolution::get_head_sha(&server.project_root).ok();
+                rpg_encoder::evolution::get_head_sha(&server.project_root().await).ok();
         }
     }
 

crates/rpg-mcp/src/main.rs

@@ -56,6 +56,13 @@ pub(crate) struct ExploreRpgParams {
     pub(crate) max_results: Option<usize>,
 }
 
+/// Parameters for the `set_project_root` tool.
+#[derive(Debug, Deserialize, JsonSchema)]
+pub(crate) struct SetProjectRootParams {
+    /// Absolute path to the project directory. Tilde expansion (`~`) is supported.
+    pub(crate) path: String,
+}
+
 /// Parameters for the `build_rpg` tool.
 #[derive(Debug, Deserialize, JsonSchema)]
 pub(crate) struct BuildRpgParams {

crates/rpg-mcp/src/params.rs

@@ -37,7 +37,10 @@ impl PromptVersions {
 /// The RPG MCP server state.
 #[derive(Clone)]
 pub(crate) struct RpgServer {
-    pub(crate) project_root: PathBuf,
+    /// Active project root. Mutable at runtime via the `set_project_root` tool
+    /// so a single long-lived session can switch between projects without
+    /// restart. Tools acquire a snapshot via [`RpgServer::project_root`].
+    pub(crate) project_root_cell: Arc<RwLock<PathBuf>>,
     pub(crate) graph: Arc<RwLock<Option<RPGraph>>>,
     pub(crate) config: Arc<RwLock<RpgConfig>>,
     pub(crate) lifting_session: Arc<RwLock<Option<LiftingSession>>>,
@@ -69,13 +72,18 @@ pub(crate) struct RpgServer {
 impl std::fmt::Debug for RpgServer {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_struct("RpgServer")
-            .field("project_root", &self.project_root)
+            .field("project_root", &"<lock>")
             .field("lifting_session", &"...")
             .finish()
     }
 }
 
 impl RpgServer {
+    /// Snapshot of the active project root. Cheap — locks for a single clone.
+    pub(crate) async fn project_root(&self) -> PathBuf {
+        self.project_root_cell.read().await.clone()
+    }
+
     /// Create a new server, loading graph and config from `project_root` if present.
     pub(crate) fn new(project_root: PathBuf) -> Self {
         let graph = storage::load(&project_root).ok();
@@ -86,7 +94,7 @@ impl RpgServer {
             .map(|s| s.entries)
             .unwrap_or_default();
         Self {
-            project_root,
+            project_root_cell: Arc::new(RwLock::new(project_root)),
             graph: Arc::new(RwLock::new(graph)),
             config: Arc::new(RwLock::new(config)),
             lifting_session: Arc::new(RwLock::new(None)),
@@ -107,16 +115,17 @@ impl RpgServer {
 
     /// Check if the loaded graph is stale (behind git HEAD) and return a notice string.
     pub(crate) async fn staleness_notice(&self) -> String {
+        let project_root = self.project_root().await;
         let guard = self.graph.read().await;
         let Some(graph) = guard.as_ref() else {
             return String::new();
         };
         // Detect workdir changes (committed + staged + unstaged)
-        let Ok(changes) = rpg_encoder::evolution::detect_workdir_changes(&self.project_root, graph)
+        let Ok(changes) = rpg_encoder::evolution::detect_workdir_changes(&project_root, graph)
         else {
             return String::new();
         };
-        let changes = rpg_encoder::evolution::filter_rpgignore_changes(&self.project_root, changes);
+        let changes = rpg_encoder::evolution::filter_rpgignore_changes(&project_root, changes);
         let languages = Self::resolve_languages(&graph.metadata);
         let source_changes = if languages.is_empty() {
             changes
@@ -150,8 +159,9 @@ impl RpgServer {
     /// markers — the next query will retry, so transient failures don't
     /// silently leave the server stale.
     pub(crate) async fn auto_sync_if_stale(&self) -> String {
+        let project_root = self.project_root().await;
         // Step 1: Get current HEAD (cheap, just opens .git/HEAD)
-        let Ok(current_head) = rpg_encoder::evolution::get_head_sha(&self.project_root) else {
+        let Ok(current_head) = rpg_encoder::evolution::get_head_sha(&project_root) else {
             return self.staleness_notice().await;
         };
 
@@ -161,21 +171,19 @@ impl RpgServer {
             let Some(graph) = guard.as_ref() else {
                 return String::new();
             };
-            let Ok(changes) =
-                rpg_encoder::evolution::detect_workdir_changes(&self.project_root, graph)
+            let Ok(changes) = rpg_encoder::evolution::detect_workdir_changes(&project_root, graph)
             else {
                 return String::new();
             };
-            let changes =
-                rpg_encoder::evolution::filter_rpgignore_changes(&self.project_root, changes);
+            let changes = rpg_encoder::evolution::filter_rpgignore_changes(&project_root, changes);
             let languages = Self::resolve_languages(&graph.metadata);
             let source_changes = if languages.is_empty() {
                 changes
             } else {
                 rpg_encoder::evolution::filter_source_changes(changes, &languages)
             };
             let paths = Self::change_paths(&source_changes);
-            let hash = Self::compute_changeset_hash(&source_changes, &self.project_root);
+            let hash = Self::compute_changeset_hash(&source_changes, &project_root);
             (source_changes, paths, hash)
         };
 
@@ -187,7 +195,7 @@ impl RpgServer {
             let last_paths = self.last_auto_sync_workdir_paths.read().await;
             let mut effective = source_changes.clone();
             for path in last_paths.difference(&current_paths) {
-                let abs = self.project_root.join(path);
+                let abs = project_root.join(path);
                 if abs.is_file() {
                     effective.push(rpg_encoder::evolution::FileChange::Modified(path.clone()));
                 } else {
@@ -228,7 +236,7 @@ impl RpgServer {
         let qcache_result =
             rpg_parser::paradigms::query_engine::QueryCache::compile_all(&paradigm_defs);
         let active_defs = rpg_parser::paradigms::detect_paradigms_toml(
-            &self.project_root,
+            &project_root,
             &detected_langs,
             &paradigm_defs,
         );
@@ -243,13 +251,13 @@ impl RpgServer {
 
         match rpg_encoder::evolution::run_update_from_changes(
             graph,
-            &self.project_root,
+            &project_root,
             effective_changes,
             pipeline.as_ref(),
         ) {
             Ok(summary) => {
                 graph.metadata.paradigms = paradigm_names;
-                let _ = storage::save(&self.project_root, graph);
+                let _ = storage::save(&project_root, graph);
                 *self.last_auto_sync_head.write().await = Some(current_head);
                 *self.last_auto_sync_changeset.write().await = Some(current_changeset);
                 *self.last_auto_sync_workdir_paths.write().await = current_paths;
@@ -405,7 +413,8 @@ impl RpgServer {
         }
         drop(read);
 
-        match storage::load(&self.project_root) {
+        let project_root = self.project_root().await;
+        match storage::load(&project_root) {
             Ok(g) => {
                 *self.graph.write().await = Some(g);
                 Ok(())
@@ -417,10 +426,10 @@ impl RpgServer {
     }
 
     /// Detailed staleness info: which source files changed (committed + staged + unstaged).
-    pub(crate) fn staleness_detail(&self, graph: &RPGraph) -> Option<String> {
-        let changes =
-            rpg_encoder::evolution::detect_workdir_changes(&self.project_root, graph).ok()?;
-        let changes = rpg_encoder::evolution::filter_rpgignore_changes(&self.project_root, changes);
+    pub(crate) async fn staleness_detail(&self, graph: &RPGraph) -> Option<String> {
+        let project_root = self.project_root().await;
+        let changes = rpg_encoder::evolution::detect_workdir_changes(&project_root, graph).ok()?;
+        let changes = rpg_encoder::evolution::filter_rpgignore_changes(&project_root, changes);
         let languages = Self::resolve_languages(&graph.metadata);
         let changes = rpg_encoder::evolution::filter_source_changes(changes, &languages);
 
@@ -471,7 +480,7 @@ impl RpgServer {
         };
 
         // Check staleness
-        let stale_detail = self.staleness_detail(graph);
+        let stale_detail = self.staleness_detail(graph).await;
         let graph_line = match &stale_detail {
             Some(detail) => format!(
                 "graph: {} ({} entities, {} files)",
@@ -592,9 +601,10 @@ impl RpgServer {
         Ok(out)
     }
 
-    /// Load config synchronously (for contexts that cannot await).
-    pub(crate) fn get_config_blocking(&self) -> RpgConfig {
-        RpgConfig::load(&self.project_root).unwrap_or_default()
+    /// Load the RPG config for the active project.
+    pub(crate) async fn load_config(&self) -> RpgConfig {
+        let project_root = self.project_root().await;
+        RpgConfig::load(&project_root).unwrap_or_default()
     }
 
     /// Lazy-initialize the embedding index on first semantic search.
@@ -612,8 +622,9 @@ impl RpgServer {
             return;
         }
 
+        let project_root = self.project_root().await;
         let updated_at = graph.updated_at.to_rfc3339();
-        match rpg_nav::embeddings::EmbeddingIndex::load_or_init(&self.project_root, &updated_at) {
+        match rpg_nav::embeddings::EmbeddingIndex::load_or_init(&project_root, &updated_at) {
             Ok(mut idx) => {
                 // Incremental sync: only re-embed entities whose features changed
                 if let Err(e) = idx.sync(graph) {