patchwork-os 0.2.0-alpha.0

package/scripts/gen-mcp-config.sh

@@ -0,0 +1,390 @@
+#!/usr/bin/env bash
+# Generate MCP configuration for connecting an IDE or agent to the claude-ide-bridge.
+#
+# Usage:
+#   bash scripts/gen-mcp-config.sh <target> [--write]
+#
+# Targets:
+#   cursor           Outputs .cursor/mcp.json content
+#   antigravity      Outputs mcp_config.json content for Google Antigravity
+#   codex            Outputs ~/.codex/config.toml section for OpenAI Codex CLI
+#   claude-desktop   Outputs claude_desktop_config.json entry for Claude Desktop app
+#
+# Flags:
+#   --write       Write the config to the correct location (asks confirmation)
+#
+# Example:
+#   bash scripts/gen-mcp-config.sh cursor
+#   bash scripts/gen-mcp-config.sh codex --write
+#   bash scripts/gen-mcp-config.sh claude-web --host mybridge.example.com --token <tok>
+
+set -euo pipefail
+
+CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+LOCK_DIR="$CLAUDE_DIR/ide"
+
+TARGET="${1:-}"
+WRITE=false
+REMOTE_HOST=""
+REMOTE_TOKEN=""
+
+# Parse flags (handle --host <val> and --token <val> for the remote target)
+_argv=("$@")
+for (( _i=1; _i<${#_argv[@]}; _i++ )); do
+  case "${_argv[$_i]}" in
+    --write) WRITE=true ;;
+    --host)  REMOTE_HOST="${_argv[$((_i+1))]:-}"; ((_i++)) ;;
+    --token) REMOTE_TOKEN="${_argv[$((_i+1))]:-}"; ((_i++)) ;;
+  esac
+done
+
+# --- Usage ---
+if [[ -z "$TARGET" || "$TARGET" == "--help" || "$TARGET" == "-h" ]]; then
+  echo "Usage: $0 <target> [--write]"
+  echo ""
+  echo "Targets: cursor | antigravity | codex | claude-desktop | remote | claude-web"
+  echo "  cursor           .cursor/mcp.json"
+  echo "  antigravity      mcp_config.json for Google Antigravity"
+  echo "  codex            ~/.codex/config.toml section for OpenAI Codex CLI"
+  echo "  claude-desktop   claude_desktop_config.json for Claude Desktop app"
+  echo "  remote           Merges a remote bridge entry into the nearest .mcp.json (or ~/.claude/mcp.json)"
+  echo "                   Requires: --host <host:port> --token <token>"
+  echo "  claude-web       Custom Connector snippet for claude.ai web"
+  echo "                   Requires: --host <host:port> --token <token>"
+  echo ""
+  echo "Flags:"
+  echo "  --write          Write config to the correct location (not applicable for claude-web)"
+  echo "  --host <h:port>  Remote host and port (remote / claude-web targets)"
+  echo "  --token <tok>    Auth token (remote / claude-web targets; get via: claude-ide-bridge print-token)"
+  exit 0
+fi
+
+# --- Find the most recent valid lock file ---
+find_lock() {
+  local best_lock=""
+  local best_mtime=0
+  local locks
+  locks=$(find "$LOCK_DIR" -maxdepth 1 -name "*.lock" 2>/dev/null) || true
+  for lock in $locks; do
+    [[ -f "$lock" ]] || continue
+    mtime=$(stat -f "%m" "$lock" 2>/dev/null || stat -c "%Y" "$lock" 2>/dev/null || echo 0)
+    if (( mtime > best_mtime )); then
+      best_mtime=$mtime
+      best_lock=$lock
+    fi
+  done
+  echo "$best_lock"
+}
+
+# claude-desktop target does not need a running bridge -- delegate to the dedicated script
+if [[ "$TARGET" == "claude-desktop" ]]; then
+  DEDICATED="${BASH_SOURCE[0]%/*}/gen-claude-desktop-config.sh"
+  if [[ -f "$DEDICATED" ]]; then
+    exec bash "$DEDICATED" ${WRITE:+--write}
+  fi
+  # Fallback inline if dedicated script is missing
+  SHIM_PATH="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/mcp-stdio-shim.cjs"
+  if [[ "$(uname)" == "Darwin" ]]; then
+    OUTPUT_PATH="${HOME}/Library/Application Support/Claude/claude_desktop_config.json"
+  else
+    OUTPUT_PATH="${APPDATA:-${HOME}/.config}/Claude/claude_desktop_config.json"
+  fi
+  CONFIG=$(SHIM_PATH="$SHIM_PATH" python3 - <<'PYEOF'
+import json, os
+shim = os.environ["SHIM_PATH"]
+print(json.dumps({"mcpServers": {"claude-ide-bridge": {"command": "node", "args": [shim]}}}, indent=2))
+PYEOF
+)
+  echo "=== Claude Desktop MCP config ==="
+  echo "Path: $OUTPUT_PATH"
+  echo ""
+  echo "$CONFIG"
+  echo ""
+  echo "The shim auto-discovers the running bridge via lock files."
+  echo "Restart Claude Desktop after writing the config."
+  if $WRITE; then
+    TMP_PATH="${OUTPUT_PATH}.tmp"
+    mkdir -p "$(dirname "$OUTPUT_PATH")"
+    if [[ -f "$OUTPUT_PATH" ]]; then
+      cp "$OUTPUT_PATH" "${OUTPUT_PATH}.$(date +%Y%m%d%H%M%S).bak"
+    fi
+    printf '%s\n' "$CONFIG" > "$TMP_PATH"
+    mv "$TMP_PATH" "$OUTPUT_PATH"
+    echo "Written: $OUTPUT_PATH"
+  fi
+  exit 0
+fi
+
+# --- Remote target: no lock file needed — caller supplies host and token ---
+if [[ "$TARGET" == "remote" ]]; then
+  if [[ -z "$REMOTE_HOST" || -z "$REMOTE_TOKEN" ]]; then
+    echo "Error: 'remote' target requires --host <host:port> and --token <token>" >&2
+    echo "  Example: bash gen-mcp-config.sh remote --host mybridge.example.com:8080 --token abc123 --write" >&2
+    exit 1
+  fi
+  OUTPUT_PATH="${HOME}/.claude/mcp.json"
+  CONFIG=$(cat <<EOF
+{
+  "mcpServers": {
+    "claude-ide-bridge-remote": {
+      "type": "http",
+      "url": "http://${REMOTE_HOST}/mcp",
+      "headers": {
+        "Authorization": "Bearer ${REMOTE_TOKEN}"
+      }
+    }
+  }
+}
+EOF
+)
+  # WARNING: Ephemeral tunnels (trycloudflare.com) generate a new URL on every restart.
+  # Any MCP config using this URL will break when the tunnel restarts.
+  # For stable remote access, use a fixed domain with --fixed-token.
+  if [[ "$REMOTE_HOST" == *".trycloudflare.com"* ]]; then
+    echo "⚠️  WARNING: trycloudflare.com tunnels are ephemeral — the URL changes every time" >&2
+    echo "   cloudflared restarts. Your MCP config will break on the next restart." >&2
+    echo "   For a permanent URL, use a named tunnel:" >&2
+    echo "     cloudflared tunnel login" >&2
+    echo "     cloudflared tunnel create my-bridge" >&2
+    echo "     cloudflared tunnel route dns my-bridge bridge.yourdomain.com" >&2
+    echo "   See the README (Cloudflare section) for the full setup guide." >&2
+    echo "" >&2
+  fi
+
+  echo "=== Remote bridge MCP config ==="
+  echo "Bridge: http://${REMOTE_HOST}/mcp"
+  echo ""
+  echo "$CONFIG"
+  echo ""
+  echo "Note: Use HTTPS in production — put nginx or Caddy in front with TLS."
+  echo "Tip:  Claude Code supports \${VAR:-default} in .mcp.json. Replace the token value"
+  echo "      with \${BRIDGE_TOKEN} and set BRIDGE_TOKEN in your shell profile to avoid"
+  echo "      storing the token in the config file. See docs/remote-access.md for details."
+  echo ""
+  echo "⚠️  IMPORTANT: Start your bridge with --fixed-token <uuid> (or CLAUDE_IDE_BRIDGE_TOKEN=<uuid>)"
+  echo "   to keep this token stable across restarts. Without it, the bridge generates a new"
+  echo "   token on every restart and this MCP config will stop working immediately."
+  echo "   Example: claude-ide-bridge --bind 0.0.0.0 --fixed-token \$BRIDGE_TOKEN --workspace /path/to/project"
+  if $WRITE; then
+    # Find the nearest .mcp.json (walk up from cwd, fallback to ~/.claude/mcp.json)
+    _find_mcp_json() {
+      local dir="$PWD"
+      while [[ "$dir" != "/" ]]; do
+        [[ -f "$dir/.mcp.json" ]] && echo "$dir/.mcp.json" && return
+        dir="$(dirname "$dir")"
+      done
+      echo "${HOME}/.claude/mcp.json"
+    }
+    OUTPUT_PATH="$(_find_mcp_json)"
+
+    # Merge the new server entry into the existing file (python3 required)
+    if command -v python3 >/dev/null 2>&1; then
+      MERGE_HOST="$REMOTE_HOST" MERGE_TOKEN="$REMOTE_TOKEN" OUTPUT_PATH="$OUTPUT_PATH" python3 - <<'PYEOF'
+import json, os, sys
+path = os.environ["OUTPUT_PATH"]
+host = os.environ["MERGE_HOST"]
+token = os.environ["MERGE_TOKEN"]
+try:
+    with open(path) as f:
+        existing = json.load(f)
+except (FileNotFoundError, json.JSONDecodeError):
+    existing = {}
+existing.setdefault("mcpServers", {})["claude-ide-bridge-remote"] = {
+    "type": "http",
+    "url": f"http://{host}/mcp",
+    "headers": {"Authorization": f"Bearer {token}"}
+}
+tmp = path + ".tmp"
+with open(tmp, "w") as f:
+    json.dump(existing, f, indent=2)
+    f.write("\n")
+os.replace(tmp, path)
+print(f"Written: {path}")
+PYEOF
+    else
+      # Fallback: write standalone file
+      TMP_PATH="${OUTPUT_PATH}.tmp"
+      mkdir -p "$(dirname "$OUTPUT_PATH")"
+      printf '%s\n' "$CONFIG" > "$TMP_PATH"
+      mv "$TMP_PATH" "$OUTPUT_PATH"
+      echo "Written: $OUTPUT_PATH"
+    fi
+  fi
+  exit 0
+fi
+
+# --- Claude.ai Web Custom Connector target ---
+if [[ "$TARGET" == "claude-web" ]]; then
+  if [[ -z "$REMOTE_HOST" || -z "$REMOTE_TOKEN" ]]; then
+    echo "Error: claude-web target requires --host <host:port> and --token <token>" >&2
+    echo "  The bridge must be behind a reverse proxy with TLS for claude.ai to reach it." >&2
+    echo "  Get the token with: claude-ide-bridge print-token" >&2
+    exit 1
+  fi
+  # Warn when using an ephemeral trycloudflare.com tunnel
+  if [[ "$REMOTE_HOST" == *".trycloudflare.com"* ]]; then
+    echo "⚠️  WARNING: trycloudflare.com tunnels are ephemeral — the URL changes every time" >&2
+    echo "   cloudflared restarts. Your connector URL will break on the next restart." >&2
+    echo "   For a permanent URL, use a named tunnel:" >&2
+    echo "     cloudflared tunnel login" >&2
+    echo "     cloudflared tunnel create my-bridge" >&2
+    echo "     cloudflared tunnel route dns my-bridge bridge.yourdomain.com" >&2
+    echo "   See the README (Cloudflare section) for the full setup guide." >&2
+    echo "" >&2
+  fi
+
+  # claude.ai Custom Connectors use HTTPS — warn if http:// is implied (no scheme in host)
+  if [[ "$REMOTE_HOST" != https://* && "$REMOTE_HOST" != http://* ]]; then
+    CONNECTOR_URL="https://${REMOTE_HOST}/mcp"
+  else
+    CONNECTOR_URL="${REMOTE_HOST}/mcp"
+  fi
+  echo "=== claude.ai Web — Custom Connector settings ==="
+  echo ""
+  echo "1. Go to claude.ai → Settings → Custom Connectors → Add connector"
+  echo "2. Enter the following:"
+  echo ""
+  echo "   Name:      Claude IDE Bridge"
+  echo "   URL:       ${CONNECTOR_URL}"
+  echo "   Auth:      Bearer token"
+  echo "   Token:     ${REMOTE_TOKEN}"
+  echo ""
+  echo "Note: The bridge must be reachable over HTTPS from the public internet."
+  echo "      See docs/remote-access.md for a production-ready Caddy/nginx TLS setup."
+  echo "Tip:  Rotate the token with: claude-ide-bridge rotate-token"
+  echo "      Then update the connector's token in claude.ai settings."
+  exit 0
+fi
+
+LOCK_FILE=$(find_lock)
+
+if [[ -z "$LOCK_FILE" ]]; then
+  echo "Error: No bridge lock file found in $LOCK_DIR" >&2
+  echo "Make sure the bridge is running first: npm run start-all" >&2
+  exit 1
+fi
+
+# Parse lock file (requires python3 or jq)
+# Passes $LOCK_FILE and $field via env vars to avoid shell injection in -c string
+parse_lock() {
+  local field="$1"
+  if command -v python3 >/dev/null 2>&1; then
+    LOCK_FILE="$LOCK_FILE" LOCK_FIELD="$field" python3 - <<'PYEOF'
+import json, os
+with open(os.environ["LOCK_FILE"]) as f:
+    d = json.load(f)
+print(d[os.environ["LOCK_FIELD"]])
+PYEOF
+  elif command -v jq >/dev/null 2>&1; then
+    jq -r --arg f "$field" '.[$f]' "$LOCK_FILE"
+  else
+    echo "Error: python3 or jq is required to parse the bridge lock file." >&2
+    echo "  Install python3: brew install python3 (macOS) or apt install python3 (Linux)" >&2
+    echo "  Install jq: brew install jq (macOS) or apt install jq (Linux)" >&2
+    exit 1
+  fi
+}
+
+PORT=$(basename "$LOCK_FILE" .lock)
+AUTH_TOKEN=$(parse_lock "authToken")
+
+WS_URL="ws://127.0.0.1:${PORT}"
+HTTP_URL="http://127.0.0.1:${PORT}"
+
+echo "Found bridge: port=${PORT} lock=$(basename "$LOCK_FILE")"
+echo ""
+
+# --- Generate config per target ---
+case "$TARGET" in
+  cursor)
+    OUTPUT_PATH="${HOME}/.cursor/mcp.json"
+    CONFIG=$(cat <<EOF
+{
+  "mcpServers": {
+    "claude-ide-bridge": {
+      "url": "${WS_URL}",
+      "headers": {
+        "x-claude-ide-extension": "${AUTH_TOKEN}"
+      }
+    }
+  }
+}
+EOF
+)
+    echo "=== Cursor MCP config (.cursor/mcp.json or project/.cursor/mcp.json) ==="
+    echo "$CONFIG"
+    ;;
+
+  antigravity)
+    OUTPUT_PATH="${HOME}/.antigravity/mcp_config.json"
+    CONFIG=$(cat <<EOF
+{
+  "mcpServers": {
+    "claude-ide-bridge": {
+      "transport": "websocket",
+      "url": "${WS_URL}",
+      "headers": {
+        "x-claude-ide-extension": "${AUTH_TOKEN}"
+      }
+    }
+  }
+}
+EOF
+)
+    echo "=== Google Antigravity MCP config ==="
+    echo "(In Antigravity: Agent session → dropdown → Manage MCP Servers → edit mcp_config.json)"
+    echo ""
+    echo "$CONFIG"
+    ;;
+
+  codex)
+    OUTPUT_PATH="${HOME}/.codex/config.toml"
+    # Codex CLI supports stdio and streamable HTTP — use the bridge's HTTP endpoint
+    # Auth uses Authorization: Bearer (not x-claude-ide-extension, which is for WS extension sessions)
+    CONFIG=$(cat <<EOF
+# Add this to ~/.codex/config.toml to connect to claude-ide-bridge
+# The bridge must be running before starting codex.
+
+[mcp_servers.claude-ide-bridge]
+# Streamable HTTP transport (bridge HTTP server)
+url = "${HTTP_URL}/mcp"
+http_headers = { "Authorization" = "Bearer ${AUTH_TOKEN}" }
+enabled = true
+EOF
+)
+    echo "=== OpenAI Codex CLI MCP config (~/.codex/config.toml) ==="
+    echo "$CONFIG"
+    echo ""
+    echo "Note: Retrieve the auth token from the lock file at: $LOCK_FILE"
+    ;;
+
+  *)
+    echo "Error: Unknown target '$TARGET'. Use: cursor | antigravity | codex | claude-desktop | remote | claude-web" >&2
+    exit 1
+    ;;
+esac
+
+# --- Write mode ---
+if $WRITE; then
+  echo ""
+  echo "Write to: $OUTPUT_PATH"
+  read -r -p "Confirm? [y/N] " confirm
+  if [[ "$confirm" =~ ^[Yy]$ ]]; then
+    mkdir -p "$(dirname "$OUTPUT_PATH")"
+    # Timestamped backup so repeated --write calls don't clobber each other
+    if [[ -f "$OUTPUT_PATH" ]]; then
+      BACKUP="${OUTPUT_PATH}.$(date +%Y%m%d%H%M%S).bak"
+      cp "$OUTPUT_PATH" "$BACKUP"
+      echo "Backed up existing config to $(basename "$BACKUP")"
+    fi
+    # Atomic write via tmp file to prevent partial writes on interrupt
+    TMP_FILE="$(mktemp)"
+    trap 'rm -f "$TMP_FILE"' EXIT
+    TMP_PATH="${OUTPUT_PATH}.tmp"
+    printf '%s\n' "$CONFIG" > "$TMP_PATH"
+    mv "$TMP_PATH" "$OUTPUT_PATH"
+    echo "Written: $OUTPUT_PATH"
+  else
+    echo "Aborted."
+  fi
+fi

