feat: sdk-commands mcp params for unity explorer (#1496)

Author: pravusjif

packages/@dcl/sdk-commands/package-lock.json

@@ -4,6 +4,31 @@ import { CliComponents } from '../../components'
 
 const isWindows = /^win/.test(process.platform)
 
+/**
+ * Parses raw CLI tokens (everything after a standalone `--`) into deep link query params.
+ * Supports `--key=value`, `--key value` and bare `--key` (mapped to `key=true`).
+ * Tokens that are not flags and not consumed as a value are ignored.
+ */
+export function parsePassthroughParams(tokens: string[]): Map<string, string> {
+  const params = new Map<string, string>()
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]
+    if (!token.startsWith('-')) continue
+    const stripped = token.replace(/^-+/, '')
+    if (!stripped) continue
+    const eqIndex = stripped.indexOf('=')
+    if (eqIndex > 0) {
+      params.set(stripped.slice(0, eqIndex), stripped.slice(eqIndex + 1))
+    } else if (eqIndex === -1 && i + 1 < tokens.length && !tokens[i + 1].startsWith('-')) {
+      params.set(stripped, tokens[i + 1])
+      i++
+    } else if (eqIndex === -1) {
+      params.set(stripped, 'true')
+    }
+  }
+  return params
+}
+
 export async function runExplorerAlpha(
   components: CliComponents,
   opts: {
@@ -47,6 +72,8 @@ async function runApp(
   const landscapeTerrainEnabled = !!args['--landscape-terrain-enabled']
   const openDeeplinkInNewInstance = !!args['-n']
   const multiInstance = !!args['--multi-instance']
+  const mcp = !!args['--mcp']
+  const mcpPort = args['--mcp-port']
 
   try {
     if (isWindows) {
@@ -78,6 +105,20 @@ async function runApp(
     if (multiInstance) {
       params.set('multi-instance', 'true')
     }
+    if (mcp) {
+      params.set('mcp', 'true')
+    }
+    if (mcpPort !== undefined) {
+      params.set('mcp-port', String(mcpPort))
+    }
+
+    // Forward any params placed after a standalone `--` verbatim into the deep link.
+    // Only fill in params that aren't already covered by a declared flag/default, so
+    // passthrough can't silently override an intentionally declared flag.
+    for (const [key, value] of parsePassthroughParams(args._ ?? [])) {
+      if (params.has(key)) continue
+      params.set(key, value)
+    }
 
     const queryParams = params.toString()
 

packages/@dcl/sdk-commands/src/commands/start/explorer-alpha.ts

@@ -68,7 +68,9 @@ export const args = declareArgs({
   '-n': Boolean,
   '--bevy-web': Boolean,
   '--multi-instance': Boolean,
-  '--no-client': Boolean
+  '--no-client': Boolean,
+  '--mcp': Boolean,
+  '--mcp-port': Number
 })
 
 export async function help(options: Options) {
@@ -98,6 +100,15 @@ export async function help(options: Options) {
       --mobile                          Show QR code for mobile preview on the same network.
       --multi-instance                  Allow running multiple Explorer instances simultaneously.
       --no-client                       Suppress every auto-launch (desktop Explorer deeplink, browser open, mobile QR). The file watcher still notifies a desktop Explorer if it connects on its own — useful when an external tool owns the Explorer process.
+      --mcp                             Enable the MCP server in the Explorer (forwarded as a deep link parameter).
+      --mcp-port                        Port for the MCP server in the Explorer (forwarded as a deep link parameter).
+
+    Any argument placed after a standalone \`--\` is not parsed by the CLI and is forwarded verbatim
+    into the Explorer deep link as a query parameter. Supported forms: --key=value, --key value,
+    and bare --key (forwarded as key=true). Declared flags above take precedence over forwarded params.
+
+      $ sdk-commands start -- --paramA --paramX valueX
+      $ npm run start -- -- --paramA --paramX valueX      (npm consumes the first --)
 
 
     Examples:

packages/@dcl/sdk-commands/src/commands/start/index.ts

@@ -185,6 +185,152 @@ describe('explorer-alpha', () => {
     })
   })
 
+  describe('mcp parameter', () => {
+    it('should include mcp parameter when --mcp flag is provided', async () => {
+      const args: any = {
+        '--mcp': true
+      }
+
+      await runExplorerAlpha(mockComponents, {
+        cwd: '/test',
+        realm: 'test-realm',
+        baseCoords: { x: 0, y: 0 },
+        isHub: false,
+        args
+      })
+
+      expect(mockExec).toHaveBeenCalledWith(
+        '/test',
+        'open',
+        expect.arrayContaining([expect.stringContaining('mcp=true')]),
+        { silent: true }
+      )
+    })
+
+    it('should include mcp-port parameter when --mcp-port is provided', async () => {
+      const args: any = {
+        '--mcp': true,
+        '--mcp-port': 8025
+      }
+
+      await runExplorerAlpha(mockComponents, {
+        cwd: '/test',
+        realm: 'test-realm',
+        baseCoords: { x: 0, y: 0 },
+        isHub: false,
+        args
+      })
+
+      expect(mockExec).toHaveBeenCalledWith(
+        '/test',
+        'open',
+        expect.arrayContaining([expect.stringContaining('mcp-port=8025')]),
+        { silent: true }
+      )
+    })
+
+    it('should not include mcp-port parameter when --mcp-port is not provided', async () => {
+      const args: any = {}
+
+      await runExplorerAlpha(mockComponents, {
+        cwd: '/test',
+        realm: 'test-realm',
+        baseCoords: { x: 0, y: 0 },
+        isHub: false,
+        args
+      })
+
+      expect(mockExec).toHaveBeenCalledWith(
+        '/test',
+        'open',
+        expect.arrayContaining([expect.not.stringContaining('mcp-port')]),
+        { silent: true }
+      )
+    })
+
+    it('should not include mcp parameter when --mcp flag is not provided', async () => {
+      const args: any = {}
+
+      await runExplorerAlpha(mockComponents, {
+        cwd: '/test',
+        realm: 'test-realm',
+        baseCoords: { x: 0, y: 0 },
+        isHub: false,
+        args
+      })
+
+      expect(mockExec).toHaveBeenCalledWith(
+        '/test',
+        'open',
+        expect.arrayContaining([expect.not.stringContaining('mcp=true')]),
+        { silent: true }
+      )
+    })
+  })
+
+  describe('passthrough parameters (after standalone --)', () => {
+    async function run(args: any) {
+      await runExplorerAlpha(mockComponents, {
+        cwd: '/test',
+        realm: 'test-realm',
+        baseCoords: { x: 0, y: 0 },
+        isHub: false,
+        args
+      })
+      return mockExec.mock.calls[0][2][0] as string
+    }
+
+    it('forwards a bare flag as key=true', async () => {
+      const deepLink = await run({ _: ['--paramA'] })
+      expect(deepLink).toContain('paramA=true')
+    })
+
+    it('forwards a flag followed by a value as key=value', async () => {
+      const deepLink = await run({ _: ['--paramX', 'valueX'] })
+      expect(deepLink).toContain('paramX=valueX')
+    })
+
+    it('forwards --key=value syntax', async () => {
+      const deepLink = await run({ _: ['--paramX=valueX'] })
+      expect(deepLink).toContain('paramX=valueX')
+    })
+
+    it('forwards multiple params, mixing bare flags and valued flags', async () => {
+      const deepLink = await run({ _: ['--paramA', '--paramB', '--paramX', 'valueX'] })
+      expect(deepLink).toContain('paramA=true')
+      expect(deepLink).toContain('paramB=true')
+      expect(deepLink).toContain('paramX=valueX')
+    })
+
+    it('does not override built-in deep link params already covered by a declared flag/default', async () => {
+      const deepLink = await run({ _: ['--realm', 'whatever.dcl.eth'] })
+      expect(deepLink).toContain('realm=test-realm')
+      expect(deepLink).not.toContain('realm=whatever.dcl.eth')
+    })
+
+    it('does not override an explicitly declared flag', async () => {
+      const deepLink = await run({ '--realm': 'declared.dcl.eth', _: ['--realm', 'whatever.dcl.eth'] })
+      expect(deepLink).toContain('realm=declared.dcl.eth')
+      expect(deepLink).not.toContain('realm=whatever.dcl.eth')
+    })
+
+    it('fills in a param that is not covered by any declared flag/default', async () => {
+      const deepLink = await run({ _: ['--paramA'] })
+      expect(deepLink).toContain('paramA=true')
+    })
+
+    it('ignores bare tokens that are not flags and not values of a flag', async () => {
+      const deepLink = await run({ _: ['stray-positional', '--paramA'] })
+      expect(deepLink).not.toContain('stray-positional')
+      expect(deepLink).toContain('paramA=true')
+    })
+
+    it('url-encodes forwarded values', async () => {
+      const deepLink = await run({ _: ['--paramX', 'a value&other'] })
+      expect(deepLink).toContain('paramX=a+value%26other')
+    })
+  })
+
   describe('URL parameter construction', () => {
     it('should construct URL with all parameters correctly', async () => {
       const args: any = {