feat: automatically detect transport

alexf37 · alexf37 · commit ebb2773d425b · 2025-07-28T09:14:37.000-04:00
diff --git a/README.md b/README.md
@@ -53,6 +53,50 @@ npx install-mcp https://api.example.com/mcp --client claude \
   --header "X-API-Key: secret-key"
 ```
 
+### Transport Methods for Remote Servers
+
+When installing remote servers (URLs), the CLI needs to know which transport method the server uses. There are two transport methods:
+
+- **Streamable HTTP** (modern, recommended)
+- **SSE** (legacy)
+
+The CLI handles this in several ways:
+
+#### Automatic Detection
+
+By default, the CLI will automatically detect the transport method:
+
+```bash
+npx install-mcp https://api.example.com/mcp --client claude
+# Output: Detecting transport type... this may take a few seconds.
+# Output: We've detected that this server uses the streamable HTTP transport method. Is this correct? (Y/n)
+```
+
+If the detection succeeds, it will ask you to confirm. If you answer "no", it will use the other transport method.
+
+#### Manual Specification
+
+You can skip detection by specifying the transport method directly:
+
+```bash
+# For streamable HTTP servers
+npx install-mcp https://api.example.com/mcp --client claude --transport http
+
+# For legacy SSE servers
+npx install-mcp https://api.example.com/mcp --client claude --transport sse
+```
+
+#### Fallback to Manual Questions
+
+If auto-detection fails, the CLI will ask you directly:
+
+```
+Could not auto-detect transport type, please answer the following questions:
+Does this server support the streamable HTTP transport method? (Y/n)
+```
+
+Note: This only applies to URL-based installations. Package names and custom commands don't require transport selection.
+
 where `<client>` is one of the following:
 
 - `claude`
diff --git a/src/commands/install.test.ts b/src/commands/install.test.ts
@@ -3,13 +3,16 @@ import type { ArgumentsCamelCase } from 'yargs'
 import { handler, InstallArgv } from './install'
 import * as clientConfig from '../client-config'
 import { logger } from '../logger'
+import * as detectTransport from '../detect-transport'
 
 // Mock dependencies
 jest.mock('../client-config')
 jest.mock('../logger')
+jest.mock('../detect-transport')
 
 const mockClientConfig = clientConfig as jest.Mocked<typeof clientConfig>
 const mockLogger = logger as jest.Mocked<typeof logger>
+const mockDetectTransport = detectTransport as jest.Mocked<typeof detectTransport>
 
 describe('install command', () => {
   beforeEach(() => {
@@ -38,6 +41,7 @@ describe('install command', () => {
       configKey: 'mcpServers',
     })
     mockLogger.prompt.mockResolvedValue('test-package')
+    mockDetectTransport.detectMcpTransport.mockResolvedValue('unknown')
   })
 
   afterEach(() => {
@@ -106,11 +110,21 @@ describe('install command', () => {
         $0: 'install-mcp',
       }
 
-      // Mock the transport confirmation prompts (defaults to http)
-      mockLogger.prompt.mockResolvedValueOnce(true) // supports streamable HTTP
+      // Mock auto-detection returns http and user confirms
+      mockDetectTransport.detectMcpTransport.mockResolvedValueOnce('http')
+      mockLogger.prompt.mockResolvedValueOnce(true) // confirms detected transport
 
       await handler(argv)
 
+      expect(mockDetectTransport.detectMcpTransport).toHaveBeenCalledWith('https://example.com/server', {
+        timeoutMs: 5000,
+        headers: undefined,
+      })
+      expect(mockLogger.info).toHaveBeenCalledWith('Detecting transport type... this may take a few seconds.')
+      expect(mockLogger.prompt).toHaveBeenCalledWith(
+        "We've detected that this server uses the streamable HTTP transport method. Is this correct?",
+        { type: 'confirm' },
+      )
       expect(mockClientConfig.writeConfig).toHaveBeenCalledWith(
         expect.objectContaining({
           mcpServers: {
@@ -186,14 +200,16 @@ describe('install command', () => {
         $0: 'install-mcp',
       }
 
-      // Mock the transport confirmation prompts
-      mockLogger.prompt.mockResolvedValueOnce(true) // supports streamable HTTP
+      // Mock auto-detection returns http and user confirms
+      mockDetectTransport.detectMcpTransport.mockResolvedValueOnce('http')
+      mockLogger.prompt.mockResolvedValueOnce(true) // confirms detected transport
 
       await handler(argv)
 
-      expect(mockLogger.prompt).toHaveBeenCalledWith('Does this server support the streamable HTTP transport method?', {
-        type: 'confirm',
-      })
+      expect(mockLogger.prompt).toHaveBeenCalledWith(
+        "We've detected that this server uses the streamable HTTP transport method. Is this correct?",
+        { type: 'confirm' },
+      )
     })
 
     it('should fall back to SSE when HTTP is not supported', async () => {
@@ -205,7 +221,8 @@ describe('install command', () => {
         $0: 'install-mcp',
       }
 
-      // Mock the transport confirmation prompts
+      // Mock auto-detection returns unknown, then manual prompts
+      mockDetectTransport.detectMcpTransport.mockResolvedValueOnce('unknown')
       mockLogger.prompt
         .mockResolvedValueOnce(false) // doesn't support streamable HTTP
         .mockResolvedValueOnce(true) // uses legacy SSE
@@ -239,15 +256,16 @@ describe('install command', () => {
         $0: 'install-mcp',
       }
 
-      // Mock the transport confirmation prompts
+      // Mock auto-detection returns unknown, then manual prompts fail
+      mockDetectTransport.detectMcpTransport.mockResolvedValueOnce('unknown')
       mockLogger.prompt
         .mockResolvedValueOnce(false) // doesn't support streamable HTTP
         .mockResolvedValueOnce(false) // doesn't use legacy SSE
 
       await handler(argv)
 
       expect(mockLogger.error).toHaveBeenCalledWith(
-        'Server must support either streamable HTTP or legacy SSE transport method.',
+        'Remote servers must support either streamable HTTP or legacy SSE transport method.',
       )
       expect(mockClientConfig.writeConfig).not.toHaveBeenCalled()
     })
@@ -276,6 +294,10 @@ describe('install command', () => {
         $0: 'install-mcp',
       }
 
+      // Mock auto-detection returns http and user confirms
+      mockDetectTransport.detectMcpTransport.mockResolvedValueOnce('http')
+      mockLogger.prompt.mockResolvedValueOnce(true) // confirms detected transport
+
       await handler(argv)
 
       expect(mockClientConfig.writeConfig).toHaveBeenCalledWith(
@@ -409,8 +431,9 @@ describe('install command', () => {
         $0: 'install-mcp',
       }
 
-      // Mock the transport confirmation prompts (defaults to http)
-      mockLogger.prompt.mockResolvedValueOnce(true) // supports streamable HTTP
+      // Mock auto-detection returns http and user confirms
+      mockDetectTransport.detectMcpTransport.mockResolvedValueOnce('http')
+      mockLogger.prompt.mockResolvedValueOnce(true) // confirms detected transport
 
       await handler(argv)
 
@@ -580,6 +603,128 @@ describe('install command', () => {
         undefined,
       )
     })
+
+    it('should auto-detect SSE transport and install with confirmation', async () => {
+      const argv: ArgumentsCamelCase<InstallArgv> = {
+        client: 'cline',
+        target: 'https://example.com/server',
+        yes: true,
+        _: [],
+        $0: 'install-mcp',
+      }
+
+      // Mock auto-detection returns sse and user confirms
+      mockDetectTransport.detectMcpTransport.mockResolvedValueOnce('sse')
+      mockLogger.prompt.mockResolvedValueOnce(true) // confirms detected transport
+
+      await handler(argv)
+
+      expect(mockLogger.prompt).toHaveBeenCalledWith(
+        "We've detected that this server uses the SSE transport method. Is this correct?",
+        { type: 'confirm' },
+      )
+      expect(mockClientConfig.writeConfig).toHaveBeenCalledWith(
+        expect.objectContaining({
+          mcpServers: {
+            'example-com': {
+              command: 'npx',
+              args: ['-y', 'supergateway', '--sse', 'https://example.com/server'],
+            },
+          },
+        }),
+        'cline',
+        undefined,
+      )
+    })
+
+    it('should use opposite transport when user rejects auto-detection', async () => {
+      const argv: ArgumentsCamelCase<InstallArgv> = {
+        client: 'cline',
+        target: 'https://example.com/server',
+        yes: true,
+        _: [],
+        $0: 'install-mcp',
+      }
+
+      // Mock auto-detection returns http but user rejects it
+      mockDetectTransport.detectMcpTransport.mockResolvedValueOnce('http')
+      mockLogger.prompt.mockResolvedValueOnce(false) // rejects detected transport
+
+      await handler(argv)
+
+      expect(mockLogger.info).toHaveBeenCalledWith('Installing as SSE transport method.')
+      expect(mockClientConfig.writeConfig).toHaveBeenCalledWith(
+        expect.objectContaining({
+          mcpServers: {
+            'example-com': {
+              command: 'npx',
+              args: ['-y', 'supergateway', '--sse', 'https://example.com/server'],
+            },
+          },
+        }),
+        'cline',
+        undefined,
+      )
+    })
+
+    it('should fall back to manual questions when auto-detection returns unknown', async () => {
+      const argv: ArgumentsCamelCase<InstallArgv> = {
+        client: 'cline',
+        target: 'https://example.com/server',
+        yes: true,
+        _: [],
+        $0: 'install-mcp',
+      }
+
+      // Mock auto-detection returns unknown
+      mockDetectTransport.detectMcpTransport.mockResolvedValueOnce('unknown')
+      mockLogger.prompt.mockResolvedValueOnce(true) // supports streamable HTTP
+
+      await handler(argv)
+
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        'Could not auto-detect transport type, please answer the following questions:',
+      )
+      expect(mockLogger.prompt).toHaveBeenCalledWith('Does this server support the streamable HTTP transport method?', {
+        type: 'confirm',
+      })
+      expect(mockClientConfig.writeConfig).toHaveBeenCalledWith(
+        expect.objectContaining({
+          mcpServers: {
+            'example-com': {
+              command: 'npx',
+              args: ['-y', 'supergateway', '--streamableHttp', 'https://example.com/server'],
+            },
+          },
+        }),
+        'cline',
+        undefined,
+      )
+    })
+
+    it('should pass headers to detectMcpTransport when provided', async () => {
+      const argv: ArgumentsCamelCase<InstallArgv> = {
+        client: 'cline',
+        target: 'https://example.com/server',
+        header: ['Authorization: Bearer token123'],
+        yes: true,
+        _: [],
+        $0: 'install-mcp',
+      }
+
+      // Mock auto-detection returns http and user confirms
+      mockDetectTransport.detectMcpTransport.mockResolvedValueOnce('http')
+      mockLogger.prompt.mockResolvedValueOnce(true) // confirms detected transport
+
+      await handler(argv)
+
+      expect(mockDetectTransport.detectMcpTransport).toHaveBeenCalledWith('https://example.com/server', {
+        timeoutMs: 5000,
+        headers: {
+          Authorization: 'Bearer token123',
+        },
+      })
+    })
   })
 
   describe('name inference', () => {
diff --git a/src/commands/install.ts b/src/commands/install.ts
@@ -10,6 +10,7 @@ import {
   setNestedValue,
   type ClientConfig,
 } from '../client-config'
+import { detectMcpTransport } from '../detect-transport'
 
 // Helper to set a server config in a nested structure
 function setServerConfig(
@@ -161,25 +162,54 @@ export async function handler(argv: ArgumentsCamelCase<InstallArgv>) {
   // Prompt for transport if target is a URL and transport not specified
   let transport = argv.transport
   if (isUrl(target) && !transport) {
-    // Ask about streamable HTTP first (default yes)
-    const supportsStreamableHttp = await logger.prompt(
-      'Does this server support the streamable HTTP transport method?',
-      { type: 'confirm' },
-    )
+    // Try to auto-detect the transport type
+    logger.info('Detecting transport type... this may take a few seconds.')
+
+    const detectedTransport = await detectMcpTransport(target, {
+      timeoutMs: 5000,
+      headers: argv.header ? parseHeaders(argv.header) : undefined,
+    })
 
-    if (supportsStreamableHttp) {
-      transport = 'http'
+    if (detectedTransport === 'http' || detectedTransport === 'sse') {
+      // We detected a transport type, ask for confirmation
+      const transportDisplay = detectedTransport === 'http' ? 'streamable HTTP' : 'SSE'
+      const confirmed = await logger.prompt(
+        `We've detected that this server uses the ${transportDisplay} transport method. Is this correct?`,
+        { type: 'confirm' },
+      )
+
+      if (confirmed) {
+        transport = detectedTransport
+      } else {
+        // User said no, use the other transport method
+        transport = detectedTransport === 'http' ? 'sse' : 'http'
+        const otherTransportDisplay = transport === 'http' ? 'streamable HTTP' : 'SSE'
+        logger.info(`Installing as ${otherTransportDisplay} transport method.`)
+      }
     } else {
-      // Ask about legacy SSE (default no, but if they said no to HTTP, we need to confirm SSE)
-      const usesLegacySSE = await logger.prompt('Does your server use the legacy SSE transport method?', {
-        type: 'confirm',
-      })
+      // Detection failed, fall back to manual questions
+      logger.info('Could not auto-detect transport type, please answer the following questions:')
 
-      if (usesLegacySSE) {
-        transport = 'sse'
+      // Ask about streamable HTTP first (default yes)
+      const supportsStreamableHttp = await logger.prompt(
+        'Does this server support the streamable HTTP transport method?',
+        { type: 'confirm' },
+      )
+
+      if (supportsStreamableHttp) {
+        transport = 'http'
       } else {
-        logger.error('Server must support either streamable HTTP or legacy SSE transport method.')
-        return
+        // Ask about legacy SSE (default no, but if they said no to HTTP, we need to confirm SSE)
+        const usesLegacySSE = await logger.prompt('Does your server use the legacy SSE transport method?', {
+          type: 'confirm',
+        })
+
+        if (usesLegacySSE) {
+          transport = 'sse'
+        } else {
+          logger.error('Remote servers must support either streamable HTTP or legacy SSE transport method.')
+          return
+        }
       }
     }
   }
diff --git a/src/detect-transport.ts b/src/detect-transport.ts
