MCP: gateway-driven port coordination (#6007)

* MCP: gateway-driven port coordination

Gateway now forwards -mcpPort N to spawned MI (configurable via --mcp-port,
default 7887). MI's setupMcp parses the flag, forces the server port and
auto-start (overriding the mcp.enableByDefault config), and shows the port
read-only in Settings. -mcpDumpFile additionally suppresses server start so
the gateway's cache-prime spawn never briefly binds the port.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Move CmdLineOverrides + parser from MRMcp to MRMcpSettings

Pure code motion — colocates CLI-flag parsing with the settings layer
(its only consumer). MRMcp public surface stays focused on the Server.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Grantim

source/MRMCPGateway/MRMCPGateway.cpp

@@ -89,7 +89,10 @@ void printUsage()
         "  --launch-arg <value>     Default argument forwarded to the backend (repeatable).\n"
         "                           A 'launch' tool call may override these for that call.\n"
         "  --launch-timeout <secs>  How long 'launch' waits for the backend (default 30).\n"
-        "  --target-url <url>       Backend MCP server URL (default http://127.0.0.1:7887).\n"
+        "  --mcp-port <port>        MCP port the backend should bind (default 7887). Forwarded\n"
+        "                           to spawned MI as -mcpPort; if --target-url is omitted, the\n"
+        "                           gateway's probe URL is derived from this port.\n"
+        "  --target-url <url>       Backend MCP server URL (default http://127.0.0.1:<mcp-port>).\n"
         "  --sse-path <path>        SSE endpoint path (default /sse).\n"
         "  --messages-path <path>   POST endpoint path (default /messages).\n"
         "  --tools-cache-namespace <name>\n"
@@ -100,6 +103,7 @@ void printUsage()
 
 bool parseArgs( int argc, char** argv, Config& cfg )
 {
+    bool targetUrlGiven = false;
     for ( int i = 1; i < argc; ++i )
     {
         const std::string a = argv[i];
@@ -117,6 +121,12 @@ bool parseArgs( int argc, char** argv, Config& cfg )
         {
             if ( !needNext( "--target-url" ) ) return false;
             cfg.targetUrl = argv[++i];
+            targetUrlGiven = true;
+        }
+        else if ( a == "--mcp-port" )
+        {
+            if ( !needNext( "--mcp-port" ) ) return false;
+            cfg.mcpPort = std::atoi( argv[++i] );
         }
         else if ( a == "--sse-path" )
         {
@@ -167,6 +177,15 @@ bool parseArgs( int argc, char** argv, Config& cfg )
         printUsage();
         return false;
     }
+    if ( cfg.mcpPort <= 0 )
+    {
+        std::cerr << "MRMCPGateway: --mcp-port must be a positive integer\n";
+        return false;
+    }
+    // Keep probe URL in sync with the port we tell MI to bind, unless the user
+    // pointed --target-url somewhere else explicitly (e.g. a remote backend).
+    if ( !targetUrlGiven )
+        cfg.targetUrl = "http://127.0.0.1:" + std::to_string( cfg.mcpPort );
     return true;
 }
 

source/MRMCPGateway/MRMCPGatewayBackend.cpp

@@ -112,6 +112,10 @@ void registerLocalTools( fastmcpp::ProxyApp& proxy, const Config& cfg )
                             args.push_back( a.get<std::string>() );
                 }
             }
+            // Always tell MI the port the gateway will probe; last-occurrence-wins
+            // parsing on MI's side means this beats any user-supplied -mcpPort in args.
+            args.emplace_back( "-mcpPort" );
+            args.emplace_back( std::to_string( cfg.mcpPort ) );
             if ( probeAndTrackBackend( cfg.targetUrl ) )
                 return std::string( "already running" );
             if ( !spawnDetached( cfg.launchCommand, args ) )

source/MRMCPGateway/MRMCPGatewayCache.cpp

@@ -143,6 +143,8 @@ void ensureFreshCache( const Config& cfg )
     std::vector<std::string> primeArgs = cfg.launchArgs;
     for ( const char* flag : { "-hidden", "-noEventLoop", "-noTelemetry", "-noSplash" } )
         primeArgs.emplace_back( flag );
+    primeArgs.emplace_back( "-mcpPort" );
+    primeArgs.emplace_back( std::to_string( cfg.mcpPort ) );
     primeArgs.emplace_back( "-mcpDumpFile" );
     primeArgs.emplace_back( cache.string() );
 

