@phenx-inc/ctlsurf 0.1.0 → 0.1.2

package/bin/ctlsurf-worker.js

@@ -4,7 +4,8 @@
  * ctlsurf launcher
  *
  * Subcommands:
- *   ctlsurf update     — pull latest and rebuild
+ *   ctlsurf setup      — configure MCP for all detected coding agents
+ *   ctlsurf update     — update to latest version
  *   ctlsurf doctor     — check all dependencies
  *   ctlsurf version    — print version
  *
@@ -16,11 +17,95 @@
 const { execFileSync, execSync } = require('child_process')
 const path = require('path')
 const fs = require('fs')
+const os = require('os')
 
 const ROOT = path.resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const subcommand = args[0]
 
+// ─── Colors ───────────────────────────────────────
+
+const G = '\x1b[32m'
+const Y = '\x1b[33m'
+const B = '\x1b[34m'
+const D = '\x1b[90m'
+const R = '\x1b[0m'
+
+// ─── MCP check ────────────────────────────────────
+
+function isMcpConfigured() {
+  // Check env var
+  if (process.env.CTLSURF_API_KEY) return true
+
+  // Check Claude Code settings
+  try {
+    const claudeSettings = path.join(os.homedir(), '.claude', 'settings.json')
+    if (fs.existsSync(claudeSettings)) {
+      const data = JSON.parse(fs.readFileSync(claudeSettings, 'utf-8'))
+      if (data.mcpServers && data.mcpServers.ctlsurf) return true
+    }
+  } catch {}
+
+  // Check Codex config
+  try {
+    const codexConfig = path.join(os.homedir(), '.codex', 'config.toml')
+    if (fs.existsSync(codexConfig)) {
+      const data = fs.readFileSync(codexConfig, 'utf-8')
+      if (data.includes('[mcp_servers.ctlsurf]')) return true
+    }
+  } catch {}
+
+  // Check Cursor config
+  try {
+    const cursorMcp = path.join(os.homedir(), '.cursor', 'mcp.json')
+    if (fs.existsSync(cursorMcp)) {
+      const data = JSON.parse(fs.readFileSync(cursorMcp, 'utf-8'))
+      if (data.mcpServers && data.mcpServers.ctlsurf) return true
+    }
+  } catch {}
+
+  return false
+}
+
+function runSetup() {
+  const setupScript = path.join(ROOT, 'scripts', 'setup-mcp.sh')
+  if (!fs.existsSync(setupScript)) {
+    console.error(`${Y}!${R} Setup script not found: ${setupScript}`)
+    console.error(`  Run the web installer instead: curl -fsSL https://app.ctlsurf.com/install.sh | bash`)
+    process.exit(1)
+  }
+  try {
+    execFileSync('bash', [setupScript, ...args.slice(1)], { stdio: 'inherit' })
+  } catch (err) {
+    process.exit(err.status || 1)
+  }
+}
+
+function promptSetup() {
+  console.log(`\n${B}  ctlsurf${R}\n`)
+  console.log(`  MCP is not configured for any coding agent.`)
+  console.log(`  Run setup to connect ctlsurf to Claude Code, Codex, Copilot, and Cursor.\n`)
+  console.log(`  ${B}ctlsurf setup${R}            ${D}# interactive setup${R}`)
+  console.log(`  ${D}ctlsurf --terminal${R}       ${D}# skip setup, launch anyway${R}\n`)
+
+  // Interactive prompt
+  if (process.stdin.isTTY) {
+    const readline = require('readline')
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+    rl.question(`  Run setup now? ${D}(Y/n)${R} `, (answer) => {
+      rl.close()
+      if (!answer || answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
+        console.log('')
+        runSetup()
+      } else {
+        console.log('')
+      }
+    })
+    return true // handled
+  }
+  return false
+}
+
 // ─── Subcommands ──────────────────────────────────
 
 if (subcommand === 'version' || args.includes('--version') || args.includes('-v')) {
@@ -33,20 +118,18 @@ if (subcommand === 'version' || args.includes('--version') || args.includes('-v'
   process.exit(0)
 }
 
-if (subcommand === 'update') {
-  const G = '\x1b[32m'
-  const Y = '\x1b[33m'
-  const B = '\x1b[34m'
-  const D = '\x1b[90m'
-  const R = '\x1b[0m'
+if (subcommand === 'setup') {
+  runSetup()
+  process.exit(0)
+}
 
+if (subcommand === 'update') {
   console.log(`\n${B}  ctlsurf update${R}\n`)
 
   try {
     console.log(`${D}Updating via npm...${R}`)
     execSync('npm update -g @phenx-inc/ctlsurf', { stdio: 'inherit' })
 
-    // Re-read version after update
     let ver = '?'
     try { ver = require(path.join(ROOT, 'package.json')).version } catch {}
     console.log(`\n${G}✓${R} ctlsurf v${ver}\n`)
@@ -58,12 +141,6 @@ if (subcommand === 'update') {
 }
 
 if (subcommand === 'doctor') {
-  const G = '\x1b[32m'
-  const Y = '\x1b[33m'
-  const R = '\x1b[0m'
-  const D = '\x1b[90m'
-  const B = '\x1b[34m'
-
   console.log(`\n${B}  ctlsurf doctor${R}\n`)
 
   function check(name, cmd, required, fix) {
@@ -88,7 +165,7 @@ if (subcommand === 'doctor') {
   check('npm', 'npm --version', true)
   check('git', 'git --version', true)
 
-  // node-pty native addon
+  // node-pty
   try {
     require(path.join(ROOT, 'node_modules/node-pty'))
     console.log(`  ${G}✓${R} node-pty ${D}(native addon loaded)${R}`)
@@ -105,6 +182,14 @@ if (subcommand === 'doctor') {
 
   console.log('')
 
+  // MCP config
+  if (isMcpConfigured()) {
+    console.log(`  ${G}✓${R} MCP configured ${D}(ctlsurf server connected)${R}`)
+  } else {
+    console.log(`  ${Y}✗${R} MCP not configured`)
+    console.log(`    ${D}Run: ctlsurf setup${R}`)
+  }
+
   // Desktop
   try {
     require.resolve('electron')
@@ -125,6 +210,14 @@ if (subcommand === 'doctor') {
   process.exit(0)
 }
 
+// ─── Auto-detect MCP on first run ─────────────────
+
+if (!subcommand || subcommand.startsWith('--')) {
+  if (!isMcpConfigured() && !args.includes('--skip-setup')) {
+    if (promptSetup()) return // async prompt, exits after
+  }
+}
+
 // ─── Mode detection ───────────────────────────────
 
 function detectMode(argv) {
@@ -145,13 +238,57 @@ if (mode === 'desktop') {
   try {
     electronPath = require('electron')
   } catch {
-    console.error('[ctlsurf] Electron not found, falling back to terminal mode')
+    // Electron not installed — prompt to install or fall back
+    if (process.stdin.isTTY && !args.includes('--terminal')) {
+      console.log(`\n${B}  ctlsurf${R}\n`)
+      console.log(`  Electron is not installed. Desktop mode requires Electron.\n`)
+      console.log(`  ${D}1)${R} Install Electron and launch desktop mode`)
+      console.log(`  ${D}2)${R} Launch in terminal mode instead`)
+      console.log(`  ${D}3)${R} Exit\n`)
+
+      const readline = require('readline')
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+      rl.question(`  Choice ${D}(1/2/3)${R}: `, (answer) => {
+        rl.close()
+        answer = answer.trim()
+        if (answer === '1') {
+          console.log(`\n${D}Installing Electron (this may take a minute)...${R}\n`)
+          try {
+            execSync('npm install electron --no-save', { cwd: ROOT, stdio: 'inherit' })
+            console.log(`\n${G}✓${R} Electron installed. Launching desktop mode...\n`)
+            try {
+              const ep = require('electron')
+              execFileSync(String(ep), [ROOT, ...args], {
+                stdio: 'inherit',
+                env: { ...process.env, CTLSURF_WORKER_CWD: process.env.CTLSURF_WORKER_CWD || process.cwd() }
+              })
+            } catch (err) {
+              process.exit(err.status || 0)
+            }
+          } catch (err) {
+            console.error(`\n${Y}!${R} Electron install failed: ${err.message}`)
+            console.error(`  Try manually: cd ${ROOT} && npm install electron\n`)
+            process.exit(1)
+          }
+        } else if (answer === '2') {
+          console.log('')
+          runTerminal()
+        } else {
+          process.exit(0)
+        }
+      })
+      return
+    }
+    // Non-interactive: fall back silently
     runTerminal()
     process.exit(0)
   }
 
   try {
-    execFileSync(String(electronPath), [ROOT, ...args], { stdio: 'inherit' })
+    execFileSync(String(electronPath), [ROOT, ...args], {
+      stdio: 'inherit',
+      env: { ...process.env, CTLSURF_WORKER_CWD: process.env.CTLSURF_WORKER_CWD || process.cwd() }
+    })
   } catch (err) {
     process.exit(err.status || 0)
   }
@@ -166,7 +303,10 @@ function runTerminal() {
     process.exit(1)
   }
   try {
-    execFileSync(process.execPath, [terminalPath, ...args], { stdio: 'inherit' })
+    execFileSync(process.execPath, [terminalPath, ...args], {
+      stdio: 'inherit',
+      env: { ...process.env, CTLSURF_WORKER_CWD: process.env.CTLSURF_WORKER_CWD || process.cwd() }
+    })
   } catch (err) {
     process.exit(err.status || 0)
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phenx-inc/ctlsurf",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Agent-agnostic terminal and desktop app for ctlsurf — run Claude Code, Codex, or any coding agent with live session logging and remote control",
   "main": "out/main/index.js",
   "bin": {
@@ -11,6 +11,7 @@
     "bin/",
     "out/",
     "resources/",
+    "scripts/",
     "src/",
     "package.json",
     "electron-vite.config.ts",

package/scripts/bundle.sh

@@ -0,0 +1,90 @@
+#!/bin/sh
+set -e
+
+# ─── Bundle ctlsurf for distribution ──────────────
+#
+# Creates a platform-specific tarball with everything needed to run.
+# No build tools required on the target machine.
+#
+# Output: dist/ctlsurf-<version>-<os>-<arch>.tar.gz
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+VERSION=$(node -e "console.log(require('./package.json').version)")
+OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+ARCH=$(uname -m)
+
+# Normalize arch names
+case "$ARCH" in
+  x86_64)  ARCH="x64" ;;
+  aarch64) ARCH="arm64" ;;
+  arm64)   ARCH="arm64" ;;
+esac
+
+BUNDLE_NAME="ctlsurf-${VERSION}-${OS}-${ARCH}"
+DIST_DIR="$ROOT/dist"
+STAGE_DIR="$DIST_DIR/$BUNDLE_NAME"
+
+echo "Building ctlsurf v${VERSION} for ${OS}-${ARCH}..."
+
+# ─── Build ─────────────────────────────────────────
+
+echo "Building headless..."
+npm run build:headless
+
+echo "Building desktop..."
+npx electron-vite build 2>/dev/null || echo "(desktop build skipped — no electron)"
+
+# ─── Stage ─────────────────────────────────────────
+
+rm -rf "$STAGE_DIR"
+mkdir -p "$STAGE_DIR"
+
+# Bin
+cp -r bin "$STAGE_DIR/bin"
+chmod +x "$STAGE_DIR/bin/ctlsurf-worker.js"
+
+# Built output
+cp -r out "$STAGE_DIR/out"
+
+# Package metadata
+cp package.json "$STAGE_DIR/package.json"
+
+# Resources (icons)
+if [ -d resources ]; then
+  cp -r resources "$STAGE_DIR/resources"
+fi
+
+# node_modules — only runtime deps, with native addons pre-compiled
+mkdir -p "$STAGE_DIR/node_modules"
+
+# node-pty (native addon — platform-specific)
+if [ -d node_modules/node-pty ]; then
+  cp -r node_modules/node-pty "$STAGE_DIR/node_modules/node-pty"
+fi
+
+# nan (node-pty dependency)
+if [ -d node_modules/nan ]; then
+  cp -r node_modules/nan "$STAGE_DIR/node_modules/nan"
+fi
+
+# node-addon-api (node-pty dependency)
+if [ -d node_modules/node-addon-api ]; then
+  cp -r node_modules/node-addon-api "$STAGE_DIR/node_modules/node-addon-api"
+fi
+
+# ─── Tarball ───────────────────────────────────────
+
+echo "Creating tarball..."
+cd "$DIST_DIR"
+tar -czf "${BUNDLE_NAME}.tar.gz" "$BUNDLE_NAME"
+rm -rf "$STAGE_DIR"
+
+SIZE=$(du -h "${BUNDLE_NAME}.tar.gz" | awk '{print $1}')
+echo ""
+echo "✓ dist/${BUNDLE_NAME}.tar.gz (${SIZE})"
+echo ""
+echo "Install on target machine:"
+echo "  tar -xzf ${BUNDLE_NAME}.tar.gz -C ~/.ctlsurf --strip-components=1"
+echo "  ln -sf ~/.ctlsurf/bin/ctlsurf-worker.js /usr/local/bin/ctlsurf"

package/scripts/setup-mcp.sh

@@ -0,0 +1,764 @@
+#!/bin/bash
+#
+# ctlsurf MCP Setup
+# Usage: curl -fsSL https://app.ctlsurf.com/install.sh | bash
+#
+# Options (pass via: curl ... | bash -s -- --flag):
+#   --force-codex   Force Codex configuration even if not detected
+#   --force-claude  Force Claude configuration even if not detected
+#   --force-copilot Force GitHub Copilot configuration even if not detected
+#   --force-cursor  Force Cursor configuration even if not detected
+#   --force         Force all configurations
+#
+# Detects and configures:
+#   - Claude Code CLI
+#   - Claude Code VSCode Extension
+#   - OpenAI Codex CLI
+#   - OpenAI Codex VSCode Extension
+#   - GitHub Copilot VSCode Extension
+#   - Cursor Editor
+#
+
+set -e
+
+# Parse command line arguments
+FORCE_CODEX=false
+FORCE_CLAUDE=false
+FORCE_COPILOT=false
+FORCE_CURSOR=false
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --force-codex) FORCE_CODEX=true; shift ;;
+        --force-claude) FORCE_CLAUDE=true; shift ;;
+        --force-copilot) FORCE_COPILOT=true; shift ;;
+        --force-cursor) FORCE_CURSOR=true; shift ;;
+        --force) FORCE_CODEX=true; FORCE_CLAUDE=true; FORCE_COPILOT=true; FORCE_CURSOR=true; shift ;;
+        *) shift ;;
+    esac
+done
+
+echo "========================================"
+echo "  ctlsurf MCP Setup"
+echo "========================================"
+echo ""
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+FOUND_CLAUDE_CLI=false
+FOUND_CLAUDE_VSCODE=false
+FOUND_CODEX_CLI=false
+FOUND_CODEX_VSCODE=false
+FOUND_COPILOT=false
+FOUND_CURSOR=false
+
+# Determine VSCode settings path based on OS
+get_vscode_settings_path() {
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        echo "$HOME/Library/Application Support/Code/User/settings.json"
+    elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+        echo "$HOME/.config/Code/User/settings.json"
+    elif [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "cygwin" ]] || [[ "$OSTYPE" == "win32" ]]; then
+        echo "$APPDATA/Code/User/settings.json"
+    else
+        echo ""
+    fi
+}
+
+# Determine VSCode mcp.json path based on OS (for Copilot)
+get_vscode_mcp_path() {
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        echo "$HOME/Library/Application Support/Code/User/mcp.json"
+    elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+        echo "$HOME/.config/Code/User/mcp.json"
+    elif [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "cygwin" ]] || [[ "$OSTYPE" == "win32" ]]; then
+        echo "$APPDATA/Code/User/mcp.json"
+    else
+        echo ""
+    fi
+}
+
+# Check if a VSCode extension is installed
+check_vscode_extension() {
+    local ext_id="$1"
+
+    # Method 1: Try using code CLI
+    if command -v code &> /dev/null; then
+        if code --list-extensions 2>/dev/null | grep -qi "$ext_id"; then
+            return 0
+        fi
+    fi
+
+    # Method 2: Check extensions folder directly (fallback when code not in PATH)
+    local ext_dir="$HOME/.vscode/extensions"
+    if [ -d "$ext_dir" ]; then
+        if ls "$ext_dir" 2>/dev/null | grep -qi "$ext_id"; then
+            return 0
+        fi
+    fi
+
+    return 1
+}
+
+echo -e "${BLUE}Detecting installed tools...${NC}"
+echo ""
+
+# Check for Claude CLI
+if [ "$FORCE_CLAUDE" = true ]; then
+    echo -e "${GREEN}✓ Claude Code CLI (forced)${NC}"
+    FOUND_CLAUDE_CLI=true
+elif command -v claude &> /dev/null; then
+    echo -e "${GREEN}✓ Found Claude Code CLI${NC}"
+    FOUND_CLAUDE_CLI=true
+else
+    echo -e "${YELLOW}○ Claude Code CLI not found${NC}"
+fi
+
+# Check for Claude Code VSCode Extension
+if check_vscode_extension "anthropic.claude-code"; then
+    echo -e "${GREEN}✓ Found Claude Code VSCode Extension${NC}"
+    FOUND_CLAUDE_VSCODE=true
+else
+    echo -e "${YELLOW}○ Claude Code VSCode Extension not found${NC}"
+fi
+
+# Check for Codex CLI (also check ~/.codex dir for installations not in PATH)
+if [ "$FORCE_CODEX" = true ]; then
+    echo -e "${GREEN}✓ OpenAI Codex CLI (forced)${NC}"
+    FOUND_CODEX_CLI=true
+elif command -v codex &> /dev/null; then
+    echo -e "${GREEN}✓ Found OpenAI Codex CLI${NC}"
+    FOUND_CODEX_CLI=true
+elif [ -d "$HOME/.codex" ]; then
+    echo -e "${GREEN}✓ Found OpenAI Codex config directory${NC}"
+    FOUND_CODEX_CLI=true
+else
+    echo -e "${YELLOW}○ OpenAI Codex CLI not found${NC}"
+fi
+
+# Check for Codex/ChatGPT VSCode Extension (openai.codex or openai.chatgpt)
+if check_vscode_extension "openai.codex" || check_vscode_extension "openai.chatgpt"; then
+    echo -e "${GREEN}✓ Found OpenAI Codex VSCode Extension${NC}"
+    FOUND_CODEX_VSCODE=true
+else
+    echo -e "${YELLOW}○ OpenAI Codex VSCode Extension not found${NC}"
+fi
+
+# Check for GitHub Copilot VSCode Extension
+if [ "$FORCE_COPILOT" = true ]; then
+    echo -e "${GREEN}✓ GitHub Copilot (forced)${NC}"
+    FOUND_COPILOT=true
+elif check_vscode_extension "github.copilot"; then
+    echo -e "${GREEN}✓ Found GitHub Copilot VSCode Extension${NC}"
+    FOUND_COPILOT=true
+else
+    echo -e "${YELLOW}○ GitHub Copilot VSCode Extension not found${NC}"
+fi
+
+# Check for Cursor Editor (check command or config directory)
+if [ "$FORCE_CURSOR" = true ]; then
+    echo -e "${GREEN}✓ Cursor Editor (forced)${NC}"
+    FOUND_CURSOR=true
+elif command -v cursor &> /dev/null; then
+    echo -e "${GREEN}✓ Found Cursor Editor${NC}"
+    FOUND_CURSOR=true
+elif [ -d "$HOME/.cursor" ]; then
+    echo -e "${GREEN}✓ Found Cursor config directory${NC}"
+    FOUND_CURSOR=true
+elif [ -d "/Applications/Cursor.app" ]; then
+    echo -e "${GREEN}✓ Found Cursor.app${NC}"
+    FOUND_CURSOR=true
+else
+    echo -e "${YELLOW}○ Cursor Editor not found${NC}"
+fi
+
+echo ""
+
+# Exit if nothing found
+if [ "$FOUND_CLAUDE_CLI" = false ] && [ "$FOUND_CLAUDE_VSCODE" = false ] && \
+   [ "$FOUND_CODEX_CLI" = false ] && [ "$FOUND_CODEX_VSCODE" = false ] && \
+   [ "$FOUND_COPILOT" = false ] && [ "$FOUND_CURSOR" = false ]; then
+    echo -e "${RED}ERROR: No supported AI tools found.${NC}"
+    echo ""
+    echo "Install one of the following:"
+    echo "  - Claude Code CLI:    https://claude.ai/download"
+    echo "  - Claude Code VSCode: Search 'Claude Code' in VSCode Extensions"
+    echo "  - Codex CLI:          npm install -g @openai/codex"
+    echo "  - Codex VSCode:       Search 'OpenAI Codex' in VSCode Extensions"
+    echo "  - GitHub Copilot:     Search 'GitHub Copilot' in VSCode Extensions"
+    echo "  - Cursor:             https://cursor.com"
+    echo ""
+    echo "Or force configuration if detection failed:"
+    echo "  curl -fsSL https://app.ctlsurf.com/install.sh | bash -s -- --force-codex"
+    echo "  curl -fsSL https://app.ctlsurf.com/install.sh | bash -s -- --force-claude"
+    echo "  curl -fsSL https://app.ctlsurf.com/install.sh | bash -s -- --force-copilot"
+    echo "  curl -fsSL https://app.ctlsurf.com/install.sh | bash -s -- --force-cursor"
+    exit 1
+fi
+
+# Check for existing API key in environment or shell profile
+EXISTING_KEY=""
+EXISTING_URL=""
+
+# Check env var
+if [ -n "$CTLSURF_API_KEY" ]; then
+    EXISTING_KEY="$CTLSURF_API_KEY"
+fi
+
+# Check shell profile
+if [ -z "$EXISTING_KEY" ]; then
+    for rc in "$HOME/.zshrc" "$HOME/.bashrc" "$HOME/.bash_profile"; do
+        if [ -f "$rc" ]; then
+            KEY_FROM_RC=$(grep '^export CTLSURF_API_KEY=' "$rc" 2>/dev/null | tail -1 | sed 's/^export CTLSURF_API_KEY="//' | sed 's/"$//')
+            if [ -n "$KEY_FROM_RC" ]; then
+                EXISTING_KEY="$KEY_FROM_RC"
+                break
+            fi
+        fi
+    done
+fi
+
+# Check CTLSURF_URL from env or profile
+if [ -n "$CTLSURF_URL" ]; then
+    EXISTING_URL="$CTLSURF_URL"
+else
+    for rc in "$HOME/.zshrc" "$HOME/.bashrc" "$HOME/.bash_profile"; do
+        if [ -f "$rc" ]; then
+            URL_FROM_RC=$(grep '^export CTLSURF_URL=' "$rc" 2>/dev/null | tail -1 | sed 's/^export CTLSURF_URL="//' | sed 's/"$//')
+            if [ -n "$URL_FROM_RC" ]; then
+                EXISTING_URL="$URL_FROM_RC"
+                break
+            fi
+        fi
+    done
+fi
+
+# Use existing credentials or prompt
+if [ -n "$EXISTING_KEY" ]; then
+    MASKED_KEY="${EXISTING_KEY:0:8}...${EXISTING_KEY: -4}"
+    echo -e "${GREEN}✓ Found existing API key: ${MASKED_KEY}${NC}"
+    echo -n "Use this key? (Y/n): "
+    read USE_EXISTING < /dev/tty
+    if [ -z "$USE_EXISTING" ] || [ "$USE_EXISTING" = "y" ] || [ "$USE_EXISTING" = "Y" ]; then
+        API_KEY="$EXISTING_KEY"
+    else
+        echo ""
+        echo "Get your API key from: https://app.ctlsurf.com/settings (API Keys tab)"
+        echo -n "Enter your ctlsurf API key: "
+        read API_KEY < /dev/tty
+    fi
+else
+    echo "Get your API key from: https://app.ctlsurf.com/settings (API Keys tab)"
+    echo -n "Enter your ctlsurf API key: "
+    read API_KEY < /dev/tty
+fi
+
+if [ -z "$API_KEY" ]; then
+    echo -e "${RED}ERROR: API key is required${NC}"
+    exit 1
+fi
+
+echo ""
+
+if [ -n "$EXISTING_URL" ]; then
+    # Strip /api/mcp suffix for display
+    DISPLAY_URL=$(echo "$EXISTING_URL" | sed 's|/api/mcp$||' | sed 's|/api$||')
+    echo -e "${GREEN}✓ Found existing server URL: ${DISPLAY_URL}${NC}"
+    echo -n "Use this URL? (Y/n): "
+    read USE_EXISTING_URL < /dev/tty
+    if [ -z "$USE_EXISTING_URL" ] || [ "$USE_EXISTING_URL" = "y" ] || [ "$USE_EXISTING_URL" = "Y" ]; then
+        SERVER_URL="$DISPLAY_URL"
+    else
+        echo -n "Server URL [https://app.ctlsurf.com]: "
+        read SERVER_URL < /dev/tty
+        SERVER_URL=${SERVER_URL:-https://app.ctlsurf.com}
+    fi
+else
+    echo -n "Server URL [https://app.ctlsurf.com]: "
+    read SERVER_URL < /dev/tty
+    SERVER_URL=${SERVER_URL:-https://app.ctlsurf.com}
+fi
+# Normalize URL
+SERVER_URL="${SERVER_URL%/}"
+SERVER_URL="${SERVER_URL%/api}"
+SERVER_URL="${SERVER_URL%/api/mcp}"
+MCP_URL="${SERVER_URL}/api/mcp"
+
+echo ""
+echo "Configuring ctlsurf..."
+echo ""
+
+# Persist API key to shell profile
+SHELL_PROFILE=""
+if [ -f "$HOME/.zshrc" ]; then
+    SHELL_PROFILE="$HOME/.zshrc"
+elif [ -f "$HOME/.bashrc" ]; then
+    SHELL_PROFILE="$HOME/.bashrc"
+elif [ -f "$HOME/.bash_profile" ]; then
+    SHELL_PROFILE="$HOME/.bash_profile"
+fi
+
+if [ -n "$SHELL_PROFILE" ]; then
+    # Remove existing CTLSURF exports
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        sed -i '' '/^export CTLSURF_/d' "$SHELL_PROFILE" 2>/dev/null || true
+    else
+        sed -i '/^export CTLSURF_/d' "$SHELL_PROFILE" 2>/dev/null || true
+    fi
+
+    # Add new exports
+    echo "" >> "$SHELL_PROFILE"
+    echo "# ctlsurf MCP configuration" >> "$SHELL_PROFILE"
+    echo "export CTLSURF_API_KEY=\"$API_KEY\"" >> "$SHELL_PROFILE"
+    echo "export CTLSURF_URL=\"$MCP_URL\"" >> "$SHELL_PROFILE"
+
+    echo -e "${GREEN}✓ Added API key to $SHELL_PROFILE${NC}"
+    echo ""
+fi
+
+CONFIGURED_COUNT=0
+CONFIGURED_TOOLS=""
+
+# ============================================================
+# Configure Claude Code CLI
+# ============================================================
+if [ "$FOUND_CLAUDE_CLI" = true ]; then
+    echo "Setting up Claude Code CLI..."
+
+    # Check for stale .mcp.json files that could shadow the user-level config
+    for MCP_JSON_PATH in "$HOME/.mcp.json" "./.mcp.json"; do
+        if [ -f "$MCP_JSON_PATH" ] && grep -q "ctlsurf" "$MCP_JSON_PATH" 2>/dev/null; then
+            # Check if it has an old stdio-based config (command-based, not HTTP)
+            if grep -q '"command"' "$MCP_JSON_PATH" 2>/dev/null && ! grep -q '"type".*"http"' "$MCP_JSON_PATH" 2>/dev/null; then
+                echo -e "${YELLOW}  ⚠ Found stale ctlsurf config in $MCP_JSON_PATH (old stdio transport)${NC}"
+                echo -e "${YELLOW}    This will shadow the HTTP config and cause connection failures.${NC}"
+                if command -v jq &> /dev/null; then
+                    # Remove ctlsurf entry from .mcp.json using jq
+                    TEMP_MCP_JSON=$(mktemp)
+                    jq 'del(.mcpServers.ctlsurf)' "$MCP_JSON_PATH" > "$TEMP_MCP_JSON" 2>/dev/null
+                    # If .mcp.json is now empty (no other servers), remove the file
+                    if jq -e '.mcpServers | length == 0' "$TEMP_MCP_JSON" &>/dev/null; then
+                        rm "$MCP_JSON_PATH"
+                        rm "$TEMP_MCP_JSON"
+                        echo -e "${GREEN}    Removed empty $MCP_JSON_PATH${NC}"
+                    else
+                        mv "$TEMP_MCP_JSON" "$MCP_JSON_PATH"
+                        echo -e "${GREEN}    Removed stale ctlsurf entry from $MCP_JSON_PATH${NC}"
+                    fi
+                else
+                    echo -e "${YELLOW}    Please remove ctlsurf from $MCP_JSON_PATH manually${NC}"
+                fi
+            fi
+        fi
+    done
+
+    # Remove existing config
+    claude mcp remove ctlsurf -s user 2>/dev/null || true
+    # Add HTTP MCP server
+    claude mcp add ctlsurf -s user --transport http "$MCP_URL" \
+        --header "Authorization: Bearer $API_KEY" 2>/dev/null || true
+
+    # Verify the config was actually persisted
+    CLAUDE_SETTINGS="$HOME/.claude/settings.json"
+    CLAUDE_CONFIG_OK=false
+    if [ -f "$CLAUDE_SETTINGS" ] && command -v jq &> /dev/null; then
+        if jq -e '.mcpServers.ctlsurf.url' "$CLAUDE_SETTINGS" &>/dev/null; then
+            CLAUDE_CONFIG_OK=true
+        fi
+    elif [ -f "$CLAUDE_SETTINGS" ] && grep -q "ctlsurf" "$CLAUDE_SETTINGS" 2>/dev/null; then
+        CLAUDE_CONFIG_OK=true
+    fi
+
+    # Fallback: write directly to settings.json if claude mcp add didn't persist
+    if [ "$CLAUDE_CONFIG_OK" = false ]; then
+        echo -e "${YELLOW}  claude mcp add didn't persist config, writing directly...${NC}"
+        mkdir -p "$HOME/.claude"
+
+        if command -v jq &> /dev/null; then
+            # Merge into existing settings.json using jq
+            if [ ! -f "$CLAUDE_SETTINGS" ] || [ ! -s "$CLAUDE_SETTINGS" ] || [ "$(cat "$CLAUDE_SETTINGS")" = "{}" ]; then
+                echo '{}' > "$CLAUDE_SETTINGS"
+            fi
+            TEMP_CLAUDE=$(mktemp)
+            MCP_CONFIG=$(cat <<EOF
+{
+    "type": "http",
+    "url": "$MCP_URL",
+    "headers": {
+        "Authorization": "Bearer $API_KEY"
+    }
+}
+EOF
+)
+            jq --argjson mcpConfig "$MCP_CONFIG" \
+               '.mcpServers.ctlsurf = $mcpConfig' \
+               "$CLAUDE_SETTINGS" > "$TEMP_CLAUDE" 2>/dev/null || \
+            jq --argjson mcpConfig "$MCP_CONFIG" \
+               '. + {"mcpServers": {"ctlsurf": $mcpConfig}}' \
+               "$CLAUDE_SETTINGS" > "$TEMP_CLAUDE"
+            mv "$TEMP_CLAUDE" "$CLAUDE_SETTINGS"
+        else
+            # No jq - write settings.json directly (only if empty or missing)
+            if [ ! -f "$CLAUDE_SETTINGS" ] || [ ! -s "$CLAUDE_SETTINGS" ] || [ "$(cat "$CLAUDE_SETTINGS")" = "{}" ]; then
+                cat > "$CLAUDE_SETTINGS" << EOF
+{
+  "mcpServers": {
+    "ctlsurf": {
+      "type": "http",
+      "url": "$MCP_URL",
+      "headers": {
+        "Authorization": "Bearer $API_KEY"
+      }
+    }
+  }
+}
+EOF
+            else
+                echo -e "${YELLOW}  ⚠ settings.json has existing config and jq is not available${NC}"
+                echo "  Please manually add ctlsurf to: $CLAUDE_SETTINGS"
+            fi
+        fi
+    fi
+
+    echo -e "${GREEN}✓ Claude Code CLI configured${NC}"
+    CONFIGURED_COUNT=$((CONFIGURED_COUNT + 1))
+    CONFIGURED_TOOLS="$CONFIGURED_TOOLS\n  - Claude Code CLI: Restart terminal to use"
+fi
+
+# ============================================================
+# Configure Claude Code VSCode Extension
+# ============================================================
+if [ "$FOUND_CLAUDE_VSCODE" = true ]; then
+    echo "Setting up Claude Code VSCode Extension..."
+
+    VSCODE_SETTINGS=$(get_vscode_settings_path)
+
+    if [ -n "$VSCODE_SETTINGS" ]; then
+        # Create settings directory if it doesn't exist
+        mkdir -p "$(dirname "$VSCODE_SETTINGS")"
+
+        # Create empty settings if file doesn't exist
+        if [ ! -f "$VSCODE_SETTINGS" ]; then
+            echo "{}" > "$VSCODE_SETTINGS"
+        fi
+
+        # Check if jq is available for safe JSON manipulation
+        if command -v jq &> /dev/null; then
+            # Use jq to safely update settings
+            TEMP_SETTINGS=$(mktemp)
+
+            # Create the MCP server config
+            MCP_CONFIG=$(cat <<EOF
+{
+    "type": "http",
+    "url": "$MCP_URL",
+    "headers": {
+        "Authorization": "Bearer $API_KEY"
+    }
+}
+EOF
+)
+            # Update settings with new MCP config
+            jq --argjson mcpConfig "$MCP_CONFIG" \
+               '.["claude-code.mcpServers"].ctlsurf = $mcpConfig' \
+               "$VSCODE_SETTINGS" > "$TEMP_SETTINGS" 2>/dev/null || \
+            jq --argjson mcpConfig "$MCP_CONFIG" \
+               '. + {"claude-code.mcpServers": {"ctlsurf": $mcpConfig}}' \
+               "$VSCODE_SETTINGS" > "$TEMP_SETTINGS"
+
+            mv "$TEMP_SETTINGS" "$VSCODE_SETTINGS"
+            echo -e "${GREEN}✓ Claude Code VSCode configured${NC}"
+            echo "  Config: $VSCODE_SETTINGS"
+        else
+            # Fallback: provide manual instructions
+            echo -e "${YELLOW}⚠ jq not found - manual configuration required${NC}"
+            echo ""
+            echo "Add this to your VSCode settings.json:"
+            echo ""
+            echo -e "${BLUE}\"claude-code.mcpServers\": {"
+            echo "    \"ctlsurf\": {"
+            echo "        \"type\": \"http\","
+            echo "        \"url\": \"$MCP_URL\","
+            echo "        \"headers\": {"
+            echo "            \"Authorization\": \"Bearer $API_KEY\""
+            echo "        }"
+            echo "    }"
+            echo -e "}${NC}"
+            echo ""
+            echo "Settings file: $VSCODE_SETTINGS"
+        fi
+        CONFIGURED_COUNT=$((CONFIGURED_COUNT + 1))
+        CONFIGURED_TOOLS="$CONFIGURED_TOOLS\n  - Claude Code VSCode: Reload VSCode window"
+    else
+        echo -e "${YELLOW}⚠ Could not determine VSCode settings path${NC}"
+    fi
+fi
+
+# ============================================================
+# Configure Codex CLI
+# ============================================================
+if [ "$FOUND_CODEX_CLI" = true ]; then
+    echo "Setting up OpenAI Codex CLI..."
+
+    CODEX_CONFIG_DIR="$HOME/.codex"
+    CODEX_CONFIG="$CODEX_CONFIG_DIR/config.toml"
+
+    # Create config directory if needed
+    mkdir -p "$CODEX_CONFIG_DIR"
+
+    # Remove existing ctlsurf config if present (use awk for reliable multi-line TOML block removal)
+    if [ -f "$CODEX_CONFIG" ] && grep -q "\[mcp_servers.ctlsurf\]" "$CODEX_CONFIG" 2>/dev/null; then
+        # awk approach: skip lines from [mcp_servers.ctlsurf] until next section or EOF
+        awk '
+            /^\[mcp_servers\.ctlsurf\]/ { skip=1; next }
+            /^\[/ { skip=0 }
+            !skip { print }
+        ' "$CODEX_CONFIG" > "$CODEX_CONFIG.tmp" && mv "$CODEX_CONFIG.tmp" "$CODEX_CONFIG"
+    fi
+
+    # Ensure config file exists
+    touch "$CODEX_CONFIG"
+
+    # Append ctlsurf HTTP configuration (Codex format)
+    cat >> "$CODEX_CONFIG" << EOF
+
+# ctlsurf (Control Surface) MCP Server - HTTP Transport
+[mcp_servers.ctlsurf]
+url = "$MCP_URL"
+http_headers = { "Authorization" = "Bearer $API_KEY" }
+EOF
+
+    echo -e "${GREEN}✓ Codex CLI configured${NC}"
+    echo "  Config: $CODEX_CONFIG"
+    CONFIGURED_COUNT=$((CONFIGURED_COUNT + 1))
+    CONFIGURED_TOOLS="$CONFIGURED_TOOLS\n  - Codex CLI: Run 'codex' and type /mcp to verify"
+fi
+
+# ============================================================
+# Configure Codex/ChatGPT VSCode Extension
+# ============================================================
+if [ "$FOUND_CODEX_VSCODE" = true ]; then
+    echo "Setting up OpenAI ChatGPT VSCode Extension..."
+
+    VSCODE_SETTINGS=$(get_vscode_settings_path)
+
+    if [ -n "$VSCODE_SETTINGS" ]; then
+        # Create settings directory if it doesn't exist
+        mkdir -p "$(dirname "$VSCODE_SETTINGS")"
+
+        # Create empty settings if file doesn't exist
+        if [ ! -f "$VSCODE_SETTINGS" ]; then
+            echo "{}" > "$VSCODE_SETTINGS"
+        fi
+
+        # Check if jq is available for safe JSON manipulation
+        if command -v jq &> /dev/null; then
+            # Use jq to safely update settings
+            TEMP_SETTINGS=$(mktemp)
+
+            # Create the MCP server config for ChatGPT
+            MCP_CONFIG=$(cat <<EOF
+{
+    "type": "http",
+    "url": "$MCP_URL",
+    "headers": {
+        "Authorization": "Bearer $API_KEY"
+    }
+}
+EOF
+)
+            # Update settings with new MCP config (chatgpt.mcpServers)
+            jq --argjson mcpConfig "$MCP_CONFIG" \
+               '.["chatgpt.mcpServers"].ctlsurf = $mcpConfig' \
+               "$VSCODE_SETTINGS" > "$TEMP_SETTINGS" 2>/dev/null || \
+            jq --argjson mcpConfig "$MCP_CONFIG" \
+               '. + {"chatgpt.mcpServers": {"ctlsurf": $mcpConfig}}' \
+               "$VSCODE_SETTINGS" > "$TEMP_SETTINGS"
+
+            mv "$TEMP_SETTINGS" "$VSCODE_SETTINGS"
+            echo -e "${GREEN}✓ ChatGPT VSCode configured${NC}"
+            echo "  Config: $VSCODE_SETTINGS"
+        else
+            # Fallback: provide manual instructions
+            echo -e "${YELLOW}⚠ jq not found - manual configuration required${NC}"
+            echo ""
+            echo "Add this to your VSCode settings.json:"
+            echo ""
+            echo -e "${BLUE}\"chatgpt.mcpServers\": {"
+            echo "    \"ctlsurf\": {"
+            echo "        \"type\": \"http\","
+            echo "        \"url\": \"$MCP_URL\","
+            echo "        \"headers\": {"
+            echo "            \"Authorization\": \"Bearer $API_KEY\""
+            echo "        }"
+            echo "    }"
+            echo -e "}${NC}"
+            echo ""
+            echo "Settings file: $VSCODE_SETTINGS"
+        fi
+        CONFIGURED_COUNT=$((CONFIGURED_COUNT + 1))
+        CONFIGURED_TOOLS="$CONFIGURED_TOOLS\n  - ChatGPT VSCode: Reload VSCode window"
+    else
+        echo -e "${YELLOW}⚠ Could not determine VSCode settings path${NC}"
+    fi
+fi
+
+# ============================================================
+# Configure GitHub Copilot VSCode Extension
+# ============================================================
+if [ "$FOUND_COPILOT" = true ]; then
+    echo "Setting up GitHub Copilot VSCode Extension..."
+
+    VSCODE_MCP=$(get_vscode_mcp_path)
+
+    if [ -n "$VSCODE_MCP" ]; then
+        # Create config directory if it doesn't exist
+        mkdir -p "$(dirname "$VSCODE_MCP")"
+
+        # Create empty mcp.json if file doesn't exist
+        if [ ! -f "$VSCODE_MCP" ]; then
+            echo '{"servers":{}}' > "$VSCODE_MCP"
+        fi
+
+        # Check if jq is available for safe JSON manipulation
+        if command -v jq &> /dev/null; then
+            # Use jq to safely update mcp.json
+            TEMP_MCP=$(mktemp)
+
+            # Create the MCP server config for Copilot
+            MCP_CONFIG=$(cat <<EOF
+{
+    "type": "http",
+    "url": "$MCP_URL",
+    "headers": {
+        "Authorization": "Bearer $API_KEY"
+    }
+}
+EOF
+)
+            # Update mcp.json with new config
+            # Copilot uses { "servers": { "name": { ... } } } format
+            jq --argjson mcpConfig "$MCP_CONFIG" \
+               '.servers.ctlsurf = $mcpConfig' \
+               "$VSCODE_MCP" > "$TEMP_MCP" 2>/dev/null || \
+            jq --argjson mcpConfig "$MCP_CONFIG" \
+               '. + {"servers": {"ctlsurf": $mcpConfig}}' \
+               "$VSCODE_MCP" > "$TEMP_MCP"
+
+            mv "$TEMP_MCP" "$VSCODE_MCP"
+            echo -e "${GREEN}✓ GitHub Copilot configured${NC}"
+            echo "  Config: $VSCODE_MCP"
+        else
+            # Fallback: provide manual instructions
+            echo -e "${YELLOW}⚠ jq not found - manual configuration required${NC}"
+            echo ""
+            echo "Create or edit: $VSCODE_MCP"
+            echo ""
+            echo -e "${BLUE}{"
+            echo "    \"servers\": {"
+            echo "        \"ctlsurf\": {"
+            echo "            \"type\": \"http\","
+            echo "            \"url\": \"$MCP_URL\","
+            echo "            \"headers\": {"
+            echo "                \"Authorization\": \"Bearer $API_KEY\""
+            echo "            }"
+            echo "        }"
+            echo "    }"
+            echo -e "}${NC}"
+        fi
+        CONFIGURED_COUNT=$((CONFIGURED_COUNT + 1))
+        CONFIGURED_TOOLS="$CONFIGURED_TOOLS\n  - GitHub Copilot: Reload VSCode window"
+    else
+        echo -e "${YELLOW}⚠ Could not determine VSCode mcp.json path${NC}"
+    fi
+fi
+
+# ============================================================
+# Configure Cursor Editor
+# ============================================================
+if [ "$FOUND_CURSOR" = true ]; then
+    echo "Setting up Cursor Editor..."
+
+    CURSOR_CONFIG_DIR="$HOME/.cursor"
+    CURSOR_MCP="$CURSOR_CONFIG_DIR/mcp.json"
+
+    # Create config directory if needed
+    mkdir -p "$CURSOR_CONFIG_DIR"
+
+    # Create empty mcp.json if file doesn't exist
+    if [ ! -f "$CURSOR_MCP" ]; then
+        echo '{"mcpServers":{}}' > "$CURSOR_MCP"
+    fi
+
+    # Check if jq is available for safe JSON manipulation
+    if command -v jq &> /dev/null; then
+        # Use jq to safely update mcp.json
+        TEMP_MCP=$(mktemp)
+
+        # Create the MCP server config for Cursor
+        # Cursor uses { "mcpServers": { "name": { url, headers } } } format (no "type" field for HTTP)
+        MCP_CONFIG=$(cat <<EOF
+{
+    "url": "$MCP_URL",
+    "headers": {
+        "Authorization": "Bearer $API_KEY"
+    }
+}
+EOF
+)
+        # Update mcp.json with new config
+        jq --argjson mcpConfig "$MCP_CONFIG" \
+           '.mcpServers.ctlsurf = $mcpConfig' \
+           "$CURSOR_MCP" > "$TEMP_MCP" 2>/dev/null || \
+        jq --argjson mcpConfig "$MCP_CONFIG" \
+           '. + {"mcpServers": {"ctlsurf": $mcpConfig}}' \
+           "$CURSOR_MCP" > "$TEMP_MCP"
+
+        mv "$TEMP_MCP" "$CURSOR_MCP"
+        echo -e "${GREEN}✓ Cursor configured${NC}"
+        echo "  Config: $CURSOR_MCP"
+    else
+        # Fallback: provide manual instructions
+        echo -e "${YELLOW}⚠ jq not found - manual configuration required${NC}"
+        echo ""
+        echo "Create or edit: $CURSOR_MCP"
+        echo ""
+        echo -e "${BLUE}{"
+        echo "    \"mcpServers\": {"
+        echo "        \"ctlsurf\": {"
+        echo "            \"url\": \"$MCP_URL\","
+        echo "            \"headers\": {"
+        echo "                \"Authorization\": \"Bearer $API_KEY\""
+        echo "            }"
+        echo "        }"
+        echo "    }"
+        echo -e "}${NC}"
+    fi
+    CONFIGURED_COUNT=$((CONFIGURED_COUNT + 1))
+    CONFIGURED_TOOLS="$CONFIGURED_TOOLS\n  - Cursor: Restart Cursor to use"
+fi
+
+echo ""
+echo "========================================"
+echo -e "${GREEN}  Setup Complete!${NC}"
+echo "========================================"
+echo ""
+echo "Server:   $SERVER_URL"
+echo "Endpoint: $MCP_URL"
+echo "Tools configured: $CONFIGURED_COUNT"
+echo ""
+
+if [ -n "$SHELL_PROFILE" ]; then
+    echo "To use the API key in current shell:"
+    echo "  source $SHELL_PROFILE"
+    echo ""
+fi
+
+if [ -n "$CONFIGURED_TOOLS" ]; then
+    echo "Next steps:"
+    echo -e "$CONFIGURED_TOOLS"
+    echo ""
+fi