package/scripts/install-extension.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Install the claude-ide-bridge VS Code extension into a supported IDE.
+#
+# Usage:
+#   bash scripts/install-extension.sh [--ide <ide>] [--build]
+#
+# Supported IDEs:
+#   windsurf     Windsurf (default if detected)
+#   cursor       Cursor
+#   antigravity  Google Antigravity
+#   code         VS Code
+#
+# Flags:
+#   --ide <name>   Specify target IDE (auto-detects if omitted)
+#   --build        Rebuild extension + VSIX before installing
+#
+# Example:
+#   bash scripts/install-extension.sh --ide cursor
+#   bash scripts/install-extension.sh --ide antigravity --build
+
+set -euo pipefail
+
+BRIDGE_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+VSIX_DIR="$BRIDGE_DIR/vscode-extension"
+IDE=""
+DO_BUILD=false
+
+# --- Parse args ---
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --ide)    IDE="$2"; shift 2 ;;
+    --build)  DO_BUILD=true; shift ;;
+    --help|-h)
+      echo "Usage: $0 [--ide <windsurf|cursor|antigravity|code>] [--build]"
+      exit 0
+      ;;
+    *) echo "Unknown option: $1" >&2; exit 1 ;;
+  esac
+done
+
+# --- Auto-detect IDE if not specified ---
+detect_ide() {
+  for cmd in windsurf cursor antigravity ag code; do
+    command -v "$cmd" >/dev/null 2>&1 && echo "$cmd" && return
+  done
+  echo ""
+}
+
+if [[ -z "$IDE" ]]; then
+  IDE=$(detect_ide)
+  if [[ -z "$IDE" ]]; then
+    echo "Error: Could not auto-detect a supported IDE on PATH." >&2
+    echo "Specify one with --ide <windsurf|cursor|antigravity|code>" >&2
+    exit 1
+  fi
+  echo "Auto-detected IDE: $IDE"
+fi
+
+# Normalise alias
+[[ "$IDE" == "ag" ]] && IDE="antigravity"
+
+# --- Map IDE to its install CLI command ---
+case "$IDE" in
+  windsurf)    INSTALL_CMD="windsurf" ;;
+  cursor)      INSTALL_CMD="cursor" ;;
+  antigravity) INSTALL_CMD="antigravity" ;;
+  code)        INSTALL_CMD="code" ;;
+  *)
+    echo "Error: Unsupported IDE '$IDE'. Use: windsurf | cursor | antigravity | code" >&2
+    exit 1
+    ;;
+esac
+
+# Verify the CLI is available
+command -v "$INSTALL_CMD" >/dev/null 2>&1 || {
+  echo "Error: '$INSTALL_CMD' not found on PATH." >&2
+  echo "Make sure $IDE is installed and its CLI is on your PATH." >&2
+  exit 1
+}
+
+# --- Build if requested ---
+if $DO_BUILD; then
+  echo "Building extension..."
+  (cd "$VSIX_DIR" && npm run build && npm run package)
+  echo ""
+fi
+
+# --- Find the VSIX ---
+VSIX_COUNT=$(ls "$VSIX_DIR"/*.vsix 2>/dev/null | wc -l | tr -d ' ')
+if [ "$VSIX_COUNT" -gt 1 ]; then
+  echo "Warning: Found $VSIX_COUNT .vsix files — using newest. Run with --build to rebuild." >&2
+fi
+VSIX=$(ls -t "$VSIX_DIR"/*.vsix 2>/dev/null | head -1)
+if [[ -z "$VSIX" ]]; then
+  echo "Error: No .vsix file found in $VSIX_DIR" >&2
+  echo "Run with --build to build it first, or: cd vscode-extension && npm run package" >&2
+  exit 1
+fi
+
+echo "Installing $(basename "$VSIX") into $IDE..."
+# --force reinstalls even if already installed (needed for upgrades)
+"$INSTALL_CMD" --install-extension "$VSIX" --force
+
+echo ""
+echo "Done. To activate: restart your IDE, or open the Command Palette (Cmd+Shift+P on Mac / Ctrl+Shift+P on Windows/Linux) and run 'Developer: Reload Window'."
+echo "The extension will auto-connect to any running bridge."