source/MRMCPGateway/MRMCPGatewayConfig.h

@@ -13,6 +13,7 @@ namespace MR::McpGateway
 /// read what they need without each replicating its own subset of CLI parsing.
 struct Config
 {
+    int mcpPort              = 7887;                   ///< -mcpPort N forwarded to spawned MI; targetUrl is derived from this if --target-url is omitted.
     std::string targetUrl    = "http://127.0.0.1:7887";
     std::string ssePath      = "/sse";
     std::string messagesPath = "/messages";

source/MRMcp/MRMcp.cpp

@@ -251,19 +251,6 @@ Expected<void> Server::saveToolsCache( const std::filesystem::path& path ) const
     return {};
 }
 
-void Server::processCmdArgs( const std::vector<std::string>& commandArgs ) const
-{
-    for ( size_t i = 0; i + 1 < commandArgs.size(); ++i )
-    {
-        if ( commandArgs[i] == "-mcpDumpFile" )
-        {
-            const std::filesystem::path target = commandArgs[i + 1];
-            if ( auto res = saveToolsCache( target ); !res )
-                spdlog::error( "MRMcp: {}", res.error() );
-            return;
-        }
-    }
-}
 void Server::setToolValidator( ToolValidator validator )
 {
     if ( !state_ )

source/MRMcp/MRMcp.h

@@ -179,11 +179,6 @@ class Server
     /// directories as needed. Returns an error message on I/O failure.
     MRMCP_API Expected<void> saveToolsCache( const std::filesystem::path& path ) const;
 
-    /// Processes MCP-related command-line arguments. Currently only `-mcpDumpFile <path>`,
-    /// which writes the tool cache to that path. Otherwise a no-op. Intended to be called
-    /// once during MCP setup with the viewer's own launch arguments, after every
-    /// `MR_ON_INIT` tool registration has run.
-    MRMCP_API void processCmdArgs( const std::vector<std::string>& commandArgs ) const;
     /// Optional predicate consulted before every tool dispatch, given the tool's id.
     /// Return {} to allow; return `unexpected("reason")` to block — the reason surfaces
     /// to the MCP client as the tool-call error.

source/MRViewer/MRMcpSettings.cpp

@@ -1,9 +1,11 @@
 #include "MRMcpSettings.h"
 
 #include "MRMesh/MRConfig.h"
+#include "MRMesh/MRStringConvert.h"
 
 #ifndef MESHLIB_NO_MCP
 #include "MRMcp/MRMcp.h"
+#include "MRViewer/MRViewer.h"
 #endif
 
 #include <utility>
@@ -61,4 +63,30 @@ void applyToServer()
     #endif
 }
 
+bool isPortLockedFromCmdLine()
+{
+    #ifndef MESHLIB_NO_MCP
+    static const bool locked = []
+    {
+        return parseCmdLineOverrides( getViewerInstance().commandArgs ).port > 0;
+    }();
+    return locked;
+    #else
+    return false;
+    #endif
+}
+
+CmdLineOverrides parseCmdLineOverrides( const std::vector<std::string>& commandArgs )
+{
+    CmdLineOverrides out;
+    for ( size_t i = 0; i + 1 < commandArgs.size(); ++i )
+    {
+        if ( commandArgs[i] == "-mcpPort" )
+            out.port = std::atoi( commandArgs[i + 1].c_str() );
+        else if ( commandArgs[i] == "-mcpDumpFile" )
+            out.dumpFilePath = pathFromUtf8( commandArgs[i + 1] );
+    }
+    return out;
+}
+
 } // namespace MR::McpSettings

source/MRViewer/MRMcpSettings.h

@@ -2,11 +2,31 @@
 
 #include "exports.h"
 
