claude-ide-bridge 2.22.7 → 2.22.8

package/deploy/README.md

@@ -0,0 +1,172 @@
+# Deploy
+
+Production VPS deployment files for claude-ide-bridge.
+
+> **Deployment targets:** The **systemd + nginx** path (this directory) is the
+> production-supported deployment for VPS/remote use. A `Dockerfile` and
+> `docker-compose.yml` exist in the repo root as an alternative for
+> containerised environments, but are not actively tested against the systemd
+> config — if you use Docker, treat it as a community-supported path and keep
+> it in sync with any service config changes.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `bootstrap-new-vps.sh` | **Full fresh-server setup** — Node.js, clone, build, user, firewall, systemd, nginx, Certbot |
+| `install-vps-service.sh` | **Idempotent updater** — re-installs service + nginx after `git pull` on an existing server |
+| `nginx-claude-bridge.conf.template` | nginx config reference (domain + port injected by scripts) |
+| `claude-ide-bridge.service.template` | systemd unit reference (paths + user injected by scripts) |
+| `claude-ide-bridge@.service` | Template unit for multi-user demo instances (alternate pattern) |
+| `ecosystem.config.js.example` | PM2 ecosystem config template (alternative to systemd) |
+
+## First-time setup (new VPS)
+
+```bash
+# Option A: run remotely on fresh server
+DOMAIN=bridge.example.com bash <(curl -fsSL https://raw.githubusercontent.com/Oolab-labs/claude-ide-bridge/main/deploy/bootstrap-new-vps.sh)
+
+# Option B: after cloning the repo
+DOMAIN=bridge.example.com bash deploy/bootstrap-new-vps.sh
+```
+
+The bootstrap script handles everything end-to-end:
+1. Installs Node.js 20, nginx, certbot
+2. Creates a dedicated `claude-bridge` system user (non-root)
+3. Clones the repo to `/opt/claude-ide-bridge`
+4. Runs `npm ci && npm run build`
+5. Generates `.env.vps` with a random auth token
+6. Opens ports 80/443 in ufw
+7. Installs and enables the systemd service
+8. Writes the nginx config with your domain injected
+9. Runs Certbot for HTTPS
+10. Starts the bridge and confirms it's healthy
+
+**Required:** `DOMAIN` env var pointing to a subdomain that resolves to your VPS IP.
+
+**Optional overrides:**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `REPO_URL` | GitHub upstream | Git repo to clone |
+| `INSTALL_DIR` | `/opt/claude-ide-bridge` | Where to install |
+| `SERVICE_USER` | `claude-bridge` | System user to run as |
+| `PORT` | `9000` | Bridge listen port |
+| `BRANCH` | `main` | Git branch |
+| `SKIP_CERTBOT` | `0` | Set to `1` to skip TLS (DNS not ready) |
+
+## Updating an existing server
+
+```bash
+cd /opt/claude-ide-bridge   # or wherever INSTALL_DIR is
+git pull
+npm ci
+npm run build
+bash deploy/install-vps-service.sh
+```
+
+`install-vps-service.sh` re-generates the systemd unit and nginx config from the current state of `.env.vps`, then restarts the service automatically. It auto-detects the domain and service user from the existing installation — no config needed.
+
+## Day-to-day management
+
+```bash
+# View live logs
+journalctl -u claude-ide-bridge -f
+
+# Check status
+systemctl status claude-ide-bridge
+
+# Restart after code change
+npm run build && systemctl restart claude-ide-bridge
+
+# Stop (won't restart until manually started)
+systemctl stop claude-ide-bridge
+```
+
+## Using PM2 instead of systemd
+
+PM2 is a simpler alternative when you're running as root, already have PM2 installed, or prefer not to configure systemd manually.
+
+> **Important:** The bridge picks a **random port** by default. The port in your PM2 start command **must match** the port in your nginx `proxy_pass` directive, or every restart will cause a 502 Bad Gateway.
+
+### Quick start with PM2
+
+```bash
+# Replace 4748 and YOUR_TOKEN_HERE with your nginx proxy_pass port and auth token
+pm2 delete claude-bridge 2>/dev/null || true
+pm2 start /root/claude-ide-bridge/dist/index.js \
+  --name claude-bridge \
+  -- --port 4748 --bind 0.0.0.0 --vps --fixed-token YOUR_TOKEN_HERE
+pm2 save
+```
+
+Retrieve your token anytime:
+```bash
+cat ~/.claude/ide/*.lock | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8').trim(); console.log(JSON.parse(d).authToken)"
+# or if you have a .env.vps:
+grep FIXED_TOKEN /root/claude-ide-bridge/.env.vps
+```
+
+### Persist across reboots
+
+```bash
+# Generate and run the startup command PM2 prints
+pm2 startup
+# (run the command it outputs, then:)
+pm2 save
+```
+
+### Using an ecosystem file
+
+For repeatable deployments, use the included example:
+
+```bash
+cp deploy/ecosystem.config.js.example ecosystem.config.js
+# Edit ecosystem.config.js: set cwd, port, and fixed-token
+pm2 start ecosystem.config.js
+pm2 save
+```
+
+### Day-to-day management with PM2
+
+```bash
+# View live logs
+pm2 logs claude-bridge
+
+# Check status
+pm2 status
+
+# Restart after code change
+npm run build && pm2 restart claude-bridge
+
+# Stop
+pm2 stop claude-bridge
+```
+
+## MCP endpoint
+
+```
+https://<your-domain>/mcp
+```
+
+Use in `.mcp.json` for Claude Desktop, claude.ai Custom Connectors, or any remote MCP client:
+
+```json
+{
+  "mcpServers": {
+    "claude-ide-bridge": {
+      "type": "http",
+      "url": "https://your-domain/mcp",
+      "headers": {
+        "Authorization": "Bearer ${BRIDGE_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+Set `BRIDGE_TOKEN` in your shell profile. Retrieve the token anytime:
+
+```bash
+grep FIXED_TOKEN /opt/claude-ide-bridge/.env.vps
+```

package/deploy/bootstrap-new-vps.sh

@@ -0,0 +1,364 @@
+#!/usr/bin/env bash
+# deploy/bootstrap-new-vps.sh
+# Full fresh-server setup for claude-ide-bridge on a NEW VPS.
+# Handles everything from Node.js install to running HTTPS service.
+#
+# Usage (run as root on a fresh Ubuntu 22.04/24.04 VPS):
+#   curl -fsSL https://raw.githubusercontent.com/Oolab-labs/claude-ide-bridge/main/deploy/bootstrap-new-vps.sh | \
+#     DOMAIN=bridge.example.com bash
+#
+#   Or after cloning:
+#   DOMAIN=bridge.example.com bash deploy/bootstrap-new-vps.sh
+#
+# Required environment variables:
+#   DOMAIN        Subdomain for the bridge  (e.g. bridge.example.com)
+#
+# Optional environment variables:
+#   REPO_URL      Git repo URL              (default: https://github.com/Oolab-labs/claude-ide-bridge)
+#   INSTALL_DIR   Where to clone the repo   (default: /opt/claude-ide-bridge)
+#   SERVICE_USER  System user to run bridge (default: claude-bridge)
+#   PORT          Bridge port               (default: 9000)
+#   BRANCH        Git branch to clone       (default: main)
+#   SKIP_CERTBOT  Set to 1 to skip TLS cert (useful if DNS not yet set)
+
+set -euo pipefail
+
+# ── Config ────────────────────────────────────────────────────────────────────
+DOMAIN="${DOMAIN:-}"
+REPO_URL="${REPO_URL:-https://github.com/Oolab-labs/claude-ide-bridge}"
+INSTALL_DIR="${INSTALL_DIR:-/opt/claude-ide-bridge}"
+SERVICE_USER="${SERVICE_USER:-claude-bridge}"
+PORT="${PORT:-9000}"
+BRANCH="${BRANCH:-main}"
+SKIP_CERTBOT="${SKIP_CERTBOT:-0}"
+SERVICE_NAME="claude-ide-bridge"
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+info()    { echo -e "${GREEN}✓${NC} $*"; }
+warn()    { echo -e "${YELLOW}⚠${NC}  $*"; }
+err()     { echo -e "${RED}✗${NC} $*" >&2; }
+section() { echo ""; echo "── $* ──────────────────────────────────────────"; }
+
+# ── Pre-flight ────────────────────────────────────────────────────────────────
+section "Pre-flight"
+
+[[ "$(id -u)" -eq 0 ]] || { err "Run as root: sudo bash deploy/bootstrap-new-vps.sh"; exit 1; }
+
+if [[ -z "$DOMAIN" ]]; then
+  err "DOMAIN is required. Example:"
+  echo "  DOMAIN=bridge.example.com bash deploy/bootstrap-new-vps.sh"
+  exit 1
+fi
+
+info "Domain:       $DOMAIN"
+info "Install dir:  $INSTALL_DIR"
+info "Service user: $SERVICE_USER"
+info "Port:         $PORT"
+info "Branch:       $BRANCH"
+
+# ── 1. System packages ────────────────────────────────────────────────────────
+section "System packages"
+
+apt-get update -qq
+apt-get install -y -qq curl git nginx certbot python3-certbot-nginx ufw
+info "System packages installed"
+
+# ── 2. Node.js 20+ ────────────────────────────────────────────────────────────
+section "Node.js"
+
+NODE_OK=false
+if command -v node &>/dev/null; then
+  NODE_VER=$(node -e 'console.log(parseInt(process.version.slice(1)))')
+  [[ "$NODE_VER" -ge 20 ]] && NODE_OK=true
+fi
+
+if [[ "$NODE_OK" == false ]]; then
+  info "Installing Node.js 20..."
+  curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+  apt-get install -y -qq nodejs
+fi
+
+NODE_VERSION=$(node --version)
+info "Node $NODE_VERSION / npm $(npm --version)"
+
+# ── 3. Service user ───────────────────────────────────────────────────────────
+section "Service user"
+
+if ! id "$SERVICE_USER" &>/dev/null; then
+  useradd --system --create-home --shell /bin/bash "$SERVICE_USER"
+  info "Created user: $SERVICE_USER"
+else
+  info "User already exists: $SERVICE_USER"
+fi
+
+# ── 4. Clone or update repo ───────────────────────────────────────────────────
+section "Repository"
+
+if [[ -d "$INSTALL_DIR/.git" ]]; then
+  info "Repo exists — pulling latest..."
+  git -C "$INSTALL_DIR" fetch origin
+  git -C "$INSTALL_DIR" checkout "$BRANCH"
+  git -C "$INSTALL_DIR" pull origin "$BRANCH"
+else
+  info "Cloning $REPO_URL..."
+  git clone --branch "$BRANCH" --depth 1 "$REPO_URL" "$INSTALL_DIR"
+fi
+
+chown -R "$SERVICE_USER:$SERVICE_USER" "$INSTALL_DIR"
+info "Repo ready at $INSTALL_DIR"
+
+# ── 5. Build ──────────────────────────────────────────────────────────────────
+section "Build"
+
+# Run npm install + build as SERVICE_USER
+sudo -u "$SERVICE_USER" bash -c "cd $INSTALL_DIR && npm ci --prefer-offline 2>&1"
+sudo -u "$SERVICE_USER" bash -c "cd $INSTALL_DIR && npm run build 2>&1"
+info "Build complete"
+
+# ── 6. Generate .env.vps ──────────────────────────────────────────────────────
+section ".env.vps"
+
+ENV_FILE="$INSTALL_DIR/.env.vps"
+if [[ -f "$ENV_FILE" ]]; then
+  warn ".env.vps already exists — leaving unchanged"
+  source "$ENV_FILE"
+  info "  PORT=$PORT  WORKSPACE=$WORKSPACE  TOKEN=***"
+else
+  FIXED_TOKEN=$(node -e "console.log(require('crypto').randomUUID())")
+  WORKSPACE="$INSTALL_DIR"
+  cat > "$ENV_FILE" <<EOF
+# Claude IDE Bridge — VPS config
+# Generated by bootstrap-new-vps.sh on $(date -u +%Y-%m-%dT%H:%M:%SZ)
+# Gitignored — never commit this file.
+
+PORT=$PORT
+WORKSPACE=$WORKSPACE
+FIXED_TOKEN=$FIXED_TOKEN
+BRIDGE_SESSION=bridge
+NGROK_SESSION=ngrok
+EOF
+  chmod 600 "$ENV_FILE"
+  chown "$SERVICE_USER:$SERVICE_USER" "$ENV_FILE"
+  info ".env.vps created"
+  info "  PORT=$PORT"
+  info "  WORKSPACE=$WORKSPACE"
+  info "  TOKEN=$FIXED_TOKEN"
+fi
+
+# Reload in case it already existed
+source "$ENV_FILE"
+
+# ── 7. Firewall ───────────────────────────────────────────────────────────────
+section "Firewall (ufw)"
+
+ufw --force enable >/dev/null 2>&1 || true
+ufw allow ssh   >/dev/null 2>&1
+ufw allow 80    >/dev/null 2>&1
+ufw allow 443   >/dev/null 2>&1
+info "ufw: ssh, 80, 443 open"
+
+# ── 8. Systemd service ────────────────────────────────────────────────────────
+section "Systemd service"
+
+# Generate service file from template (parameterised for this install)
+cat > "/etc/systemd/system/${SERVICE_NAME}.service" <<SERVICE
+[Unit]
+Description=Claude IDE Bridge MCP Server
+Documentation=https://github.com/Oolab-labs/claude-ide-bridge
+After=network.target
+StartLimitIntervalSec=120
+StartLimitBurst=5
+
+[Service]
+Type=simple
+User=$SERVICE_USER
+WorkingDirectory=$INSTALL_DIR
+
+# Load config — FIXED_TOKEN, PORT, WORKSPACE
+EnvironmentFile=$ENV_FILE
+
+# Bridge process
+ExecStart=/usr/bin/node $INSTALL_DIR/dist/index.js \\
+    --port \${PORT} \\
+    --workspace \${WORKSPACE} \\
+    --fixed-token \${FIXED_TOKEN} \\
+    --grace-period 120000 \\
+    --vps
+
+KillMode=mixed
+KillSignal=SIGTERM
+TimeoutStopSec=15
+Restart=always
+RestartSec=5
+
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=claude-ide-bridge
+
+NoNewPrivileges=true
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+SERVICE
+
+systemctl daemon-reload
+systemctl enable "$SERVICE_NAME"
+info "Systemd service installed and enabled"
+
+# ── 9. nginx ──────────────────────────────────────────────────────────────────
+section "nginx"
+
+# Add connection_upgrade map to nginx.conf if missing
+if ! grep -q "connection_upgrade" /etc/nginx/nginx.conf 2>/dev/null; then
+  # Insert after the `http {` line
+  perl -i -0pe 's/(http \{)/$1\n    map \$http_upgrade \$connection_upgrade {\n        default upgrade;\n        '"''"'     close;\n    }/' /etc/nginx/nginx.conf
+  info "Added connection_upgrade map to nginx.conf"
+fi
+
+# Write nginx site config (domain injected here, not hardcoded in repo)
+cat > "/etc/nginx/sites-available/claude-bridge" <<NGINX
+# Claude IDE Bridge — nginx reverse proxy
+# Domain: $DOMAIN  Port: ${PORT}
+# Generated by bootstrap-new-vps.sh
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name $DOMAIN;
+
+    location /.well-known/acme-challenge/ {
+        root /var/www/html;
+    }
+
+    location / {
+        return 301 https://\$host\$request_uri;
+    }
+}
+
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    server_name $DOMAIN;
+
+    # TLS — populated by Certbot
+    # ssl_certificate     /etc/letsencrypt/live/$DOMAIN/fullchain.pem;
+    # ssl_certificate_key /etc/letsencrypt/live/$DOMAIN/privkey.pem;
+    # include /etc/letsencrypt/options-ssl-nginx.conf;
+    # ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+
+    add_header X-Content-Type-Options nosniff always;
+    add_header X-Frame-Options DENY always;
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+
+    # /mcp — Streamable HTTP MCP endpoint (SSE-safe)
+    location /mcp {
+        proxy_pass http://127.0.0.1:${PORT};
+        proxy_http_version 1.1;
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+        proxy_connect_timeout 10s;
+        proxy_set_header Authorization \$http_authorization;
+        proxy_pass_header Authorization;
+        proxy_set_header Mcp-Session-Id \$http_mcp_session_id;
+        proxy_pass_header Mcp-Session-Id;
+        proxy_set_header Host \$host;
+        proxy_set_header X-Real-IP \$remote_addr;
+        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto \$scheme;
+        proxy_set_header Upgrade \$http_upgrade;
+        proxy_set_header Connection \$connection_upgrade;
+    }
+
+    location /health {
+        proxy_pass http://127.0.0.1:${PORT};
+        proxy_http_version 1.1;
+        proxy_connect_timeout 5s;
+        proxy_read_timeout 10s;
+    }
+
+    location /.well-known/ {
+        proxy_pass http://127.0.0.1:${PORT};
+        proxy_http_version 1.1;
+        proxy_connect_timeout 5s;
+        proxy_read_timeout 10s;
+    }
+
+    location / {
+        return 404;
+    }
+}
+NGINX
+
+# Enable site
+[[ -L "/etc/nginx/sites-enabled/claude-bridge" ]] || \
+  ln -s /etc/nginx/sites-available/claude-bridge /etc/nginx/sites-enabled/claude-bridge
+
+# Remove default site (conflicts on port 80)
+[[ -L "/etc/nginx/sites-enabled/default" ]] && \
+  rm -f /etc/nginx/sites-enabled/default && info "Removed nginx default site"
+
+nginx -t
+systemctl reload nginx
+info "nginx configured for $DOMAIN"
+
+# ── 10. TLS certificate ───────────────────────────────────────────────────────
+section "TLS certificate"
+
+if [[ "$SKIP_CERTBOT" == "1" ]]; then
+  warn "SKIP_CERTBOT=1 — skipping cert. Run manually later:"
+  echo "  certbot --nginx -d $DOMAIN"
+else
+  if certbot --nginx -d "$DOMAIN" --non-interactive --agree-tos \
+      --register-unsafely-without-email --redirect 2>&1; then
+    info "TLS certificate obtained for $DOMAIN"
+  else
+    warn "Certbot failed. Common causes:"
+    echo "   - DNS not yet pointing to this IP (check: dig $DOMAIN)"
+    echo "   - Port 80 blocked"
+    echo "  Re-run manually: certbot --nginx -d $DOMAIN"
+  fi
+fi
+
+# ── 11. Start service ─────────────────────────────────────────────────────────
+section "Starting service"
+
+systemctl restart "$SERVICE_NAME"
+
+echo -n "Waiting for bridge..."
+for i in $(seq 1 30); do
+  if curl -sf --max-time 3 "http://127.0.0.1:${PORT}/health" >/dev/null 2>&1; then
+    echo " ready."
+    break
+  fi
+  sleep 1; echo -n "."
+  if [[ $i -eq 30 ]]; then
+    echo " timed out."
+    warn "Check logs: journalctl -u $SERVICE_NAME -n 50"
+  fi
+done
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  Claude IDE Bridge — bootstrap complete"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "  MCP endpoint:  https://$DOMAIN/mcp"
+echo "  Health check:  https://$DOMAIN/health"
+echo "  Local:         http://127.0.0.1:${PORT}/mcp"
+echo "  Token:         ${FIXED_TOKEN}"
+echo "  Install dir:   $INSTALL_DIR"
+echo "  Service user:  $SERVICE_USER"
+echo ""
+echo "  Service management:"
+echo "    systemctl status $SERVICE_NAME"
+echo "    journalctl -u $SERVICE_NAME -f"
+echo "    systemctl restart $SERVICE_NAME"
+echo ""
+echo "  To update:"
+echo "    cd $INSTALL_DIR && git pull && npm ci && npm run build"
+echo "    systemctl restart $SERVICE_NAME"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

package/deploy/claude-ide-bridge.service.template

@@ -0,0 +1,67 @@
+# deploy/claude-ide-bridge.service.template
+# Reference template — paths and user are injected by the install scripts.
+# Do NOT copy this file to /etc/systemd/system/ directly.
+# Use bootstrap-new-vps.sh or install-vps-service.sh which generate
+# the final unit file with all variables substituted.
+
+[Unit]
+Description=Claude IDE Bridge MCP Server
+Documentation=https://github.com/Oolab-labs/claude-ide-bridge
+After=network.target
+StartLimitIntervalSec=120
+StartLimitBurst=5
+
+[Service]
+Type=simple
+User=${SERVICE_USER}
+WorkingDirectory=${INSTALL_DIR}
+
+# Load personal config — FIXED_TOKEN, PORT, WORKSPACE must be set here
+EnvironmentFile=${ENV_FILE}
+
+# Bridge process — reads PORT, WORKSPACE, FIXED_TOKEN from EnvironmentFile
+ExecStart=/usr/bin/node ${INSTALL_DIR}/dist/index.js \
+    --port ${PORT} \
+    --workspace ${WORKSPACE} \
+    --fixed-token ${FIXED_TOKEN} \
+    --grace-period 120000 \
+    --vps
+
+# Graceful shutdown: SIGTERM → wait 15s → SIGKILL
+KillMode=mixed
+KillSignal=SIGTERM
+TimeoutStopSec=15
+
+# Restart policy: always restart unless manually stopped
+Restart=always
+RestartSec=5
+
+# Logging — view with: journalctl -u claude-ide-bridge -f
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=claude-ide-bridge
+
+# Hardening
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=${INSTALL_DIR} /tmp /root/.claude
+CapabilityBoundingSet=
+AmbientCapabilities=
+LockPersonality=true
+RestrictNamespaces=true
+RestrictRealtime=true
+RestrictSUIDSGID=true
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=${INSTALL_DIR} /tmp /root/.claude
+CapabilityBoundingSet=
+AmbientCapabilities=
+LockPersonality=true
+RestrictNamespaces=true
+RestrictRealtime=true
+RestrictSUIDSGID=true
+
+[Install]
+WantedBy=multi-user.target

package/deploy/claude-ide-bridge@.service

@@ -0,0 +1,31 @@
+[Unit]
+Description=Claude IDE Bridge MCP Server (for user %i)
+After=network.target
+StartLimitIntervalSec=60
+StartLimitBurst=5
+
+[Service]
+Type=simple
+User=%i
+WorkingDirectory=%h
+ExecStart=/usr/local/bin/node /opt/claude-ide-bridge/dist/index.js --workspace %h --jsonl
+Restart=on-failure
+RestartSec=3
+TimeoutStopSec=10
+KillMode=mixed
+KillSignal=SIGTERM
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=claude-ide-bridge
+NoNewPrivileges=true
+ProtectSystem=strict
+ReadWritePaths=%h/.claude %h
+PrivateTmp=true
+ProtectHome=read-only
+CapabilityBoundingSet=
+LockPersonality=true
+RestrictNamespaces=true
+RestrictSUIDSGID=true
+
+[Install]
+WantedBy=default.target

package/deploy/ecosystem.config.js.example

@@ -0,0 +1,36 @@
+// PM2 ecosystem config for claude-ide-bridge.
+// Copy to the repo root and edit before use:
+//   cp deploy/ecosystem.config.js.example ecosystem.config.js
+//
+// Usage:
+//   pm2 start ecosystem.config.js
+//   pm2 save
+//
+// IMPORTANT: The --port value below must match the port in your nginx proxy_pass.
+// The bridge defaults to a random port if --port is not set, which breaks nginx.
+
+module.exports = {
+  apps: [
+    {
+      name: "claude-bridge",
+      script: "dist/index.js",
+      cwd: "/root/claude-ide-bridge", // adjust to your INSTALL_DIR
+
+      // All bridge flags go here — NOT in env (PORT env var is not read by the bridge)
+      args: [
+        "--port", "4748",             // must match nginx proxy_pass port
+        "--bind", "0.0.0.0",          // expose to all interfaces (nginx handles TLS)
+        "--vps",                       // expands command allowlist for server use
+        "--fixed-token", "YOUR_TOKEN_HERE", // stable token; prevents rotation on restart
+      ].join(" "),
+
+      restart_delay: 5000,  // wait 5s before restart on crash
+      max_restarts: 20,     // give up after 20 consecutive crashes
+      min_uptime: "10s",    // don't count a restart as a crash if up for <10s
+
+      env: {
+        NODE_ENV: "production",
+      },
+    },
+  ],
+};

package/deploy/install-vps-service.sh

@@ -0,0 +1,240 @@
+#!/usr/bin/env bash
+# deploy/install-vps-service.sh
+# Idempotent updater — re-installs the systemd service and nginx config
+# on an already-bootstrapped server after a git pull.
+#
+# For FIRST-TIME setup on a new VPS, use bootstrap-new-vps.sh instead.
+#
+# Usage (run as root from repo root):
+#   bash deploy/install-vps-service.sh
+#
+# Optional environment overrides:
+#   DOMAIN        Override domain (default: read from existing nginx config or prompt)
+#   PORT          Override port   (default: read from .env.vps)
+#   SERVICE_USER  Override user   (default: auto-detect from existing service)
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SERVICE_NAME="claude-ide-bridge"
+ENV_FILE="$REPO_ROOT/.env.vps"
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+info()    { echo -e "${GREEN}✓${NC} $*"; }
+warn()    { echo -e "${YELLOW}⚠${NC}  $*"; }
+err()     { echo -e "${RED}✗${NC} $*" >&2; }
+
+echo "=== Claude IDE Bridge — Service Updater ==="
+echo ""
+
+# ── Pre-flight ────────────────────────────────────────────────────────────────
+[[ "$(id -u)" -eq 0 ]] || { err "Run as root: sudo bash deploy/install-vps-service.sh"; exit 1; }
+[[ -f "$ENV_FILE" ]]   || { err "$ENV_FILE not found. Run bootstrap-new-vps.sh first."; exit 1; }
+
+source "$ENV_FILE"
+[[ -n "${FIXED_TOKEN:-}" ]] || { err "FIXED_TOKEN not set in $ENV_FILE"; exit 1; }
+[[ -n "${PORT:-}" ]]        || { err "PORT not set in $ENV_FILE"; exit 1; }
+[[ -n "${WORKSPACE:-}" ]]   || { err "WORKSPACE not set in $ENV_FILE"; exit 1; }
+
+DIST="$REPO_ROOT/dist/index.js"
+[[ -f "$DIST" ]] || { err "$DIST not found. Run: npm run build"; exit 1; }
+
+command -v nginx     >/dev/null 2>&1 || { err "nginx not found. Run bootstrap-new-vps.sh first."; exit 1; }
+command -v systemctl >/dev/null 2>&1 || { err "systemd not available."; exit 1; }
+
+# Detect service user from existing unit file, fall back to env or default
+EXISTING_USER=$(grep -Po '(?<=^User=).+' /etc/systemd/system/${SERVICE_NAME}.service 2>/dev/null || echo "")
+SERVICE_USER="${SERVICE_USER:-${EXISTING_USER:-claude-bridge}}"
+
+# Detect domain from existing nginx config
+EXISTING_DOMAIN=$(grep -Po '(?<=server_name )[\w.-]+' /etc/nginx/sites-available/claude-bridge 2>/dev/null | head -1 || echo "")
+DOMAIN="${DOMAIN:-$EXISTING_DOMAIN}"
+
+if [[ -z "$DOMAIN" ]]; then
+  err "Cannot determine DOMAIN. Set it: DOMAIN=bridge.example.com bash deploy/install-vps-service.sh"
+  exit 1
+fi
+
+info "Repo:         $REPO_ROOT"
+info "Domain:       $DOMAIN"
+info "Port:         $PORT"
+info "Service user: $SERVICE_USER"
+echo ""
+
+# ── Systemd service ───────────────────────────────────────────────────────────
+echo "Updating systemd service..."
+
+cat > "/etc/systemd/system/${SERVICE_NAME}.service" <<SERVICE
+[Unit]
+Description=Claude IDE Bridge MCP Server
+Documentation=https://github.com/Oolab-labs/claude-ide-bridge
+After=network.target
+StartLimitIntervalSec=120
+StartLimitBurst=5
+
+[Service]
+Type=simple
+User=$SERVICE_USER
+WorkingDirectory=$REPO_ROOT
+
+# Load config — FIXED_TOKEN, PORT, WORKSPACE
+EnvironmentFile=$ENV_FILE
+
+# Bridge process
+ExecStart=/usr/bin/node $REPO_ROOT/dist/index.js \\
+    --port \${PORT} \\
+    --workspace \${WORKSPACE} \\
+    --fixed-token \${FIXED_TOKEN} \\
+    --grace-period 120000 \\
+    --vps
+
+KillMode=mixed
+KillSignal=SIGTERM
+TimeoutStopSec=15
+Restart=always
+RestartSec=5
+
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=claude-ide-bridge
+
+NoNewPrivileges=true
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+SERVICE
+
+systemctl daemon-reload
+systemctl enable "$SERVICE_NAME"
+info "Systemd service updated"
+
+# ── nginx ─────────────────────────────────────────────────────────────────────
+echo "Updating nginx config..."
+
+# Add connection_upgrade map if missing
+if ! grep -q "connection_upgrade" /etc/nginx/nginx.conf 2>/dev/null; then
+  perl -i -0pe 's/(http \{)/$1\n    map \$http_upgrade \$connection_upgrade {\n        default upgrade;\n        '"''"'     close;\n    }/' /etc/nginx/nginx.conf
+  info "Added connection_upgrade map to nginx.conf"
+fi
+
+# Write site config with domain and port injected
+cat > "/etc/nginx/sites-available/claude-bridge" <<NGINX
+# Claude IDE Bridge — nginx reverse proxy
+# Domain: $DOMAIN  Port: ${PORT}
+# Updated by install-vps-service.sh on $(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name $DOMAIN;
+
+    location /.well-known/acme-challenge/ {
+        root /var/www/html;
+    }
+
+    location / {
+        return 301 https://\$host\$request_uri;
+    }
+}
+
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    server_name $DOMAIN;
+
+    # TLS — managed by Certbot
+    # ssl_certificate     /etc/letsencrypt/live/$DOMAIN/fullchain.pem;
+    # ssl_certificate_key /etc/letsencrypt/live/$DOMAIN/privkey.pem;
+    # include /etc/letsencrypt/options-ssl-nginx.conf;
+    # ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+
+    add_header X-Content-Type-Options nosniff always;
+    add_header X-Frame-Options DENY always;
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+
+    location /mcp {
+        proxy_pass http://127.0.0.1:${PORT};
+        proxy_http_version 1.1;
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 86400s;
+        proxy_send_timeout 86400s;
+        proxy_connect_timeout 10s;
+        proxy_set_header Authorization \$http_authorization;
+        proxy_pass_header Authorization;
+        proxy_set_header Mcp-Session-Id \$http_mcp_session_id;
+        proxy_pass_header Mcp-Session-Id;
+        proxy_set_header Host \$host;
+        proxy_set_header X-Real-IP \$remote_addr;
+        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto \$scheme;
+        proxy_set_header Upgrade \$http_upgrade;
+        proxy_set_header Connection \$connection_upgrade;
+    }
+
+    location /health {
+        proxy_pass http://127.0.0.1:${PORT};
+        proxy_http_version 1.1;
+        proxy_connect_timeout 5s;
+        proxy_read_timeout 10s;
+    }
+
+    location /.well-known/ {
+        proxy_pass http://127.0.0.1:${PORT};
+        proxy_http_version 1.1;
+        proxy_connect_timeout 5s;
+        proxy_read_timeout 10s;
+    }
+
+    location / {
+        return 404;
+    }
+}
+NGINX
+
+[[ -L "/etc/nginx/sites-enabled/claude-bridge" ]] || \
+  ln -s /etc/nginx/sites-available/claude-bridge /etc/nginx/sites-enabled/claude-bridge
+
+[[ -L "/etc/nginx/sites-enabled/default" ]] && \
+  rm -f /etc/nginx/sites-enabled/default
+
+nginx -t
+systemctl reload nginx
+info "nginx config updated"
+
+# ── Stop tmux session if still running (superseded by systemd) ────────────────
+if command -v tmux >/dev/null 2>&1 && tmux has-session -t "bridge" 2>/dev/null; then
+  tmux kill-session -t "bridge" 2>/dev/null || true
+  info "Stopped legacy tmux bridge session"
+fi
+
+# ── Restart service ───────────────────────────────────────────────────────────
+echo "Restarting service..."
+systemctl restart "$SERVICE_NAME"
+
+echo -n "Waiting for bridge..."
+for i in $(seq 1 20); do
+  if curl -sf --max-time 3 "http://127.0.0.1:${PORT}/health" >/dev/null 2>&1; then
+    echo " ready."
+    break
+  fi
+  sleep 1; echo -n "."
+  if [[ $i -eq 20 ]]; then
+    echo " timed out."
+    warn "Check: journalctl -u $SERVICE_NAME -n 50"
+  fi
+done
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  Claude IDE Bridge — service updated"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "  MCP endpoint:  https://$DOMAIN/mcp"
+echo "  Local:         http://127.0.0.1:${PORT}/mcp"
+echo "  Token:         ${FIXED_TOKEN}"
+echo ""
+echo "  journalctl -u $SERVICE_NAME -f"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

package/deploy/nginx-claude-bridge.conf.template

@@ -0,0 +1,129 @@
+# deploy/nginx-claude-bridge.conf.template
+# Reference template — domain and port are injected by the install scripts.
+# Do NOT use this file directly. Use bootstrap-new-vps.sh or install-vps-service.sh
+# which write the final nginx config to /etc/nginx/sites-available/claude-bridge
+# with $DOMAIN and $PORT substituted.
+#
+# To manually generate from this template:
+#   DOMAIN=bridge.example.com PORT=9000 \
+#   envsubst '$DOMAIN $PORT' < deploy/nginx-claude-bridge.conf.template \
+#   > /etc/nginx/sites-available/claude-bridge
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name ${DOMAIN};
+
+    # Let Certbot complete ACME HTTP-01 challenges
+    location /.well-known/acme-challenge/ {
+        root /var/www/html;
+    }
+
+    # Redirect all other HTTP to HTTPS
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
+
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    server_name ${DOMAIN};
+
+    # TLS — Certbot populates these after: certbot --nginx -d ${DOMAIN}
+    # ssl_certificate     /etc/letsencrypt/live/${DOMAIN}/fullchain.pem;
+    # ssl_certificate_key /etc/letsencrypt/live/${DOMAIN}/privkey.pem;
+    # include /etc/letsencrypt/options-ssl-nginx.conf;
+    # ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+
+    # Security headers
+    add_header X-Content-Type-Options nosniff always;
+    add_header X-Frame-Options DENY always;
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+    add_header Content-Security-Policy "default-src 'none'" always;
+
+    # /mcp — Streamable HTTP MCP endpoint (SSE-safe, never buffer)
+    location /mcp {
+        # Rate limit: 30 req/min per IP, burst of 10 (requires limit_req_zone in http{} block)
+        limit_req zone=mcp_zone burst=10 nodelay;
+        limit_req_status 429;
+
+        proxy_pass http://127.0.0.1:${PORT};
+        proxy_http_version 1.1;
+
+        # SSE requires no buffering
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 86400s;
+        proxy_send_timeout 86400s;
+        proxy_connect_timeout 10s;
+
+        # Forward auth and MCP session headers
+        proxy_set_header Authorization $http_authorization;
+        proxy_pass_header Authorization;
+        proxy_set_header Mcp-Session-Id $http_mcp_session_id;
+        proxy_pass_header Mcp-Session-Id;
+
+        # Standard proxy headers
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket upgrade passthrough
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+    }
+
+    # /health — unauthenticated health check
+    location /health {
+        proxy_pass http://127.0.0.1:${PORT};
+        proxy_http_version 1.1;
+        proxy_connect_timeout 5s;
+        proxy_read_timeout 10s;
+    }
+
+    # /.well-known — MCP server card + OAuth discovery (RFC 8414, RFC 9396)
+    location /.well-known/ {
+        proxy_pass http://127.0.0.1:${PORT};
+        proxy_http_version 1.1;
+        proxy_connect_timeout 5s;
+        proxy_read_timeout 10s;
+    }
+
+    # /oauth — OAuth 2.0 endpoints (authorize, token, register, revoke)
+    location /oauth/ {
+        proxy_pass http://127.0.0.1:${PORT};
+        proxy_http_version 1.1;
+        proxy_connect_timeout 5s;
+        proxy_read_timeout 30s;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # /ping — unauthenticated health probe
+    location /ping {
+        proxy_pass http://127.0.0.1:${PORT};
+        proxy_http_version 1.1;
+        proxy_connect_timeout 5s;
+        proxy_read_timeout 10s;
+    }
+
+    # Block everything else
+    location / {
+        return 404;
+    }
+}
+
+# Note: add this to the `http {}` block in /etc/nginx/nginx.conf if not present
+# (bootstrap-new-vps.sh and install-vps-service.sh do this automatically):
+#
+# map $http_upgrade $connection_upgrade {
+#     default upgrade;
+#     ''      close;
+# }
+#
+# Rate limiting zone — add to http {} block:
+# limit_req_zone $binary_remote_addr zone=mcp_zone:10m rate=30r/m;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-ide-bridge",
-  "version": "2.22.7",
+  "version": "2.22.8",
   "description": "Standalone MCP bridge for Claude Code IDE integration with any editor — 136+ tools for LSP, debugging, terminals, Git, GitHub, and more",
   "type": "module",
   "main": "dist/index.js",
@@ -54,7 +54,9 @@
     "scripts/mcp-stdio-shim.cjs",
     "scripts/postinstall.mjs",
     "scripts/start-vps.sh",
+    "scripts/gen-claude-desktop-config.sh",
     "templates",
+    "deploy",
     "LICENSE",
     "README.md"
   ],
@@ -62,7 +64,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc && node scripts/postinstall.mjs",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc && (node scripts/postinstall.mjs || true)",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "test": "vitest run",

package/scripts/gen-claude-desktop-config.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# Generate or update claude_desktop_config.json so Claude Desktop connects
+# to the running claude-ide-bridge via the stdio shim.
+#
+# Run with `bash`, do not source this script.
+#
+# Usage:
+#   bash scripts/gen-claude-desktop-config.sh          # Print config
+#   bash scripts/gen-claude-desktop-config.sh --write   # Write to config file
+#
+# The shim auto-discovers the running bridge via lock files in ~/.claude/ide/.
+# No port or token needs to be hard-coded -- just start the bridge first.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SHIM_PATH="${SCRIPT_DIR}/mcp-stdio-shim.cjs"
+
+# --- Detect config path ---
+if [[ "$(uname)" == "Darwin" ]]; then
+  CONFIG_PATH="${HOME}/Library/Application Support/Claude/claude_desktop_config.json"
+else
+  CONFIG_PATH="${APPDATA:-${HOME}/.config}/Claude/claude_desktop_config.json"
+fi
+
+WRITE=false
+for arg in "$@"; do
+  case "$arg" in
+    --write) WRITE=true ;;
+    --help|-h)
+      echo "Usage: $0 [--write]"
+      echo ""
+      echo "Generates a claude_desktop_config.json entry so Claude Desktop"
+      echo "connects to the running claude-ide-bridge via the stdio shim."
+      echo ""
+      echo "  --write   Merge into ${CONFIG_PATH}"
+      echo "            (backs up existing config first)"
+      exit 0
+      ;;
+  esac
+done
+
+# --- Verify shim exists ---
+if [[ ! -f "$SHIM_PATH" ]]; then
+  echo "Error: stdio shim not found at $SHIM_PATH" >&2
+  echo "Make sure you're running this from the bridge repo." >&2
+  exit 1
+fi
+
+# --- Verify bridge is running (optional, warn only) ---
+CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+LOCK_DIR="$CLAUDE_DIR/ide"
+LOCK_COUNT=$(find "$LOCK_DIR" -maxdepth 1 -name "*.lock" 2>/dev/null | wc -l | tr -d ' ')
+if [[ "$LOCK_COUNT" -eq 0 ]]; then
+  echo "Warning: No bridge lock files found. Start the bridge first (npm run start-all)." >&2
+  echo "The config will still be generated -- the shim will connect when the bridge starts." >&2
+  echo ""
+fi
+
+# --- Build or merge config ---
+# Pass SHIM_PATH via env var to avoid path injection in python -c string
+if [[ -f "$CONFIG_PATH" ]]; then
+  MERGED=$(SHIM_PATH="$SHIM_PATH" CONFIG_PATH="$CONFIG_PATH" python3 - <<'PYEOF'
+import json, os, sys
+shim = os.environ["SHIM_PATH"]
+config_path = os.environ["CONFIG_PATH"]
+try:
+    with open(config_path, "r") as f:
+        config = json.load(f)
+except (json.JSONDecodeError, FileNotFoundError):
+    config = {}
+if "mcpServers" not in config:
+    config["mcpServers"] = {}
+config["mcpServers"]["claude-ide-bridge"] = {
+    "command": "node",
+    "args": [shim]
+}
+print(json.dumps(config, indent=2))
+PYEOF
+)
+else
+  MERGED=$(SHIM_PATH="$SHIM_PATH" python3 - <<'PYEOF'
+import json, os
+shim = os.environ["SHIM_PATH"]
+config = {
+    "mcpServers": {
+        "claude-ide-bridge": {
+            "command": "node",
+            "args": [shim]
+        }
+    }
+}
+print(json.dumps(config, indent=2))
+PYEOF
+)
+fi
+
+echo "=== Claude Desktop MCP Config ==="
+echo "Config path: $CONFIG_PATH"
+echo ""
+echo "$MERGED"
+
+if $WRITE; then
+  echo ""
+  # Atomic write: write to .tmp then mv to prevent partial writes
+  TMP_PATH="${CONFIG_PATH}.tmp"
+  mkdir -p "$(dirname "$CONFIG_PATH")"
+  # Back up existing config with timestamp to avoid clobbering previous backups
+  if [[ -f "$CONFIG_PATH" ]]; then
+    BACKUP="${CONFIG_PATH}.$(date +%Y%m%d%H%M%S).bak"
+    cp "$CONFIG_PATH" "$BACKUP"
+    echo "Backed up existing config to $(basename "$BACKUP")"
+  fi
+  printf '%s\n' "$MERGED" > "$TMP_PATH"
+  mv "$TMP_PATH" "$CONFIG_PATH"
+  echo "Written: $CONFIG_PATH"
+  echo ""
+  echo "Restart Claude Desktop to pick up the new config."
+  echo "Then ask Claude: \"What files are open in my IDE?\""
+else
+  echo ""
+  echo "Run with --write to save this config, or copy it manually to:"
+  echo "  $CONFIG_PATH"
+fi