@aerostack/gateway 0.11.5 → 0.13.0

package/README.md

@@ -1,12 +1,14 @@
 # @aerostack/gateway
 
-Connect any MCP client to an [Aerostack Workspace](https://aerostack.dev) — one URL, all your tools, with built-in human approval gates.
+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.
 
 [![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
@@ -15,33 +17,17 @@ 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 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 |
+### 1. Get a workspace token
 
----
+In your [Aerostack Admin Dashboard](https://app.aerostack.dev), open your workspace and generate a token (`mwt_...`).
 
-### Claude Desktop
+### 2. Configure your AI tool
 
-**NPX (recommended):**
-
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
@@ -50,7 +36,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
       "command": "npx",
       "args": ["-y", "@aerostack/gateway"],
       "env": {
-        "AEROSTACK_WORKSPACE_URL": "https://mcp.aerostack.dev/ws/your-slug",
+        "AEROSTACK_WORKSPACE_URL": "https://api.aerostack.dev/api/gateway/ws/my-workspace",
         "AEROSTACK_TOKEN": "mwt_your_token_here"
       }
     }
@@ -58,334 +44,127 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-**URL:**
+**Cline (VS Code)** — add to VS Code settings under `cline.mcpServers`:
 
 ```json
 {
-  "mcpServers": {
-    "aerostack": {
-      "url": "https://mcp.aerostack.dev/ws/your-slug",
-      "headers": { "Authorization": "Bearer mwt_your_token_here" }
+  "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"
     }
   }
 }
 ```
 
----
-
-### Claude Code
-
-**NPX (recommended):**
+**Cursor / Goose / HTTP-native clients** — use the workspace URL directly (no bridge needed):
 
-```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"
 ```
-
-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"
-      }
-    }
-  }
-}
+URL:   https://api.aerostack.dev/api/gateway/ws/my-workspace
+Token: mwt_your_token_here  (Authorization: Bearer header)
 ```
 
----
-
-### Cursor
+### 3. Use it
 
-**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" }
-    }
-  }
-}
 ```
-
-**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"
-      }
-    }
-  }
-}
+You: Create a GitHub issue for the login bug
+AI:  [calls github__create_issue via Aerostack workspace]
 ```
 
----
-
-### Windsurf
-
-**URL (recommended):**
+Tools are namespaced as `{server}__{tool}` (e.g., `github__create_issue`, `slack__send_message`).
 
-Edit `~/.codeium/windsurf/mcp_config.json`:
+## How It Works
 
-```json
-{
-  "mcpServers": {
-    "aerostack": {
-      "serverUrl": "https://mcp.aerostack.dev/ws/your-slug",
-      "headers": { "Authorization": "Bearer mwt_your_token_here" }
-    }
-  }
-}
 ```
-
-**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"
-      }
-    }
-  }
-}
+Your AI tool (stdio) → @aerostack/gateway → HTTPS → Aerostack Workspace
+                                                           ↓
+                                              ┌────────────────────────┐
+                                              │ Fan-out to MCP servers │
+                                              │ GitHub, Slack, Gmail,  │
+                                              │ custom Workers, etc.   │
+                                              └────────────────────────┘
 ```
 
----
-
-### VS Code
-
-**URL:**
+The bridge:
 
-Edit `.vscode/mcp.json`:
+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
 
-```json
-{
-  "servers": {
-    "aerostack": {
-      "type": "http",
-      "url": "https://mcp.aerostack.dev/ws/your-slug",
-      "headers": { "Authorization": "Bearer mwt_your_token_here" }
-    }
-  }
-}
-```
-
-**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"
-      }
-    }
-  }
-}
-```
-
----
-
-### 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):**
-
-Edit `~/.config/goose/config.yaml`:
-
-```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
+## Approval Gates
 
-If the connection isn't working, run the bridge directly in your terminal:
+When your workspace has approval rules configured, the bridge handles them transparently:
 
-```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":{}}'
+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
 ```
 
-**Common issues:**
+Your AI agent sees either a successful result or a clear error — no special handling needed.
 
-| 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` |
+## Local Guardian
 
----
+Approval gates for **local operations** — file deletion, destructive shell commands, git push, deploys. The agent asks for approval before acting on your machine.
 
-## Approval Gates
-
-When workspace approval rules are configured, the bridge handles them transparently:
+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.
 
 ```
-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
+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
 ```
 
-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.
+| 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 |
 
 ## Configuration
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `AEROSTACK_WORKSPACE_URL` | Yes | — | `https://mcp.aerostack.dev/ws/your-slug` |
+| `AEROSTACK_WORKSPACE_URL` | Yes | — | Full workspace endpoint URL |
 | `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` |
+| `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 |
 
 ## Requirements
 
-- Node.js 18+ (for NPX mode only)
+- Node.js 18+
 - 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.5",
+  "version": "0.13.0",
   "description": "stdio-to-HTTP bridge connecting any MCP client to Aerostack Workspaces",
   "author": "Aerostack",
   "license": "MIT",