feat(meta-tools): target any Space via space_id + add mcpmux_list_spaces

Make the self-management surface flexible: a client can now inspect and
configure any Space it can discover, with user approval as the gate.

- New read tool `mcpmux_list_spaces` → [{id, name, is_default, description}]
  so the LLM can discover valid space ids.
- Optional `space_id` on every tool (list_all_tools, search_tools,
  list_feature_sets, manage_feature_set, bind_current_workspace). Omitted ⇒
  the caller''s resolved Space (back-compatible); provided ⇒ that Space
  (validated to exist). bind can now route a workspace into a *different* Space.
- Approval payload carries `space_name`; every write summary names the target
  Space so a cross-Space change is a conscious approval, not a surprise.
- Reads stay silent (local-trust); writes still prompt.

Advertise a trigger language so the LLM isolates McpMux requests from the
user''s actual work: the server `instructions` now teach the `@mux` convention
and that `mcpmux_*` are McpMux controls, not task tools. Built-in descriptor
lists mcpmux_list_spaces.

Tests: list_spaces, unknown-space rejection, cross-Space create + bind land in
the targeted Space (not the caller''s), updated advertise + parity guards.

Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

Author: its-mash

crates/mcpmux-core/src/domain/builtin.rs

@@ -56,9 +56,14 @@ pub fn builtin_servers() -> Vec<BuiltinServerDescriptor> {
                       each with your approval. Reads are silent; writes need approval.",
         default_enabled: true,
         tools: vec![
+            BuiltinToolDescriptor {
+                name: "mcpmux_list_spaces",
+                description: "List all Spaces so the AI can target one by id.",
+                write: false,
+            },
             BuiltinToolDescriptor {
                 name: "mcpmux_list_all_tools",
-                description: "Browse every tool available in the resolved Space, unfiltered.",
+                description: "Browse every tool available in a Space, unfiltered.",
                 write: false,
             },
             BuiltinToolDescriptor {

crates/mcpmux-gateway/src/mcp/handler.rs

@@ -354,7 +354,21 @@ impl ServerHandler for McpMuxGatewayHandler {
         info.server_info = server_info;
         info.instructions = Some(
             "McpMux aggregates multiple MCP servers. Use tools/prompts/resources \
-             from your authorized backend servers."
+             from your authorized backend servers to do the user's work.\n\n\
+             The `mcpmux_*` tools are different: they are McpMux's own \
+             self-management / tool-optimization controls, NOT tools for the \
+             user's task. Use them ONLY when the user is explicitly managing \
+             their McpMux setup — discovering available tools, composing or \
+             editing FeatureSets, listing Spaces, or routing (binding) a \
+             workspace to a FeatureSet. The trigger word is `@mux`: when a user \
+             message contains `@mux` (e.g. \"@mux build a minimal toolset for \
+             this repo\"), treat it as a McpMux tool-optimization request and use \
+             the `mcpmux_*` tools to fulfill it. Otherwise do not call them. \
+             Reads (mcpmux_list_spaces / list_all_tools / search_tools / \
+             list_feature_sets) are safe to call freely once the user has opted \
+             in; writes (manage_feature_set, bind_current_workspace) prompt the \
+             user for approval. Most operations accept an optional `space_id` \
+             (from mcpmux_list_spaces) to target a specific Space."
                 .to_string(),
         );
         info

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

@@ -73,6 +73,12 @@ pub struct ApprovalPayload {
     /// Human summary the dialog puts above the diff. e.g.
     /// "Pin this connection to FeatureSet 'android-dev' (12 tools)".
     pub summary: String,
+    /// Name of the Space this write targets, surfaced as a labeled chip so the
+    /// user can see (and reject) a change aimed at a Space other than the one
+    /// they expect — important now that a client may pass any `space_id`.
+    /// `None` for writes with no single target Space.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub space_name: Option<String>,
     /// Tool-list diff the dialog shows to make the change concrete.
     /// Optional because some writes (e.g. create_feature_set without
     /// activation) don't shift the caller's resolved toolset.
@@ -350,6 +356,7 @@ mod tests {
         ApprovalPayload {
             tool_name: "mcpmux_pin_this_session".into(),
             summary: "test".into(),
+            space_name: None,
             diff: None,
             raw_args: serde_json::json!({}),
             affects_other_clients: false,

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

@@ -77,6 +77,7 @@ pub fn build_default_registry(
 
     let mut registry = MetaToolRegistry::new(ctx);
     // Reads — no approval needed.
+    registry.register(Box::new(tools::ListSpacesTool));
     registry.register(Box::new(tools::ListAllToolsTool));
     registry.register(Box::new(tools::SearchToolsTool));
     registry.register(Box::new(tools::ListFeatureSetsTool));