@aerostack/gateway 0.11.2 → 0.11.4

package/README.md

@@ -1,14 +1,12 @@
 # @aerostack/gateway
 
-Connect any MCP client (Claude Desktop, Cline, Cursor, Goose, Windsurf, and more) to an [Aerostack Workspace](https://aerostack.dev) — one URL, all your tools, with built-in human approval gates.
+Connect any MCP client to an [Aerostack Workspace](https://aerostack.dev) — one URL, all your tools, with built-in human approval gates.
 
 [![License: MIT](https://img.shields.io/badge/LICENSE_//_MIT-3b5bdb?style=for-the-badge&labelColor=eff6ff)](https://opensource.org/licenses/MIT)
 [![npm](https://img.shields.io/npm/v/@aerostack/gateway?style=for-the-badge&color=3b5bdb&labelColor=eff6ff)](https://www.npmjs.com/package/@aerostack/gateway)
 
 ## Why?
 
-Many MCP clients only support **stdio** transport. Aerostack Workspaces use **HTTP**. This bridge connects them — no code required.
-
 Instead of configuring dozens of separate MCP servers in your AI tool, point at one Aerostack Workspace and get:
 
 - **All tools in one place** — composed from multiple MCP servers
@@ -17,17 +15,33 @@ Instead of configuring dozens of separate MCP servers in your AI tool, point at
 - **Local Guardian** — approval gates for local operations (file delete, shell, git push, deploy)
 - **Per-tool permissions** — workspace tokens scope exactly which tools are accessible
 - **Usage tracking & audit** — every tool call logged and metered
-- **Rate limiting** — per-token, plan-tiered
 
 ## Quick Start
 
-### 1. Get a workspace token
+### 1. Get your workspace URL and token
+
+In your [Aerostack Dashboard](https://app.aerostack.dev), open your workspace and copy:
+- **Workspace URL:** `https://mcp.aerostack.dev/ws/your-slug`
+- **Token:** generate one from the Tokens tab (`mwt_...`)
+
+---
+
+## Setup by Client
+
+Two connection modes:
+
+| Mode | How | Best for |
+|------|-----|----------|
+| **URL** | Client connects directly over HTTP | Cursor, Windsurf, VS Code, Goose — HTTP-native clients |
+| **NPX** | Runs a local bridge process | Claude Desktop, Cline, OpenClaw — stdio-only clients |
 
-In your [Aerostack Admin Dashboard](https://app.aerostack.dev), open your workspace and generate a token (`mwt_...`).
+---
 
-### 2. Configure your AI tool
+### Claude Desktop
 
-**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+**NPX (recommended):**
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
@@ -36,7 +50,7 @@ In your [Aerostack Admin Dashboard](https://app.aerostack.dev), open your worksp
       "command": "npx",
       "args": ["-y", "@aerostack/gateway"],
       "env": {
-        "AEROSTACK_WORKSPACE_URL": "https://api.aerostack.dev/api/gateway/ws/my-workspace",
+        "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-slug",
         "AEROSTACK_TOKEN": "mwt_your_token_here"
       }
     }
@@ -44,127 +58,334 @@ In your [Aerostack Admin Dashboard](https://app.aerostack.dev), open your worksp
 }
 ```
 
-**Cline (VS Code)** — add to VS Code settings under `cline.mcpServers`:
+**URL:**
 
 ```json
 {
-  "aerostack": {
-    "command": "npx",
-    "args": ["-y", "@aerostack/gateway"],
-    "env": {
-      "AEROSTACK_WORKSPACE_URL": "https://api.aerostack.dev/api/gateway/ws/my-workspace",
-      "AEROSTACK_TOKEN": "mwt_your_token_here"
+  "mcpServers": {
+    "aerostack": {
+      "url": "https://mcp.aerostack.dev/ws/your-slug",
+      "headers": { "Authorization": "Bearer mwt_your_token_here" }
     }
   }
 }
 ```
 
-**Cursor / Goose / HTTP-native clients** — use the workspace URL directly (no bridge needed):
+---
+
+### Claude Code
+
+**NPX (recommended):**
 
+```bash
+claude mcp add aerostack \
+  --command "npx" \
+  --args "-y,@aerostack/gateway" \
+  --env "AEROSTACK_WORKSPACE_URL=https://mcp.aerostack.dev/ws/your-slug" \
+  --env "AEROSTACK_TOKEN=mwt_your_token_here"
 ```
-URL:   https://api.aerostack.dev/api/gateway/ws/my-workspace
-Token: mwt_your_token_here  (Authorization: Bearer header)
+
+Or edit `.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "aerostack": {
+      "command": "npx",
+      "args": ["-y", "@aerostack/gateway"],
+      "env": {
+        "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-slug",
+        "AEROSTACK_TOKEN": "mwt_your_token_here"
+      }
+    }
+  }
+}
 ```
 
-### 3. Use it
+---
+
+### Cursor
 
+**URL (recommended — no install needed):**
+
+Open Cursor Settings → MCP → Add Server:
+
+```json
+{
+  "mcpServers": {
+    "aerostack": {
+      "url": "https://mcp.aerostack.dev/ws/your-slug",
+      "headers": { "Authorization": "Bearer mwt_your_token_here" }
+    }
+  }
+}
 ```
-You: Create a GitHub issue for the login bug
-AI:  [calls github__create_issue via Aerostack workspace]
+
+**NPX:**
+
+```json
+{
+  "mcpServers": {
+    "aerostack": {
+      "command": "npx",
+      "args": ["-y", "@aerostack/gateway"],
+      "env": {
+        "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-slug",
+        "AEROSTACK_TOKEN": "mwt_your_token_here"
+      }
+    }
+  }
+}
 ```
 
-Tools are namespaced as `{server}__{tool}` (e.g., `github__create_issue`, `slack__send_message`).
+---
+
+### Windsurf
+
+**URL (recommended):**
 
-## How It Works
+Edit `~/.codeium/windsurf/mcp_config.json`:
 
+```json
+{
+  "mcpServers": {
+    "aerostack": {
+      "serverUrl": "https://mcp.aerostack.dev/ws/your-slug",
+      "headers": { "Authorization": "Bearer mwt_your_token_here" }
+    }
+  }
+}
 ```
-Your AI tool (stdio) → @aerostack/gateway → HTTPS → Aerostack Workspace
-                                                           ↓
-                                              ┌────────────────────────┐
-                                              │ Fan-out to MCP servers │
-                                              │ GitHub, Slack, Gmail,  │
-                                              │ custom Workers, etc.   │
-                                              └────────────────────────┘
+
+**NPX:**
+
+```json
+{
+  "mcpServers": {
+    "aerostack": {
+      "command": "npx",
+      "args": ["-y", "@aerostack/gateway"],
+      "env": {
+        "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-slug",
+        "AEROSTACK_TOKEN": "mwt_your_token_here"
+      }
+    }
+  }
+}
 ```
 
-The bridge:
+---
 
-1. Starts as a stdio MCP server (what your AI tool expects)
-2. Forwards all JSON-RPC requests to your workspace over HTTPS
-3. Handles SSE streaming responses transparently
-4. Manages the approval gate flow automatically
+### VS Code
 
-## Approval Gates
+**URL:**
 
-When your workspace has approval rules configured, the bridge handles them transparently:
+Edit `.vscode/mcp.json`:
 
+```json
+{
+  "servers": {
+    "aerostack": {
+      "type": "http",
+      "url": "https://mcp.aerostack.dev/ws/your-slug",
+      "headers": { "Authorization": "Bearer mwt_your_token_here" }
+    }
+  }
+}
 ```
-AI calls dangerous_tool
-  → Bridge forwards to workspace
-  → Workspace returns "needs approval" (-32050)
-  → Bridge waits via WebSocket (instant) or polls as fallback
-  → You approve/reject in dashboard or mobile app
-  → Bridge retries on approval, returns error on rejection
+
+**NPX:**
+
+```json
+{
+  "servers": {
+    "aerostack": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@aerostack/gateway"],
+      "env": {
+        "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-slug",
+        "AEROSTACK_TOKEN": "mwt_your_token_here"
+      }
+    }
+  }
+}
 ```
 
-Your AI agent sees either a successful result or a clear error — no special handling needed.
+---
 
-## Local Guardian
+### Cline
+
+**NPX:**
+
+Open VS Code Settings → search `Cline MCP` → Edit in `settings.json`:
+
+```json
+{
+  "cline.mcpServers": {
+    "aerostack": {
+      "command": "npx",
+      "args": ["-y", "@aerostack/gateway"],
+      "env": {
+        "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-slug",
+        "AEROSTACK_TOKEN": "mwt_your_token_here"
+      }
+    }
+  }
+}
+```
+
+**URL:**
+
+```json
+{
+  "cline.mcpServers": {
+    "aerostack": {
+      "url": "https://mcp.aerostack.dev/ws/your-slug",
+      "headers": { "Authorization": "Bearer mwt_your_token_here" }
+    }
+  }
+}
+```
+
+---
+
+### Goose
+
+**URL (recommended — Goose is HTTP-native):**
 
-Approval gates for **local operations** — file deletion, destructive shell commands, git push, deploys. The agent asks for approval before acting on your machine.
+Edit `~/.config/goose/config.yaml`:
 
-The bridge injects an `aerostack__local_guardian` tool. When the LLM is about to perform a risky local operation, it calls this tool first. You get a push notification and can approve or reject from the dashboard or your phone.
+```yaml
+mcp:
+  servers:
+    aerostack:
+      url: https://mcp.aerostack.dev/ws/your-slug
+      headers:
+        Authorization: Bearer mwt_your_token_here
+```
+
+**NPX:**
+
+```yaml
+mcp:
+  servers:
+    aerostack:
+      command: npx
+      args: ["-y", "@aerostack/gateway"]
+      env:
+        AEROSTACK_WORKSPACE_URL: https://mcp.aerostack.dev/ws/your-slug
+        AEROSTACK_TOKEN: mwt_your_token_here
+```
+
+---
+
+### OpenClaw
+
+**NPX:**
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "aerostack": {
+        "command": "npx",
+        "args": ["-y", "@aerostack/gateway"],
+        "env": {
+          "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-slug",
+          "AEROSTACK_TOKEN": "mwt_your_token_here"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+### Any HTTP-native client
+
+Use the workspace URL directly — no package needed:
+
+```
+URL:    https://mcp.aerostack.dev/ws/your-slug
+Header: Authorization: Bearer mwt_your_token_here
+```
+
+---
+
+## Debugging
+
+If the connection isn't working, run the bridge directly in your terminal:
+
+```bash
+AEROSTACK_LOG_LEVEL=debug \
+AEROSTACK_WORKSPACE_URL=https://mcp.aerostack.dev/ws/your-slug \
+AEROSTACK_TOKEN=mwt_your_token_here \
+npx -y @aerostack/gateway
+```
+
+Or test the workspace endpoint with curl:
+
+```bash
+curl -X POST https://mcp.aerostack.dev/ws/your-slug \
+  -H "Authorization: Bearer mwt_your_token_here" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+**Common issues:**
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `401 Unauthorized` | Invalid or expired token | Generate a new token from the Tokens tab |
+| `404 Not Found` | Wrong workspace slug | Check the slug in your dashboard URL |
+| Tools list is empty | No servers added to workspace | Add MCP servers from the marketplace |
+| `npx: command not found` | Node.js not installed | Install Node.js 18+ from nodejs.org |
+| Old version cached by npx | Stale npx cache | Run `npx --yes @aerostack/gateway@latest` |
+
+---
+
+## Approval Gates
+
+When workspace approval rules are configured, the bridge handles them transparently:
 
 ```
-Agent wants to: rm -rf ./old-config/
-  → Agent calls aerostack__local_guardian
-  → You get push notification on your phone
-  → Tap Approve or Reject
-  → Agent proceeds or stops
+AI calls a gated tool
+  → Workspace returns "needs approval"
+  → Bridge waits (WebSocket for instant wake, polling as fallback)
+  → You approve or reject from dashboard or mobile app
+  → Bridge retries on approval, returns error on rejection
 ```
 
-| Category | What it covers |
-|----------|---------------|
-| `file_delete` | Deleting or overwriting files |
-| `shell_destructive` | `rm -rf`, `DROP TABLE`, etc. |
-| `git_push` | `git push`, force push, `git reset --hard` |
-| `config_modify` | `.env`, credentials, production configs |
-| `deploy` | Deploy, publish, release to any environment |
-| `database` | Direct database mutations outside migrations |
+Your agent sees either a successful result or a clear error — no special handling needed.
+
+## Local Guardian
+
+Approval gates for local operations — file deletion, shell commands, git push, deploys. The `aerostack__local_guardian` tool is injected automatically when enabled in your workspace settings.
 
 ## Configuration
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `AEROSTACK_WORKSPACE_URL` | Yes | — | Full workspace endpoint URL |
+| `AEROSTACK_WORKSPACE_URL` | Yes | — | `https://mcp.aerostack.dev/ws/your-slug` |
 | `AEROSTACK_TOKEN` | Yes | — | Workspace token (`mwt_...`) |
 | `AEROSTACK_APPROVAL_POLL_MS` | No | `3000` | Approval polling interval (ms) |
 | `AEROSTACK_APPROVAL_TIMEOUT_MS` | No | `300000` | Max approval wait time (5 min) |
 | `AEROSTACK_REQUEST_TIMEOUT_MS` | No | `30000` | HTTP request timeout (30s) |
 | `AEROSTACK_LOCAL_GUARDIAN` | No | `true` | Set `false` to disable Local Guardian |
-| `AEROSTACK_LOG_LEVEL` | No | `info` | Log level: debug, info, warn, error |
-
-## Supported MCP Methods
-
-| Method | Description |
-|--------|-------------|
-| `tools/list` | List all tools from all workspace servers |
-| `tools/call` | Call a namespaced tool (with approval handling) |
-| `resources/list` | List resources from all workspace servers |
-| `resources/read` | Read a specific resource |
-| `prompts/list` | List prompts from all workspace servers |
-| `prompts/get` | Get a prompt with arguments |
+| `AEROSTACK_LOG_LEVEL` | No | `info` | Log level: `debug`, `info`, `warn`, `error` |
 
 ## Requirements
 
-- Node.js 18+
+- Node.js 18+ (for NPX mode only)
 - An Aerostack account with a configured workspace
 - A workspace token (`mwt_...`)
 
 ## Links
 
+- [Aerostack Dashboard](https://app.aerostack.dev)
 - [Aerostack Docs](https://docs.aerostack.dev)
-- [Aerostack Admin](https://app.aerostack.dev)
 - [MCP Specification](https://modelcontextprotocol.io)
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerostack/gateway",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "stdio-to-HTTP bridge connecting any MCP client to Aerostack Workspaces",
   "author": "Aerostack",
   "license": "MIT",