MCP: Auto-probe port and fix port display

vdavid · vdavid · commit d69f87617950 · 2026-03-18T13:19:25.000+01:00
- Unify default MCP port to 9224 for all builds (was 9225 for debug, 9224 for release)
- Auto-probe to next available port if configured port is in use (scans up to 100 ports)
- Store actual bound port in `MCP_ACTUAL_PORT` static, exposed via `get_mcp_port` command
- Frontend `syncState()` fetches actual port from backend instead of trusting the setting value
- Show "(port X was in use)" in Settings UI when the server auto-probed to a different port
- Update MCP CLAUDE.md: document auto-probing, clarify that tool/resource output is for LLMs not parsers
diff --git a/apps/desktop/src-tauri/src/commands/mcp.rs b/apps/desktop/src-tauri/src/commands/mcp.rs
@@ -35,3 +35,9 @@ pub async fn set_mcp_port<R: Runtime + 'static>(app: AppHandle<R>, port: u16) ->
 pub fn get_mcp_running() -> bool {
     mcp::is_mcp_running()
 }
+
+/// Returns the port the MCP server is actually listening on, or null if not running.
+#[tauri::command]
+pub fn get_mcp_port() -> Option<u16> {
+    mcp::get_mcp_actual_port()
+}
diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
@@ -861,6 +861,7 @@ pub fn run() {
             commands::mcp::set_mcp_enabled,
             commands::mcp::set_mcp_port,
             commands::mcp::get_mcp_running,
+            commands::mcp::get_mcp_port,
             // Settings commands
             commands::settings::check_port_available,
             commands::settings::find_available_port,
diff --git a/apps/desktop/src-tauri/src/mcp/CLAUDE.md b/apps/desktop/src-tauri/src/mcp/CLAUDE.md
@@ -9,7 +9,7 @@ Expose Cmdr functionality to AI agents via the Model Context Protocol (MCP). Age
 ### Server (`server.rs`)
 
 - Runs in a background tokio task spawned at app startup
-- Binds to `127.0.0.1:9225` in dev, `127.0.0.1:9224` in release (localhost only for security)
+- Binds to `127.0.0.1:9224` by default (localhost only for security). If the port is taken, auto-probes upward (up to 100 ports) to find an available one
 - Streamable HTTP transport (MCP spec 2025-11-25)
 - Endpoints: `POST /mcp` (JSON-RPC), `GET /mcp` (optional SSE), `GET /mcp/health`
 
@@ -43,7 +43,7 @@ Routes tool calls to implementations. Most tools emit Tauri events that trigger
 
 ### Configuration (`config.rs`)
 
-Constants and configuration for the MCP server (port, bind address, transport settings).
+Constants and configuration for the MCP server (port, bind address, transport settings). Default port is 9224 for all build types (dev and prod use separate data dirs, so no collision risk).
 
 ### Dialog state (`dialog_state.rs`)
 
@@ -69,7 +69,7 @@ LLMs consume resources, not machines. YAML is 30-40% smaller and more readable.
 
 ### Why plain text responses?
 
-Tool results are plain text (`"OK: Navigated to /Users"`, `"ERROR: Path not found"`), not JSON objects. This reduces token usage and is easier for LLMs to parse. Errors are still JSON-RPC error objects, but the `content` field is plain text.
+Tool results and resource content are consumed by LLMs, not parsed by code. Output doesn't need to be JSON, YAML, or any structured format — anything that reads well to a human and is concise works. Tool results are plain text (`"OK: Navigated to /Users"`, aligned columns for search results), resources use YAML or plain text. Errors are still JSON-RPC error objects, but the `content` field is plain text. Optimize for readability and token efficiency, not parseability.
 
 ### Why stateful architecture?
 
@@ -91,7 +91,7 @@ Binding to `0.0.0.0` would expose the server to the network. An attacker could q
 
 ### Server lifecycle is managed at runtime
 
-`start_mcp_server()` binds the port and spawns a tokio task, storing the `JoinHandle` in a static `MCP_HANDLE`. The server can be started/stopped live via `set_mcp_enabled` and `set_mcp_port` Tauri commands — no app restart needed. `stop_mcp_server()` aborts the task (instant). `is_mcp_running()` checks whether the handle exists. At startup, `start_mcp_server_background()` wraps the async start in a fire-and-forget spawn. If the server crashes, the app continues but MCP stops working. Check logs for "MCP server crashed" errors.
+`start_mcp_server()` binds the port and spawns a tokio task, storing the `JoinHandle` in a static `MCP_HANDLE`. If the configured port is taken, it auto-probes upward (up to 100 ports) and stores the actual bound port in `MCP_ACTUAL_PORT`. The frontend queries this via `get_mcp_port()` and shows a notice when it differs from the configured port. The server can be started/stopped live via `set_mcp_enabled` and `set_mcp_port` Tauri commands — no app restart needed. `stop_mcp_server()` aborts the task and resets `MCP_ACTUAL_PORT` to 0. `is_mcp_running()` checks whether the handle exists. At startup, `start_mcp_server_background()` wraps the async start in a fire-and-forget spawn. If the server crashes, the app continues but MCP stops working. Check logs for "MCP server crashed" errors.
 
 ### Live MCP control only works from the settings window
 
diff --git a/apps/desktop/src-tauri/src/mcp/config.rs b/apps/desktop/src-tauri/src/mcp/config.rs
@@ -36,13 +36,12 @@ impl McpConfig {
         // Priority for port:
         // 1. CMDR_MCP_PORT env var (explicit dev override)
         // 2. User setting (developer.mcpPort)
-        // 3. Default: 9225 in debug builds, 9224 in release
-        let default_port: u16 = if cfg!(debug_assertions) { 9225 } else { 9224 };
+        // 3. Default: 9224 (same for all build types — dev and prod use separate data dirs)
         let port = env::var("CMDR_MCP_PORT")
             .ok()
             .and_then(|v| v.parse().ok())
             .or(setting_port)
-            .unwrap_or(default_port);
+            .unwrap_or(9224);
 
         Self { enabled, port }
     }
@@ -85,10 +84,7 @@ mod tests {
     fn test_from_settings_with_no_settings() {
         // When no settings are provided, should use defaults
         let config = McpConfig::from_settings_and_env(None, None);
-        // Debug builds use port 9225 to avoid clashing with a running release build
-        #[cfg(debug_assertions)]
-        assert_eq!(config.port, 9225);
-        #[cfg(not(debug_assertions))]
+        // Default port is always 9224 regardless of build type
         assert_eq!(config.port, 9224);
         // In debug builds, enabled is true by default
         #[cfg(debug_assertions)]
diff --git a/apps/desktop/src-tauri/src/mcp/executor.rs b/apps/desktop/src-tauri/src/mcp/executor.rs
@@ -669,11 +669,11 @@ fn execute_dialog_close<R: Runtime>(app: &AppHandle<R>, dialog_type: &str, path:
 
 // ── Search tools ──────────────────────────────────────────────────────
 
+use crate::indexing::search::PatternType;
 use crate::indexing::search::{
-    self, DIALOG_OPEN, SEARCH_INDEX, SearchIndexState, SearchQuery, SearchResult,
-    fill_directory_sizes, format_size, format_timestamp, summarize_query,
+    self, DIALOG_OPEN, SEARCH_INDEX, SearchIndexState, SearchQuery, SearchResult, fill_directory_sizes, format_size,
+    format_timestamp, summarize_query,
 };
-use crate::indexing::search::PatternType;
 
 /// Ensure the search index is loaded. Returns the index or an error.
 async fn ensure_search_index() -> Result<Arc<search::SearchIndex>, ToolError> {
@@ -741,13 +741,17 @@ fn parse_human_size(s: &str) -> Result<u64, ToolError> {
     } else {
         // Try parsing as pure number (bytes)
         let n: u64 = s.trim().parse().map_err(|_| {
-            ToolError::invalid_params(format!("Couldn't parse size: \"{s}\". Use a format like \"1 MB\" or \"500 KB\"."))
+            ToolError::invalid_params(format!(
+                "Couldn't parse size: \"{s}\". Use a format like \"1 MB\" or \"500 KB\"."
+            ))
         })?;
         return Ok(n);
     };
 
     let num: f64 = num_str.trim().parse().map_err(|_| {
-        ToolError::invalid_params(format!("Couldn't parse size: \"{s}\". Use a format like \"1 MB\" or \"500 KB\"."))
+        ToolError::invalid_params(format!(
+            "Couldn't parse size: \"{s}\". Use a format like \"1 MB\" or \"500 KB\"."
+        ))
     })?;
 
     let multiplier: u64 = match unit {
@@ -772,14 +776,19 @@ fn format_search_results(result: &SearchResult, limit: u32) -> String {
     let entries = &result.entries[..shown];
 
     // Compute column widths
-    let max_name = entries.iter().map(|e| {
-        let display_name = if e.is_directory {
-            format!("{}/", e.name)
-        } else {
-            e.name.clone()
-        };
-        display_name.len()
-    }).max().unwrap_or(0).max(4);
+    let max_name = entries
+        .iter()
+        .map(|e| {
+            let display_name = if e.is_directory {
+                format!("{}/", e.name)
+            } else {
+                e.name.clone()
+            };
+            display_name.len()
+        })
+        .max()
+        .unwrap_or(0)
+        .max(4);
 
     let max_parent = entries.iter().map(|e| e.parent_path.len()).max().unwrap_or(0).max(4);
 
@@ -818,18 +827,14 @@ fn format_search_results(result: &SearchResult, limit: u32) -> String {
 }
 
 /// Run search and post-process (fill dir sizes, post-filter, truncate).
-fn run_search_and_postprocess(
-    index: &search::SearchIndex,
-    query: &SearchQuery,
-) -> Result<SearchResult, ToolError> {
-    let mut result = search::search(index, query).map_err(|e| ToolError::internal(e))?;
+fn run_search_and_postprocess(index: &search::SearchIndex, query: &SearchQuery) -> Result<SearchResult, ToolError> {
+    let mut result = search::search(index, query).map_err(ToolError::internal)?;
 
     // Fill directory sizes from the DB
-    if result.entries.iter().any(|e| e.is_directory) {
-        if let Some(pool) = crate::indexing::get_read_pool() {
+    if result.entries.iter().any(|e| e.is_directory)
+        && let Some(pool) = crate::indexing::get_read_pool() {
             fill_directory_sizes(&mut result, &pool);
         }
-    }
 
     // Post-filter: remove directories that don't match size criteria
     let has_size_filter = query.min_size.is_some() || query.max_size.is_some();
@@ -886,13 +891,13 @@ async fn execute_search(params: &Value) -> ToolResult {
         .and_then(|v| v.as_str())
         .map(crate::commands::search::iso_date_to_timestamp)
         .transpose()
-        .map_err(|e| ToolError::invalid_params(e))?;
+        .map_err(ToolError::invalid_params)?;
     let modified_before = params
         .get("modified_before")
         .and_then(|v| v.as_str())
         .map(crate::commands::search::iso_date_to_timestamp)
         .transpose()
-        .map_err(|e| ToolError::invalid_params(e))?;
+        .map_err(ToolError::invalid_params)?;
     let is_directory = match params.get("type").and_then(|v| v.as_str()) {
         Some("file") => Some(false),
         Some("dir") => Some(true),
@@ -941,9 +946,8 @@ async fn execute_ai_search(params: &Value) -> ToolResult {
             ));
         }
         "local" => {
-            let port = crate::ai::manager::get_port().ok_or_else(|| {
-                ToolError::internal("Local AI server isn't running. Start it in settings.")
-            })?;
+            let port = crate::ai::manager::get_port()
+                .ok_or_else(|| ToolError::internal("Local AI server isn't running. Start it in settings."))?;
             crate::ai::client::AiBackend::Local { port }
         }
         "openai-compatible" => {
@@ -973,8 +977,7 @@ async fn execute_ai_search(params: &Value) -> ToolResult {
         .await
         .map_err(|e| ToolError::internal(format!("{e}")))?;
 
-    let mut ai_query = crate::commands::search::parse_ai_response(&response)
-        .map_err(|e| ToolError::internal(e))?;
+    let mut ai_query = crate::commands::search::parse_ai_response(&response).map_err(ToolError::internal)?;
 
     // Validate regex patterns — retry once if invalid
     if let Err(regex_error) = crate::commands::search::validate_regex_pattern(&ai_query) {
@@ -989,8 +992,7 @@ async fn execute_ai_search(params: &Value) -> ToolResult {
             .await
             .map_err(|e| ToolError::internal(format!("{e}")))?;
 
-        ai_query = crate::commands::search::parse_ai_response(&retry_response)
-            .map_err(|e| ToolError::internal(e))?;
+        ai_query = crate::commands::search::parse_ai_response(&retry_response).map_err(ToolError::internal)?;
 
         if let Err(retry_error) = crate::commands::search::validate_regex_pattern(&ai_query) {
             return Err(ToolError::internal(format!(
@@ -999,8 +1001,8 @@ async fn execute_ai_search(params: &Value) -> ToolResult {
         }
     }
 
-    let translate_result = crate::commands::search::build_translate_result(ai_query)
-        .map_err(|e| ToolError::internal(e))?;
+    let translate_result =
+        crate::commands::search::build_translate_result(ai_query).map_err(ToolError::internal)?;
 
     let query = SearchQuery {
         name_pattern: translate_result.query.name_pattern,
diff --git a/apps/desktop/src-tauri/src/mcp/mod.rs b/apps/desktop/src-tauri/src/mcp/mod.rs
@@ -19,5 +19,5 @@ mod tests;
 pub use config::McpConfig;
 pub use dialog_state::SoftDialogTracker;
 pub use pane_state::PaneStateStore;
-pub use server::{is_mcp_running, start_mcp_server, start_mcp_server_background, stop_mcp_server};
+pub use server::{get_mcp_actual_port, is_mcp_running, start_mcp_server, start_mcp_server_background, stop_mcp_server};
 pub use settings_state::SettingsStateStore;
diff --git a/apps/desktop/src-tauri/src/mcp/server.rs b/apps/desktop/src-tauri/src/mcp/server.rs
@@ -17,6 +17,7 @@ use futures_util::stream;
 use serde_json::{Value, json};
 use std::convert::Infallible;
 use std::net::SocketAddr;
+use std::sync::atomic::{AtomicU16, Ordering};
 use std::sync::{Arc, Mutex, RwLock};
 use tauri::async_runtime::JoinHandle;
 use tauri::{AppHandle, Runtime};
@@ -32,6 +33,9 @@ use super::tools::get_all_tools;
 /// Handle to the running MCP server task, if any.
 static MCP_HANDLE: Mutex<Option<JoinHandle<()>>> = Mutex::new(None);
 
+/// The port the server is actually listening on (0 when not running).
+static MCP_ACTUAL_PORT: AtomicU16 = AtomicU16::new(0);
+
 /// The current MCP protocol version we support.
 pub const PROTOCOL_VERSION: &str = "2025-11-25";
 
@@ -57,8 +61,19 @@ impl<R: Runtime> McpState<R> {
     }
 }
 
+/// Find an available port starting from `start_port`, scanning up to 100 ports.
+fn find_available_port(start_port: u16) -> Option<u16> {
+    for offset in 0..100 {
+        let port = start_port.saturating_add(offset);
+        if std::net::TcpListener::bind(("127.0.0.1", port)).is_ok() {
+            return Some(port);
+        }
+    }
+    None
+}
+
 /// Start the MCP server. Binds to the configured port and spawns the server task.
-/// Returns an error if the port is already in use or binding fails.
+/// If the configured port is taken, auto-probes upward to find the next available port.
 pub async fn start_mcp_server<R: Runtime + 'static>(app: AppHandle<R>, config: McpConfig) -> Result<(), String> {
     if !config.enabled {
         log::info!("MCP server is disabled");
@@ -71,7 +86,19 @@ pub async fn start_mcp_server<R: Runtime + 'static>(app: AppHandle<R>, config: M
         return Ok(());
     }
 
-    let port = config.port;
+    let configured_port = config.port;
+
+    // Auto-probe: if the configured port is taken, find the next available one
+    let port = find_available_port(configured_port)
+        .ok_or_else(|| format!("No available port found starting from {}.", configured_port))?;
+    if port != configured_port {
+        log::info!(
+            "MCP server: port {} is in use, using port {} instead",
+            configured_port,
+            port
+        );
+    }
+
     let state = Arc::new(McpState::new(app));
 
     let cors = CorsLayer::new().allow_origin(Any).allow_methods(Any).allow_headers(Any);
@@ -87,16 +114,14 @@ pub async fn start_mcp_server<R: Runtime + 'static>(app: AppHandle<R>, config: M
     log::debug!("MCP server attempting to bind on http://{}", addr);
 
     // Bind before spawning so we can report errors synchronously
-    let listener = tokio::net::TcpListener::bind(addr).await.map_err(|e| {
-        if e.kind() == std::io::ErrorKind::AddrInUse {
-            format!("Port {} is already in use. Try a different port?", port)
-        } else {
-            format!("Couldn't start the server on port {}. {}", port, e)
-        }
-    })?;
+    let listener = tokio::net::TcpListener::bind(addr)
+        .await
+        .map_err(|e| format!("Couldn't start the server on port {}. {}", port, e))?;
 
     log::info!("MCP server listening on http://{}", addr);
 
+    MCP_ACTUAL_PORT.store(port, Ordering::Relaxed);
+
     let handle = tauri::async_runtime::spawn(async move {
         if let Err(e) = axum::serve(listener, router).await {
             log::error!("MCP server crashed: {}", e);
@@ -126,6 +151,7 @@ pub fn stop_mcp_server() {
         && let Some(handle) = guard.take()
     {
         handle.abort();
+        MCP_ACTUAL_PORT.store(0, Ordering::Relaxed);
         log::info!("MCP server stopped");
     }
 }
@@ -135,6 +161,12 @@ pub fn is_mcp_running() -> bool {
     MCP_HANDLE.lock().ok().is_some_and(|guard| guard.is_some())
 }
 
+/// Returns the port the MCP server is actually listening on, or `None` if not running.
+pub fn get_mcp_actual_port() -> Option<u16> {
+    let port = MCP_ACTUAL_PORT.load(Ordering::Relaxed);
+    if port == 0 { None } else { Some(port) }
+}
+
 /// Health check endpoint.
 async fn health_check() -> impl IntoResponse {
     Json(json!({"status": "ok"}))
diff --git a/apps/desktop/src-tauri/src/mcp/tools.rs b/apps/desktop/src-tauri/src/mcp/tools.rs
@@ -375,8 +375,7 @@ fn get_search_tools() -> Vec<Tool> {
         },
         Tool {
             name: "ai_search".to_string(),
-            description: "Natural language file search using the configured LLM to translate the query"
-                .to_string(),
+            description: "Natural language file search using the configured LLM to translate the query".to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
diff --git a/apps/desktop/src-tauri/src/net.rs b/apps/desktop/src-tauri/src/net.rs
@@ -0,0 +1,40 @@
+//! Network utilities shared across modules.
+
+use std::net::TcpListener;
+
+/// Check if a port is available for binding on localhost.
+pub fn is_port_available(port: u16) -> bool {
+    TcpListener::bind(("127.0.0.1", port)).is_ok()
+}
+
+/// Find an available port on localhost starting from `start_port`, scanning up to 100 ports.
+pub fn find_available_port(start_port: u16) -> Option<u16> {
+    for offset in 0..100 {
+        let port = start_port.saturating_add(offset);
+        if is_port_available(port) {
+            return Some(port);
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_is_port_available() {
+        // High port that's likely free — just verify it doesn't panic
+        let _ = is_port_available(49999);
+    }
+
+    #[test]
+    fn test_find_available_port() {
+        let result = find_available_port(49000);
+        assert!(result.is_some());
+        if let Some(port) = result {
+            assert!(port >= 49000);
+            assert!(port < 49100);
+        }
+    }
+}
diff --git a/apps/desktop/src/lib/settings/sections/McpServerSection.svelte b/apps/desktop/src/lib/settings/sections/McpServerSection.svelte
diff --git a/apps/desktop/src/lib/settings/settings-registry.ts b/apps/desktop/src/lib/settings/settings-registry.ts
diff --git a/apps/desktop/src/lib/tauri-commands/index.ts b/apps/desktop/src/lib/tauri-commands/index.ts
diff --git a/apps/desktop/src/lib/tauri-commands/settings.ts b/apps/desktop/src/lib/tauri-commands/settings.ts
