feat(meta-tools): add mcpmux_list_servers read tool (Phase 2)

Server-level manifest with binding/session status per installed server.

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

Author: crimsonsunset

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

@@ -134,6 +134,7 @@ impl ServiceContainer {
             feature_set_resolver.clone(),
             pool_services.feature_service.clone(),
             session_roots.clone(),
+            session_overrides.clone(),
             approval_broker.clone(),
             domain_event_tx.clone(),
             deps.settings_repo.clone(),

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

@@ -55,6 +55,7 @@ pub fn build_default_registry(
     resolver: std::sync::Arc<crate::services::FeatureSetResolverService>,
     feature_service: std::sync::Arc<crate::pool::FeatureService>,
     session_roots: std::sync::Arc<crate::services::SessionRootsRegistry>,
+    session_overrides: std::sync::Arc<crate::services::SessionOverrideRegistry>,
     approval_broker: std::sync::Arc<ApprovalBroker>,
     domain_event_tx: tokio::sync::broadcast::Sender<mcpmux_core::DomainEvent>,
     settings_repo: Option<std::sync::Arc<dyn mcpmux_core::AppSettingsRepository>>,
@@ -68,6 +69,7 @@ pub fn build_default_registry(
         resolver,
         feature_service,
         session_roots,
+        session_overrides,
         approval_broker,
         domain_event_tx,
         settings_repo,
@@ -77,6 +79,7 @@ pub fn build_default_registry(
     // Reads — no approval needed.
     registry.register(Box::new(tools::ListAllToolsTool));
     registry.register(Box::new(tools::ListFeatureSetsTool));
+    registry.register(Box::new(tools::ListServersTool));
     // Both `describe_resolution` and `describe_workspace` were removed by
     // user request — the read surface is just the two list_* tools above,
     // which an LLM can stitch into the same picture without an extra hop.

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

@@ -19,7 +19,9 @@ use tokio::sync::broadcast;
 
 use super::approval::ApprovalBroker;
 use crate::pool::FeatureService;
-use crate::services::{FeatureSetResolverService, SessionRootsRegistry};
+use crate::services::{
+    FeatureSetResolverService, SessionOverrideRegistry, SessionRootsRegistry,
+};
 
 /// App-settings key that toggles the entire `mcpmux_*` namespace.
 /// Present + "false" → hidden; missing or anything else → enabled.
@@ -39,6 +41,7 @@ pub struct MetaToolContext {
     pub resolver: Arc<FeatureSetResolverService>,
     pub feature_service: Arc<FeatureService>,
     pub session_roots: Arc<SessionRootsRegistry>,
+    pub session_overrides: Arc<SessionOverrideRegistry>,
     pub approval_broker: Arc<ApprovalBroker>,
     /// Broadcast domain events (e.g. ToolsChanged) so MCPNotifier can push
     /// `tools/list_changed` to connected peers after a write mutates state.

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

@@ -9,12 +9,14 @@ use mcpmux_core::{
 };
 use rmcp::model::{CallToolResult, Content};
 use serde_json::{json, Value};
+use std::collections::{HashMap, HashSet};
 use tokio::sync::broadcast;
 use tracing::info;
 use uuid::Uuid;
 
 use super::approval::{ApprovalPayload, ApprovalScope};
 use super::registry::{MetaTool, MetaToolCall, MetaToolError};
+use crate::services::ResolvedFeatureSet;
 
 /// Fire a `FeatureSetMembersChanged` event so MCPNotifier pushes a
 /// `tools/list_changed` notification to every connected client in the Space.
@@ -64,6 +66,33 @@ async fn caller_space_id(call: &MetaToolCall<'_>) -> Result<Uuid, MetaToolError>
     ))
 }
 
+/// Full resolver output for the caller — space + binding FS ids + source.
+async fn caller_resolution(call: &MetaToolCall<'_>) -> Result<ResolvedFeatureSet, MetaToolError> {
+    call.ctx
+        .resolver
+        .resolve(call.session_id, Some(call.client_id))
+        .await
+        .map_err(|e| MetaToolError::Internal(e.to_string()))
+}
+
+/// Derive the manifest status for one server in the caller's session.
+fn derive_server_status(
+    server_id: &str,
+    binding_servers: &HashSet<String>,
+    session_enabled: &HashSet<String>,
+    session_disabled: &HashSet<String>,
+) -> &'static str {
+    if session_disabled.contains(server_id) {
+        "disabled_via_session"
+    } else if session_enabled.contains(server_id) && !binding_servers.contains(server_id) {
+        "enabled_via_session"
+    } else if binding_servers.contains(server_id) {
+        "enabled_via_binding"
+    } else {
+        "inactive"
+    }
+}
+
 // ---------------------------------------------------------------------------
 // mcpmux_list_all_tools — read
 // ---------------------------------------------------------------------------
@@ -165,6 +194,103 @@ impl MetaTool for ListFeatureSetsTool {
     }
 }
 
+// ---------------------------------------------------------------------------
+// mcpmux_list_servers — read
+// ---------------------------------------------------------------------------
+
+pub struct ListServersTool;
+
+#[async_trait]
+impl MetaTool for ListServersTool {
+    fn name(&self) -> &'static str {
+        "mcpmux_list_servers"
+    }
+
+    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 \
+         current routing state without loading every tool."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({ "type": "object", "properties": {} })
+    }
+
+    async fn call(&self, call: MetaToolCall<'_>) -> Result<CallToolResult, MetaToolError> {
+        let resolved = caller_resolution(&call).await?;
+        let space_id = resolved
+            .space_id
+            .ok_or_else(|| MetaToolError::Internal("space missing".into()))?;
+
+        let binding_features = call
+            .ctx
+            .feature_service
+            .resolve_feature_sets(&space_id.to_string(), &resolved.feature_set_ids)
+            .await?;
+        let binding_servers: HashSet<String> = binding_features
+            .iter()
+            .map(|f| f.server_id.clone())
+            .collect();
+
+        let session_enabled = call
+            .session_id
+            .map(|sid| call.ctx.session_overrides.enabled_set(sid))
+            .unwrap_or_default();
+        let session_disabled = call
+            .session_id
+            .map(|sid| call.ctx.session_overrides.disabled_set(sid))
+            .unwrap_or_default();
+
+        let features = call
+            .ctx
+            .server_feature_repo
+            .list_for_space(&space_id.to_string())
+            .await?;
+
+        let mut by_server: HashMap<String, (Option<String>, usize)> = HashMap::new();
+        for feature in &features {
+            if feature.feature_type != FeatureType::Tool {
+                continue;
+            }
+            let entry = by_server
+                .entry(feature.server_id.clone())
+                .or_insert((None, 0));
+            if entry.0.is_none() {
+                entry.0 = feature.display_name.clone();
+            }
+            entry.1 += 1;
+        }
+
+        let mut servers: Vec<Value> = by_server
+            .into_iter()
+            .map(|(id, (display_name, tool_count))| {
+                let name = display_name.unwrap_or_else(|| id.clone());
+                let status = derive_server_status(
+                    &id,
+                    &binding_servers,
+                    &session_enabled,
+                    &session_disabled,
+                );
+                json!({
+                    "id": id,
+                    "name": name,
+                    "tool_count": tool_count,
+                    "status": status,
+                })
+            })
+            .collect();
+        servers.sort_by(|a, b| {
+            a.get("id")
+                .and_then(|v| v.as_str())
+                .unwrap_or("")
+                .cmp(b.get("id").and_then(|v| v.as_str()).unwrap_or(""))
+        });
+
+        Ok(text_result(json!({ "servers": servers })))
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Writes — each goes through the ApprovalBroker before mutating state.
 // ---------------------------------------------------------------------------

docs/planning/dynamic-mcp-toggle-meta-tools.md

@@ -1,7 +1,7 @@
 # Dynamic MCP Toggling via Meta Tools
 
 **Last Updated:** May 19, 2026
-**Status:** Phase 1 complete — SessionOverrideRegistry + list-path composition wired; Phases 2–5 pending
+**Status:** Phase 2 complete — `mcpmux_list_servers` read tool shipped; Phases 3–5 pending
 **Branch:** `feat/dynamic-mcp-toggle-meta-tools`
 **Base branch:** `feat/workspace-root-routing` ([upstream PR #151](https://github.com/mcpmux/mcp-mux/pull/151))
 **Issue:** TBD — file after planning review
@@ -187,17 +187,18 @@ Each write fires `tools/list_changed` per-peer via the existing `MCPNotifier::no
 - Server-level composition loads **all available** features for each effective `server_id` (not FS-partial tool subsets).
 - Fixed pre-existing DashMap deadlock in `SessionRootsRegistry::record_resolution` (`get` guard must not overlap `insert` on the same map).
 
-### Phase 2 — `mcpmux_list_servers` read tool
+### Phase 2 — `mcpmux_list_servers` read tool ✅
 
-**Effort:** 1 evening
+**Effort:** 1 evening  
+**Completed:** May 19, 2026
 
-- Add `ListServersTool` unit struct + `MetaTool` impl in `meta_tools/tools.rs`.
-- Implementation: load `ServerFeature::list_for_space(caller_space_id)`, group by `server_id`, compute `tool_count = features.iter().filter(|f| f.feature_type == Tool).count()`, derive `status` per server by checking `binding`, `session_overrides.enabled`, `session_overrides.disabled` in order.
-- JSON schema: empty `properties` (no args).
-- Register in `build_default_registry` alongside the existing reads.
-- Integration test: connect a fake session, call `mcpmux_list_servers`, assert response shape includes `status` enum values for both bound and unbound servers.
+- [x] `ListServersTool` in `meta_tools/tools.rs` — groups `ServerFeature::list_for_space` by `server_id`, counts tools, derives status
+- [x] Status enum: `enabled_via_binding | enabled_via_session | disabled_via_session | inactive` (binding → session-enabled → session-disabled priority)
+- [x] `SessionOverrideRegistry` plumbed into `MetaToolContext` for status derivation
+- [x] Registered in `build_default_registry`
+- [x] Integration tests: inactive (no binding), `enabled_via_binding`, session override statuses
 
-**Outcome:** An LLM calling `mcpmux_list_servers` from any session receives a server roster like `[{id: "github", name: "GitHub", tool_count: 24, status: "enabled_via_binding"}, {id: "firebase", name: "Firebase", tool_count: 18, status: "inactive"}, ...]`. No state mutation yet.
+**Outcome:** LLM calls `mcpmux_list_servers` and gets a server roster with per-server status. No state mutation.
 
 ### Phase 3 — `mcpmux_enable_server` / `mcpmux_disable_server` (session scope)
 

tests/rust/tests/integration/meta_tools.rs

@@ -129,6 +129,7 @@ impl Fixture {
             resolver,
             feature_service.clone(),
             session_roots.clone(),
+            session_overrides.clone(),
             broker.clone(),
             tx,
             None,
@@ -260,6 +261,100 @@ async fn list_feature_sets_returns_space_contents() {
     assert_eq!(sets.len(), 3, "Default + 2 custom expected");
 }
 
+fn server_status(body: &Value, server_id: &str) -> String {
+    body.get("servers")
+        .unwrap()
+        .as_array()
+        .unwrap()
+        .iter()
+        .find(|s| s.get("id").and_then(|v| v.as_str()) == Some(server_id))
+        .unwrap()
+        .get("status")
+        .unwrap()
+        .as_str()
+        .unwrap()
+        .to_string()
+}
+
+async fn bind_github_only_to_session_root(f: &Fixture) -> String {
+    use mcpmux_core::WorkspaceBinding;
+
+    let fs_id = github_only_fs(f).await;
+    let root = "/tmp/mcpmux-list-servers-test";
+    f.session_roots.set_roots_capable(&f.session_id, true);
+    f.session_roots.set(&f.session_id, [root]);
+    let binding = WorkspaceBinding::new(
+        normalize_workspace_root(root),
+        f.space_id,
+        fs_id.clone(),
+    );
+    f.binding_repo.create(&binding).await.unwrap();
+    fs_id
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn list_servers_marks_unbound_servers_inactive() {
+    let f = Fixture::new().await;
+    let result = f
+        .registry
+        .call(
+            "mcpmux_list_servers",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({}),
+        )
+        .await
+        .unwrap();
+    assert!(!Fixture::is_error(&result));
+    let body = Fixture::result_json(&result);
+    let servers = body.get("servers").unwrap().as_array().unwrap();
+    assert_eq!(servers.len(), 2);
+    assert_eq!(server_status(&body, "github"), "inactive");
+    assert_eq!(server_status(&body, "firebase"), "inactive");
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn list_servers_shows_enabled_via_binding() {
+    let f = Fixture::new().await;
+    bind_github_only_to_session_root(&f).await;
+
+    let result = f
+        .registry
+        .call(
+            "mcpmux_list_servers",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({}),
+        )
+        .await
+        .unwrap();
+    let body = Fixture::result_json(&result);
+    assert_eq!(server_status(&body, "github"), "enabled_via_binding");
+    assert_eq!(server_status(&body, "firebase"), "inactive");
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn list_servers_shows_session_override_statuses() {
+    let f = Fixture::new().await;
+    bind_github_only_to_session_root(&f).await;
+    f.session_overrides.enable(&f.session_id, "firebase");
+    f.session_overrides.disable(&f.session_id, "github");
+
+    let result = f
+        .registry
+        .call(
+            "mcpmux_list_servers",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({}),
+        )
+        .await
+        .unwrap();
+    let body = Fixture::result_json(&result);
+    assert_eq!(server_status(&body, "github"), "disabled_via_session");
+    assert_eq!(server_status(&body, "firebase"), "enabled_via_session");
+}
+
 // `describe_resolution` and `describe_workspace` were both removed at the
 // user's request — the read surface is now just `list_all_tools` and
 // `list_feature_sets`. Behavior previously asserted here is covered by
@@ -448,6 +543,7 @@ async fn registry_advertises_every_default_tool_with_annotations() {
     for expected in [
         "mcpmux_list_all_tools",
         "mcpmux_list_feature_sets",
+        "mcpmux_list_servers",
         "mcpmux_create_feature_set",
         "mcpmux_bind_current_workspace",
     ] {
@@ -525,6 +621,7 @@ async fn bare_registry(
         resolver,
         feature_service,
         SessionRootsRegistry::new(),
+        SessionOverrideRegistry::new(),
         Arc::new(ApprovalBroker::new()),
         tx.clone(),
         settings_repo,
@@ -638,6 +735,7 @@ async fn master_switch_toggles_registry_visibility() {
         resolver,
         feature_service,
         SessionRootsRegistry::new(),
+        SessionOverrideRegistry::new(),
         Arc::new(ApprovalBroker::new()),
         tx,
         Some(settings_repo.clone()),