feat(server-clone): Phase 3 — Meta-tool + docs surfacing

Autonomous decisions:
- Added InstalledServerRepository to MetaToolContext so mcpmux_list_servers
  can resolve cloned_from without a core type change (field already on InstalledServer)
- Omitted cloned_from from non-clone rows rather than emitting null
- Skipped jsg-tech-check migration doc (out of repo per orchestrator)
- Updated planning doc status/checkboxes to match Phases 1–3 completion

Signed-off-by: crimsonsunset <jsangio1@gmail.com>

Author: crimsonsunset

crates/mcpmux-gateway/src/server/service_container.rs

@@ -131,6 +131,7 @@ impl ServiceContainer {
             deps.feature_set_repo.clone(),
             deps.workspace_binding_repo.clone(),
             deps.feature_repo.clone(),
+            deps.installed_server_repo.clone(),
             feature_set_resolver.clone(),
             pool_services.feature_service.clone(),
             session_roots.clone(),

crates/mcpmux-gateway/src/services/meta_tools/mod.rs

@@ -56,6 +56,7 @@ pub fn build_default_registry(
     feature_set_repo: std::sync::Arc<dyn mcpmux_core::FeatureSetRepository>,
     binding_repo: std::sync::Arc<dyn mcpmux_core::WorkspaceBindingRepository>,
     server_feature_repo: std::sync::Arc<dyn mcpmux_core::ServerFeatureRepository>,
+    installed_server_repo: std::sync::Arc<dyn mcpmux_core::InstalledServerRepository>,
     resolver: std::sync::Arc<crate::services::FeatureSetResolverService>,
     feature_service: std::sync::Arc<crate::pool::FeatureService>,
     session_roots: std::sync::Arc<crate::services::SessionRootsRegistry>,
@@ -70,6 +71,7 @@ pub fn build_default_registry(
         feature_set_repo,
         binding_repo,
         server_feature_repo,
+        installed_server_repo,
         resolver,
         feature_service,
         session_roots,

crates/mcpmux-gateway/src/services/meta_tools/registry.rs

@@ -9,8 +9,8 @@ use std::sync::{Arc, Mutex};
 
 use async_trait::async_trait;
 use mcpmux_core::{
-    DomainEvent, FeatureSetRepository, InboundMcpClientRepository, ServerFeatureRepository,
-    SpaceRepository, WorkspaceBindingRepository,
+    DomainEvent, FeatureSetRepository, InboundMcpClientRepository, InstalledServerRepository,
+    ServerFeatureRepository, SpaceRepository, WorkspaceBindingRepository,
 };
 use rmcp::model::{CallToolResult, Tool};
 use serde_json::Value;
@@ -41,6 +41,7 @@ pub struct MetaToolContext {
     pub feature_set_repo: Arc<dyn FeatureSetRepository>,
     pub binding_repo: Arc<dyn WorkspaceBindingRepository>,
     pub server_feature_repo: Arc<dyn ServerFeatureRepository>,
+    pub installed_server_repo: Arc<dyn InstalledServerRepository>,
     pub resolver: Arc<FeatureSetResolverService>,
     pub feature_service: Arc<FeatureService>,
     pub session_roots: Arc<SessionRootsRegistry>,

crates/mcpmux-gateway/src/services/meta_tools/tools.rs

@@ -211,7 +211,8 @@ impl MetaTool for ListServersTool {
     fn description(&self) -> &'static str {
         "List every MCP server installed in the caller's resolved Space with \
          a coarse status per server: enabled_via_binding, enabled_via_session, \
-         disabled_via_session, or inactive. Use before enable/disable to see \
+         disabled_via_session, or inactive. Clone installs include optional \
+         `cloned_from` (source server_id). Use before enable/disable to see \
          current routing state without loading every tool."
     }
 
@@ -250,6 +251,17 @@ impl MetaTool for ListServersTool {
             .list_for_space(&space_id.to_string())
             .await?;
 
+        let installed = call
+            .ctx
+            .installed_server_repo
+            .list_for_space(&space_id.to_string())
+            .await
+            .map_err(|e| MetaToolError::Internal(e.to_string()))?;
+        let cloned_from_by_server: HashMap<String, Option<String>> = installed
+            .into_iter()
+            .map(|s| (s.server_id, s.cloned_from))
+            .collect();
+
         let mut by_server: HashMap<String, (Option<String>, usize)> = HashMap::new();
         for feature in &features {
             if feature.feature_type != FeatureType::Tool {
@@ -274,12 +286,16 @@ impl MetaTool for ListServersTool {
                     &session_enabled,
                     &session_disabled,
                 );
-                json!({
+                let mut entry = json!({
                     "id": id,
                     "name": name,
                     "tool_count": tool_count,
                     "status": status,
-                })
+                });
+                if let Some(cloned_from) = cloned_from_by_server.get(&id).and_then(|v| v.as_ref()) {
+                    entry["cloned_from"] = json!(cloned_from);
+                }
+                entry
             })
             .collect();
         servers.sort_by(|a, b| {

docs/guide/servers.mdx

@@ -100,6 +100,33 @@ Disabling a server immediately disconnects it and removes its tools from connect
 
 ![Expanded server view showing available tools and prompts for each connected server](https://mcpmux.com/screenshots/server-expanded.png)
 
+## Multiple Accounts
+
+Some MCP servers only support one account per process. Others accept a per-call account parameter, or you may simply want work and personal credentials in separate contexts. Use this decision tree:
+
+```text
+Need more than one account for the same MCP?
+├─ The MCP accepts a per-call account parameter (e.g. Google Workspace `user_google_email`)
+│   └─ Install once — pass the account on each tool call. No clone needed.
+├─ Accounts map to different repo or project context (work vs personal vs client)
+│   └─ Use [Spaces](/docs/spaces/) — one install per Space with separate credentials.
+└─ Two or more accounts in the SAME Space for a single-account MCP
+    └─ Clone via **Add another account…** on the server card in My Servers.
+```
+
+### Cloning a server
+
+When you need two PostHog workspaces, Firebase projects, or Gmail accounts in one Space:
+
+1. Open **My Servers** and use the server menu → **Add another account…**
+2. Choose a suffix (`work`, `personal`, `prod`, etc.) — the clone ID becomes `{server}-{suffix}` (e.g. `posthog-work`)
+3. Configure credentials for the clone (secrets are never copied from the source)
+4. Enable the clone — tools appear with the clone prefix (e.g. `posthog-work_capture`)
+
+Clones are independent installs: separate credentials, OAuth sessions, and tool prefixes. The source server is unchanged. You cannot clone a clone (max depth 1).
+
+When using [meta tools](/docs/feature-sets/) (`mcpmux_list_servers`), clone rows include an optional `cloned_from` field with the source server ID so an LLM can see lineage.
+
 ## Connection Status
 
 The **My Servers** page shows real-time connection status for each server:

docs/planning/server-account-clones.md

@@ -1,8 +1,8 @@
 # Server Account Clones (UI-Assisted Multi-Account)
 
 **Last Updated:** May 23, 2026
-**Status:** Planning — decisions locked, not started
-**Branch:** TBD — file after planning review
+**Status:** In progress — Phases 1–3 complete, Phase 4 pending
+**Branch:** `feat/server-account-clones`
 **Base branch:** `main`
 **Issue:** TBD — file after planning review
 **Depends on:** None (orthogonal to session meta-tools; benefits from but does not require PR #154)
@@ -163,27 +163,27 @@ Multi-account need?
 
 **Effort:** ~1 day
 
-- [ ] Migration: `cloned_from TEXT NULL` on `installed_servers`
-- [ ] `InstalledServer.cloned_from` field + repo round-trip
-- [ ] `ServerAppService::clone_server`:
+- [x] Migration: `cloned_from TEXT NULL` on `installed_servers`
+- [x] `InstalledServer.cloned_from` field + repo round-trip
+- [x] `ServerAppService::clone_server`:
   - Load source install + definition from `cached_definition`
   - Derive `new_id = "{base}-{suffix}"` using same normalization as `UserServerEntry::normalize_server_id`
   - Reject if `(space_id, new_id)` exists or source is missing
   - Patch definition `alias` to suffix (or user override)
   - Install via existing `install()` path with `ManualEntry` + `with_cloned_from(source_id)`
-- [ ] Unit tests: happy path, collision, missing source, suffix normalization (no underscores)
-- [ ] Tauri command `clone_server(space_id, source_server_id, suffix, alias?)`
+- [x] Unit tests: happy path, collision, missing source, suffix normalization (no underscores)
+- [x] Tauri command `clone_server(space_id, source_server_id, suffix, alias?)`
 
 **Outcome:** `clone_server` from Tauri creates a disabled `posthog-work` install with copied definition, empty creds, and `cloned_from = "posthog"`. Verifiable via `list_installed_servers` and SQLite inspection. No UI yet.
 
 ### Phase 2 — Clone wizard UI
 
 **Effort:** ~1 day
 
-- [ ] `CloneAccountModal` — suffix field with suggestions (`work`, `personal`, `prod`, `staging`), live alias preview, inline collision error
-- [ ] `ServerActionMenu` → "Add another account…" on registry and manual installs (not on clones)
-- [ ] Post-clone flow: open existing `ConfigEditorModal` for credential entry before enable
-- [ ] `SourceBadge` shows clone lineage
+- [x] `CloneAccountModal` — suffix field with suggestions (`work`, `personal`, `prod`, `staging`), live alias preview, inline collision error
+- [x] `ServerActionMenu` → "Add another account…" on registry and manual installs (not on clones)
+- [x] Post-clone flow: open existing `ConfigEditorModal` for credential entry before enable
+- [x] `SourceBadge` shows clone lineage
 - [ ] Optional: collapsed "Accounts" group on `ServersPage` when `cloned_from` matches same base (visual only, no schema)
 
 **Outcome:** User clicks "Add another account" on PostHog, enters suffix `work`, gets `posthog-work` card in My Servers, configures API key, enables — tools appear as `posthog-work_*` in gateway. No JSON editing.
@@ -192,9 +192,9 @@ Multi-account need?
 
 **Effort:** ~0.5 day
 
-- [ ] `mcpmux_list_servers` returns optional `cloned_from` for clone rows
-- [ ] `docs/guide/servers.mdx` section: "Multiple accounts" — decision tree (Spaces / native param / clone)
-- [ ] Migration doc update in `jsg-tech-check` with concrete clone targets (PostHog, Gmail, Sheets, Firebase)
+- [x] `mcpmux_list_servers` returns optional `cloned_from` for clone rows
+- [x] `docs/guide/servers.mdx` section: "Multiple accounts" — decision tree (Spaces / native param / clone)
+- [ ] Migration doc update in `jsg-tech-check` with concrete clone targets (PostHog, Gmail, Sheets, Firebase) — out of repo; deferred
 
 **Outcome:** LLM manifest shows clone lineage. Docs explain when to clone vs use a Space. Migration checklist has explicit suffix naming convention.
 

tests/rust/tests/integration/meta_tools.rs

@@ -12,8 +12,9 @@ use std::time::Duration;
 use futures::FutureExt;
 use mcpmux_core::{
     normalize_workspace_root, Client, DomainEvent, FeatureSet, FeatureSetMember,
-    FeatureSetRepository, InboundMcpClientRepository, MemberMode, MemberType, ServerFeature,
-    ServerFeatureRepository, SpaceRepository, WorkspaceBindingRepository,
+    FeatureSetRepository, InboundMcpClientRepository, InstalledServer, InstalledServerRepository,
+    MemberMode, MemberType, ServerFeature, ServerFeatureRepository, SpaceRepository,
+    WorkspaceBindingRepository,
 };
 use mcpmux_gateway::pool::FeatureService;
 use mcpmux_gateway::services::{
@@ -22,9 +23,9 @@ use mcpmux_gateway::services::{
     SessionRootsRegistry,
 };
 use mcpmux_storage::{
-    Database, InboundClientRepository, SqliteFeatureSetRepository,
-    SqliteInboundMcpClientRepository, SqliteServerFeatureRepository, SqliteSpaceRepository,
-    SqliteWorkspaceBindingRepository,
+    generate_master_key, Database, FieldEncryptor, InboundClientRepository,
+    SqliteFeatureSetRepository, SqliteInboundMcpClientRepository, SqliteInstalledServerRepository,
+    SqliteServerFeatureRepository, SqliteSpaceRepository, SqliteWorkspaceBindingRepository,
 };
 use serde_json::{json, Value};
 use tokio::sync::{broadcast, Mutex};
@@ -37,6 +38,7 @@ struct Fixture {
     client_repo: Arc<dyn InboundMcpClientRepository>,
     feature_set_repo: Arc<dyn FeatureSetRepository>,
     binding_repo: Arc<dyn WorkspaceBindingRepository>,
+    installed_server_repo: Arc<dyn InstalledServerRepository>,
     session_roots: Arc<SessionRootsRegistry>,
     session_overrides: Arc<SessionOverrideRegistry>,
     feature_service: Arc<FeatureService>,
@@ -50,6 +52,11 @@ struct Fixture {
     event_rx: broadcast::Receiver<DomainEvent>,
 }
 
+fn test_encryptor() -> Arc<FieldEncryptor> {
+    let key = generate_master_key().expect("generate key");
+    Arc::new(FieldEncryptor::new(&key).expect("create encryptor"))
+}
+
 impl Fixture {
     async fn new() -> Self {
         let db = Arc::new(Mutex::new(Database::open_in_memory().unwrap()));
@@ -63,6 +70,9 @@ impl Fixture {
             Arc::new(SqliteWorkspaceBindingRepository::new(db.clone()));
         let server_feature_repo: Arc<dyn ServerFeatureRepository> =
             Arc::new(SqliteServerFeatureRepository::new(db.clone()));
+        let installed_server_repo: Arc<dyn InstalledServerRepository> = Arc::new(
+            SqliteInstalledServerRepository::new(db.clone(), test_encryptor()),
+        );
 
         let default_space = space_repo.get_default().await.unwrap().unwrap();
         let space_id = default_space.id;
@@ -127,6 +137,7 @@ impl Fixture {
             feature_set_repo.clone(),
             binding_repo.clone(),
             server_feature_repo.clone(),
+            installed_server_repo.clone(),
             resolver,
             feature_service.clone(),
             session_roots.clone(),
@@ -142,6 +153,7 @@ impl Fixture {
             client_repo,
             feature_set_repo,
             binding_repo,
+            installed_server_repo,
             session_roots,
             session_overrides,
             feature_service,
@@ -353,6 +365,67 @@ async fn list_servers_shows_session_override_statuses() {
     assert_eq!(server_status(&body, "firebase"), "enabled_via_session");
 }
 
+#[tokio::test(flavor = "multi_thread")]
+async fn list_servers_includes_cloned_from_for_clone_installs() {
+    let f = Fixture::new().await;
+    let space_id = f.space_id.to_string();
+
+    let posthog = InstalledServer::new(&space_id, "posthog");
+    f.installed_server_repo
+        .install(&posthog)
+        .await
+        .unwrap();
+    let posthog_work = InstalledServer::new(&space_id, "posthog-work")
+        .with_cloned_from("posthog");
+    f.installed_server_repo
+        .install(&posthog_work)
+        .await
+        .unwrap();
+
+    let mut clone_tool = ServerFeature::tool(f.space_id, "posthog-work", "capture");
+    clone_tool.display_name = Some("PostHog (work)".into());
+    f.registry
+        .context()
+        .server_feature_repo
+        .upsert(&clone_tool)
+        .await
+        .unwrap();
+
+    let result = f
+        .registry
+        .call(
+            "mcpmux_list_servers",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({}),
+        )
+        .await
+        .unwrap();
+    let body = Fixture::result_json(&result);
+    let clone_entry = body
+        .get("servers")
+        .unwrap()
+        .as_array()
+        .unwrap()
+        .iter()
+        .find(|s| s.get("id").and_then(|v| v.as_str()) == Some("posthog-work"))
+        .expect("clone server in manifest");
+    assert_eq!(
+        clone_entry.get("cloned_from").and_then(|v| v.as_str()),
+        Some("posthog")
+    );
+
+    let github_entry = body
+        .get("servers")
+        .unwrap()
+        .as_array()
+        .unwrap()
+        .iter()
+        .find(|s| s.get("id").and_then(|v| v.as_str()) == Some("github"))
+        .expect("github in manifest");
+    assert!(github_entry.get("cloned_from").is_none());
+}
+
 #[tokio::test(flavor = "multi_thread")]
 async fn enable_server_adds_tools_on_next_list() {
     let f = Fixture::new().await;
@@ -774,6 +847,9 @@ async fn bare_registry(
         Arc::new(SqliteWorkspaceBindingRepository::new(db.clone()));
     let server_feature_repo: Arc<dyn ServerFeatureRepository> =
         Arc::new(SqliteServerFeatureRepository::new(db.clone()));
+    let installed_server_repo: Arc<dyn InstalledServerRepository> = Arc::new(
+        SqliteInstalledServerRepository::new(db.clone(), test_encryptor()),
+    );
 
     let _space = space_repo.get_default().await.unwrap().unwrap();
     let client = Client::new("c", "t");
@@ -801,6 +877,7 @@ async fn bare_registry(
         feature_set_repo,
         binding_repo,
         server_feature_repo,
+        installed_server_repo,
         resolver,
         feature_service,
         SessionRootsRegistry::new(),
@@ -894,6 +971,9 @@ async fn master_switch_toggles_registry_visibility() {
         Arc::new(SqliteWorkspaceBindingRepository::new(db.clone()));
     let server_feature_repo: Arc<dyn ServerFeatureRepository> =
         Arc::new(SqliteServerFeatureRepository::new(db.clone()));
+    let installed_server_repo: Arc<dyn InstalledServerRepository> = Arc::new(
+        SqliteInstalledServerRepository::new(db.clone(), test_encryptor()),
+    );
     let inbound_client_repo = Arc::new(InboundClientRepository::new(db.clone()));
     let resolver = Arc::new(FeatureSetResolverService::new(
         space_repo.clone(),
@@ -915,6 +995,7 @@ async fn master_switch_toggles_registry_visibility() {
         feature_set_repo,
         binding_repo,
         server_feature_repo,
+        installed_server_repo,
         resolver,
         feature_service,
         SessionRootsRegistry::new(),