Allow live project root switching and temporary root overrides

[VooDisss]

Issue Draft: Cross-Root RPG Exploration for MCP

Summary

The MCP server can currently operate only on its active project_root, which is set at startup and then reused by all read-only semantic tools. This makes it difficult to inspect an external repository graph from a long-lived session rooted in another workspace.

We need a way to query another codebase temporarily, without permanently switching the server session root.

Problem

The current exposed rpg_development_* tool set includes:

• rpg_development_build_rpg
• rpg_development_reload_rpg
• rpg_development_update_rpg
• rpg_development_rpg_info
• rpg_development_search_node
• rpg_development_fetch_node
• rpg_development_explore_rpg
• and the remaining lifting / hierarchy / analysis tools

However, there is no exposed MCP tool for changing project_root, and the read-only tools do not accept a per-call root override.

That means an agent rooted in one workspace cannot easily inspect the RPG graph of a sibling or parent repository, even when that repository already has its own .rpg/graph.json.

Desired Behavior

Support two distinct workflows:

1. Persistent session switch

   • Switch the active project_root to another repository path while the MCP server is still running.
   • This should reload the target repo graph and config, and reset session-scoped state.
   • Changing the project root must not require restarting the MCP server.

2. Temporary per-call override

   • Allow semantic read-only tools to accept an optional project_root parameter.
   • When provided, the tool should query that repository graph for that call only.
   • The active session root must remain unchanged.

The persistent switch is for changing the session context live.
The temporary override is the preferred behavior for one-off cross-repo exploration because it avoids contaminating the existing session state.

Recommended Scope

Start with the read-only tools that are most useful for cross-repo exploration:

• search_node
• fetch_node
• explore_rpg
• rpg_info

If the implementation is straightforward, extend the same pattern to other read-only analysis tools later:

• context_pack
• slice_between
• find_paths
• impact_radius
• detect_cycles
• analyze_health
• plan_change

Suggested API Shape

Add an optional project_root field to the relevant tool parameters.

Example:

{
  "query": "OpenCode SDK",
  "mode": "features",
  "project_root": "/path/to/opencode"
}

Implementation Notes

• Canonicalize the override path before using it.
• If the path does not exist or is not accessible, return a clear error.
• Load .rpg/graph.json from the override root on demand.
• Do not mutate project_root_cell for temporary overrides.
• Do not carry over stale lifting sessions, pending routing, or auto-sync markers across override calls.
• Keep set_project_root semantics separate from per-call overrides if both are implemented.

Acceptance Criteria

• A caller can query another repository graph without restarting the MCP server.
• Temporary overrides do not change the server’s active session root.
• Existing behavior for tools without overrides remains unchanged.
• Errors are clear when the override root has no .rpg/graph.json or is invalid.
• The current root-switching flow still works for persistent session changes.
• The server can change its active project root at runtime without a restart.

Example Use Case

An agent is rooted in one repository and wants to inspect another repository named opencode.

With this feature, the agent could run a temporary semantic search against the OpenCode graph, inspect the exposed SDK methods, and return to the original root unchanged.

Non-Goals

• Building a multi-root session model.
• Merging graphs from multiple repositories into one shared session.
• Changing how .rpg/graph.json is stored on disk.