npm - @aerostack/gateway - Versions diffs - 0.11.5 → 0.13.1 - Mend

@aerostack/gateway 0.11.5 → 0.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -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/dist/hook-server.js CHANGED Viewed

@@ -10,8 +10,9 @@
  * Also manages ~/.claude/settings.json hook entries when enabled/disabled.
  */
 import { createServer } from 'node:http';
-import { readFile, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
+import { readFile, writeFile, appendFile, stat } from 'node:fs/promises';
+import { watch } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { info, warn, debug } from './logger.js';
 // ─── Config ───────────────────────────────────────────────────────────────
@@ -158,34 +159,93 @@ function handleHookRequest(req, res) {
     });
 }
 // ─── Public API ───────────────────────────────────────────────────────────
+let fileWatcher = null;
+let lastFileSize = 0;
+/** Process new lines appended to the JSONL events file. */
+async function processNewEvents() {
+    try {
+        const st = await stat(HOOK_EVENTS_FILE).catch(() => null);
+        if (!st || st.size <= lastFileSize)
+            return;
+        const content = await readFile(HOOK_EVENTS_FILE, 'utf-8');
+        const lines = content.split('\n').filter(Boolean);
+        // Only process lines we haven't seen (based on byte offset)
+        const newContent = content.slice(lastFileSize);
+        lastFileSize = st.size;
+        const newLines = newContent.split('\n').filter(Boolean);
+        for (const line of newLines) {
+            try {
+                const data = JSON.parse(line);
+                const toolName = data.tool_name ?? '';
+                // Skip read-only tools
+                if (READONLY_TOOLS.has(toolName))
+                    continue;
+                if (!MUTATION_TOOLS.has(toolName) && !bridgeConfig.tools.includes(toolName))
+                    continue;
+                const toolInput = data.tool_input ?? {};
+                const { category, risk } = detectCategory(toolName, toolInput);
+                const summary = summarizeToolInput(toolName, toolInput);
+                addToBatch({
+                    action: `${toolName}: ${summary}`.slice(0, 500),
+                    category,
+                    risk_level: risk,
+                    details: JSON.stringify({ tool: toolName, ...toolInput }).slice(0, 500),
+                });
+                debug(`File hook event: ${toolName}`, { category });
+            }
+            catch { /* skip malformed lines */ }
+        }
+        // Truncate file if it gets too large (>1MB)
+        if (st.size > 1_048_576) {
+            await writeFile(HOOK_EVENTS_FILE, '', 'utf-8');
+            lastFileSize = 0;
+        }
+    }
+    catch { /* file may not exist yet */ }
+}
 export async function startHookServer(flushFn, port = DEFAULT_PORT) {
     batchFlushFn = flushFn;
-    // Find available port (try configured, then increment)
-    return new Promise((resolve, reject) => {
+    // Start HTTP server (still useful for non-Claude clients)
+    const actualPort = await new Promise((resolve, reject) => {
         httpServer = createServer(handleHookRequest);
         httpServer.on('error', (err) => {
             if (err.code === 'EADDRINUSE') {
-                // Try next port
                 info(`Port ${port} in use, trying ${port + 1}`);
                 httpServer.close();
                 startHookServer(flushFn, port + 1).then(resolve).catch(reject);
             }
             else {
-                reject(err);
+                // Non-fatal — file-based hooks still work without HTTP server
+                warn('HTTP hook server failed, using file-based hooks only', { error: err.message });
+                resolve(0);
             }
         });
         httpServer.listen(port, '127.0.0.1', () => {
             serverPort = port;
             info(`Hook server listening on http://127.0.0.1:${port}/hook`);
-            // Start batch flush timer
-            flushTimer = setInterval(() => {
-                flushBatch().catch(err => {
-                    warn('Batch flush failed', { error: err instanceof Error ? err.message : String(err) });
-                });
-            }, BATCH_INTERVAL_MS);
             resolve(port);
         });
     });
+    // Start file watcher for JSONL events (primary hook mechanism — no port conflicts)
+    try {
+        // Touch file so watcher has something to watch
+        await appendFile(HOOK_EVENTS_FILE, '');
+        fileWatcher = watch(HOOK_EVENTS_FILE, () => {
+            processNewEvents().catch(() => { });
+        });
+        info('File watcher started', { path: HOOK_EVENTS_FILE });
+    }
+    catch (err) {
+        warn('File watcher failed', { error: err instanceof Error ? err.message : String(err) });
+    }
+    // Start batch flush timer — also polls JSONL file as safety net for fs.watch misses
+    flushTimer = setInterval(() => {
+        processNewEvents().catch(() => { });
+        flushBatch().catch(err => {
+            warn('Batch flush failed', { error: err instanceof Error ? err.message : String(err) });
+        });
+    }, BATCH_INTERVAL_MS);
+    return actualPort;
 }
 export function stopHookServer() {
     if (flushTimer) {
@@ -194,6 +254,10 @@ export function stopHookServer() {
     }
     // Final flush
     flushBatch().catch(() => { });
+    if (fileWatcher) {
+        fileWatcher.close();
+        fileWatcher = null;
+    }
     if (httpServer) {
         httpServer.close();
         httpServer = null;
@@ -202,7 +266,9 @@ export function stopHookServer() {
 }
 // ─── Claude Code hook management ──────────────────────────────────────────
 const HOOK_MARKER = '/* aerostack-guardian-hook */';
-export async function installClaudeHook(port) {
+/** Path where hook events are written as JSONL (one JSON object per line). */
+export const HOOK_EVENTS_FILE = join(tmpdir(), 'aerostack-guardian-events.jsonl');
+export async function installClaudeHook(_port) {
     const settingsPath = join(homedir(), '.claude', 'settings.json');
     try {
         let settings = {};
@@ -215,28 +281,26 @@ export async function installClaudeHook(port) {
         }
         const hooks = (settings.hooks ?? {});
         const preToolUse = (hooks.PreToolUse ?? []);
-        // Check if our hook already exists
-        const existing = preToolUse.findIndex(h => {
+        // Remove any old HTTP-based aerostack hooks
+        const cleaned = preToolUse.filter(h => {
             const innerHooks = (h.hooks ?? []);
-            return innerHooks.some(ih => ih.url?.includes('127.0.0.1') && ih.url?.includes('/hook'));
+            return !innerHooks.some(ih => (ih.url?.includes('127.0.0.1') && ih.url?.includes('/hook')) ||
+                (ih.command?.includes('aerostack-guardian')));
         });
+        // Command hook: reads stdin JSON, appends to JSONL file
+        // No HTTP, no port, no conflicts between sessions
         const hookEntry = {
             matcher: 'Bash|Write|Edit',
             hooks: [{
-                    type: 'http',
-                    url: `http://127.0.0.1:${port}/hook`,
+                    type: 'command',
+                    command: `cat >> ${HOOK_EVENTS_FILE}`,
                 }],
         };
-        if (existing >= 0) {
-            preToolUse[existing] = hookEntry;
-        }
-        else {
-            preToolUse.push(hookEntry);
-        }
-        hooks.PreToolUse = preToolUse;
+        cleaned.push(hookEntry);
+        hooks.PreToolUse = cleaned;
         settings.hooks = hooks;
         await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-        info('Installed Claude Code hook', { port, path: settingsPath });
+        info('Installed Claude Code hook (file-based)', { eventsFile: HOOK_EVENTS_FILE, path: settingsPath });
         return true;
     }
     catch (err) {

package/package.json CHANGED Viewed

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