+#include <filesystem>
+#include <string>
+#include <vector>
+
 // Those functions act on the default MCP settings in the config file.
 
 namespace MR::McpSettings
 {
 
+// Overrides parsed from the application's command-line arguments. Sentinel values
+// (`port <= 0`, empty `dumpFilePath`) mean "no override".
+struct CmdLineOverrides
+{
+    int port = 0;                        ///< `-mcpPort N`. <= 0 means no override.
+    std::filesystem::path dumpFilePath;  ///< `-mcpDumpFile <path>`. Empty means no dump.
+};
+
+// Pure parse: scans @p commandArgs for MCP-related flags and returns the resolved
+// overrides. Last occurrence of each flag wins (matches shell convention).
+// `-mcpPort N` forces the server port to N (overriding the config).
+// `-mcpDumpFile <path>` requests writing the tool cache to that path; the caller
+// (typically `ViewerSetup::setupMcp`) is expected to skip starting the live server
+// in that case so a prime spawn does not collide with a real backend on the port.
+[[nodiscard]] MRVIEWER_API CmdLineOverrides parseCmdLineOverrides( const std::vector<std::string>& commandArgs );
+
 // Returns the MCP port from the config file, or the default value.
 // Note that this acts on the config file and not on the actual MCP server that might be running.
 [[nodiscard]] MRVIEWER_API int getPort();
@@ -25,4 +45,8 @@ MRVIEWER_API void setEnableByDefault( bool enable );
 // This ignores `getEnableByDefault()`.
 MRVIEWER_API void applyToServer();
 
+// True iff `-mcpPort N` was passed on the command line. The config-backed port is then
+// ignored for this session, and the GUI shows the port read-only.
+[[nodiscard]] MRVIEWER_API bool isPortLockedFromCmdLine();
+
 } // namespace MR::McpSettings

source/MRViewer/MRSetupViewer.cpp

@@ -197,10 +197,27 @@ void ViewerSetup::unloadExtendedLibraries() const
 bool ViewerSetup::setupMcp() const
 {
     #ifndef MESHLIB_NO_MCP
-    McpSettings::applyToServer();
-    if ( McpSettings::getEnableByDefault() )
-        Mcp::getDefaultServer().setRunning( true );
-    Mcp::getDefaultServer().processCmdArgs( getViewerInstance().commandArgs );
+    auto& server = Mcp::getDefaultServer();
+    const auto overrides = McpSettings::parseCmdLineOverrides( getViewerInstance().commandArgs );
+
+    // Push the effective port (CLI override beats config).
+    Mcp::Server::Params params = server.getParams();
+    params.port = overrides.port > 0 ? overrides.port : McpSettings::getPort();
+    server.setParams( std::move( params ) );
+
+    if ( !overrides.dumpFilePath.empty() )
+    {
+        // Dump-and-exit: write the tool cache and skip server start so a prime spawn
+        // does not collide with a real backend on the same port.
+        if ( auto res = server.saveToolsCache( overrides.dumpFilePath ); !res )
+            spdlog::error( "MRMcp: {}", res.error() );
+        return true;
+    }
+
+    // `-mcpPort N` forces auto-start (gateway's launch path needs MCP up regardless of
+    // the user's `mcp.enableByDefault` config). Without the flag, honor the config.
+    if ( overrides.port > 0 || McpSettings::getEnableByDefault() )
+        server.setRunning( true );
     return true;
     #else
     return false;

source/MRViewer/MRViewerSettingsPlugin.cpp

@@ -1307,12 +1307,20 @@ void ViewerSettingsPlugin::drawMcpSettings_()
     if ( UI::checkbox( _tr( "Enable by Default" ), &enableByDefault ) )
         McpSettings::setEnableByDefault( enableByDefault );
 
-    int port = McpSettings::getPort();
     ImGui::SetNextItemWidth( ImGui::GetFrameHeight() * 3 );
-    if ( UI::input<NoUnit>( _tr( "Port" ), port, 1, 65535, {}, UI::defaultSliderFlags, 0, 0 ) )
-        McpSettings::setPort( port );
-    if ( ImGui::IsItemDeactivatedAfterEdit() )
-        McpSettings::applyToServer();
+    if ( McpSettings::isPortLockedFromCmdLine() )
+    {
+        UI::readOnlyValue<NoUnit>( _tr( "Port" ), server.getParams().port );
+        UI::setTooltipIfHovered( _tr( "Port forced by -mcpPort command-line flag" ) );
+    }
+    else
+    {
+        int port = McpSettings::getPort();
+        if ( UI::input<NoUnit>( _tr( "Port" ), port, 1, 65535, {}, UI::defaultSliderFlags, 0, 0 ) )
+            McpSettings::setPort( port );
+        if ( ImGui::IsItemDeactivatedAfterEdit() )
+            McpSettings::applyToServer();
+    }
     #endif
 }