@aiwerk/mcp-bridge 2.1.0 → 2.1.2

package/README.md

@@ -1,6 +1,6 @@
 # @aiwerk/mcp-bridge
 
-[![Tests](https://github.com/AIWerk/mcp-bridge/actions/workflows/test.yml/badge.svg)](https://github.com/AIWerk/mcp-bridge/actions/workflows/test.yml)
+[![CI](https://github.com/AIWerk/mcp-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/AIWerk/mcp-bridge/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@aiwerk/mcp-bridge.svg)](https://www.npmjs.com/package/@aiwerk/mcp-bridge)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -17,6 +17,12 @@ Most AI agents connect to MCP servers one-by-one. With 10+ servers, that's 10+ c
 - **Intent routing**: say what you need in plain language, the bridge finds the right tool
 - **Schema compression**: tool descriptions compressed ~57%, full schema on demand
 - **Security layer**: trust levels, tool deny/allow lists, result size limits
+- **HTTP auth**: bearer token, custom headers, and **OAuth2 Client Credentials** with automatic token management
+- **Result caching**: LRU cache with per-tool TTL overrides
+- **Batch calls**: parallel multi-tool execution via `action=batch`
+- **Multi-server resolution**: automatic tool disambiguation when multiple servers provide the same tool
+- **Configurable retries**: exponential backoff for transient errors
+- **Graceful shutdown**: clean process termination and connection cleanup
 - **Direct mode**: all tools registered individually with automatic prefixing
 - **3 transports**: stdio, SSE, streamable-http
 - **Built-in catalog**: 14 pre-configured servers, install with one command
@@ -363,6 +369,35 @@ When `action="call"` is used without `server=`, mcp-bridge can resolve collision
 | `sse` | `url`, `headers` | Remote SSE servers |
 | `streamable-http` | `url`, `headers` | Modern HTTP-based servers |
 
+### Authentication
+
+SSE and streamable-HTTP transports support three auth methods:
+
+**Bearer token:**
+```json
+{ "auth": { "type": "bearer", "token": "${MY_API_TOKEN}" } }
+```
+
+**Custom headers:**
+```json
+{ "auth": { "type": "header", "headers": { "X-API-Key": "${MY_KEY}" } } }
+```
+
+**OAuth2 Client Credentials** (automatic token management):
+```json
+{
+  "auth": {
+    "type": "oauth2",
+    "clientId": "${CLIENT_ID}",
+    "clientSecret": "${CLIENT_SECRET}",
+    "tokenUrl": "https://provider.com/oauth/token",
+    "scopes": ["read", "write"]
+  }
+}
+```
+
+OAuth2 features: automatic token acquisition, caching with expiry-aware refresh, single-attempt 401 retry, env var substitution in credentials.
+
 ### Environment variables
 
 Secrets go in `~/.mcp-bridge/.env` (chmod 600 on init):
@@ -459,6 +494,36 @@ const result = await router.dispatch("todoist", "call", "find-tasks", { query: "
                         └──────────────────────────────────────────────┘
 ```
 
+## Security Limitations
+
+The built-in security layer (trust levels, tool filters, result sanitization) provides **baseline protection** for common threats:
+
+- Prompt injection patterns (known strings)
+- Oversized responses
+- Unauthorized tool access
+
+**What it does NOT cover:**
+- Unicode obfuscation / homoglyph attacks
+- Sophisticated multi-step injection chains
+- Content-level PII detection
+
+For production deployments with high security requirements, consider adding an external content filtering layer (e.g., guardrails, PII redaction service) between the bridge and your application.
+
+## Roadmap
+
+| Status | Feature | Version |
+|--------|---------|---------|
+| ✅ | Smart Router v2 (intent, cache, batch, resolution) | 1.9.0 |
+| ✅ | HTTP auth (bearer, headers) | 2.0.0 |
+| ✅ | Configurable retries + graceful shutdown | 2.0.0 |
+| ✅ | OAuth2 Client Credentials | 2.1.0 |
+| 🔜 | Hosted bridge (bridge.aiwerk.ch) | planned |
+| 🔜 | Remote catalog integration | planned |
+| 🔜 | OpenTelemetry / Prometheus metrics | planned |
+| 🔜 | PII redaction | planned |
+
+See [docs/hosted-bridge-spec.md](docs/hosted-bridge-spec.md) for the hosted bridge architecture.
+
 ## Related
 
 - **[@aiwerk/openclaw-mcp-bridge](https://github.com/AIWerk/openclaw-mcp-bridge)** — OpenClaw plugin wrapper (uses this package as core)

package/dist/src/index.d.ts

@@ -17,6 +17,6 @@ export type { Logger, McpServerConfig, McpClientConfig, HttpAuthConfig, RetryCon
 export { nextRequestId } from "./types.js";
 export { pickRegisteredToolName } from "./tool-naming.js";
 export { StandaloneServer } from "./standalone-server.js";
-export { checkForUpdate, getUpdateNotice, runUpdate, resetNoticeFlag } from "./update-checker.js";
-export type { UpdateInfo } from "./update-checker.js";
+export { checkForUpdate, checkPluginUpdate, getUpdateNotice, runUpdate, resetNoticeFlag } from "./update-checker.js";
+export type { UpdateInfo, PluginUpdateInfo } from "./update-checker.js";
 export { filterServers, buildFilteredDescription } from "./smart-filter.js";

package/dist/src/index.js

@@ -22,6 +22,6 @@ export { pickRegisteredToolName } from "./tool-naming.js";
 // Standalone server
 export { StandaloneServer } from "./standalone-server.js";
 // Update checker
-export { checkForUpdate, getUpdateNotice, runUpdate, resetNoticeFlag } from "./update-checker.js";
+export { checkForUpdate, checkPluginUpdate, getUpdateNotice, runUpdate, resetNoticeFlag } from "./update-checker.js";
 // Smart filter
 export { filterServers, buildFilteredDescription } from "./smart-filter.js";

package/dist/src/update-checker.d.ts

@@ -6,11 +6,22 @@ export interface UpdateInfo {
     updateCommand: string;
     updateCommandParts: string[];
 }
+export interface PluginUpdateInfo {
+    pluginName: string;
+    currentVersion: string;
+    latestVersion: string;
+    updateAvailable: boolean;
+}
 /**
  * Check npm registry for a newer version. Non-blocking, best-effort.
  * Caches result for the lifetime of the process.
  */
 export declare function checkForUpdate(logger: Logger): Promise<UpdateInfo>;
+/**
+ * Check if a wrapper plugin (e.g. openclaw-mcp-bridge) has an update.
+ * The caller passes the installed plugin version; we check npm for the latest.
+ */
+export declare function checkPluginUpdate(pluginName: string, installedVersion: string, logger: Logger): Promise<PluginUpdateInfo>;
 /**
  * Build the notice string to inject into the first tool response.
  * Returns empty string if no update or already delivered.

package/dist/src/update-checker.js

@@ -1,7 +1,9 @@
 import { execFileSync, execFile } from "child_process";
 import { PACKAGE_VERSION } from "./protocol.js";
 const PACKAGE_NAME = "@aiwerk/mcp-bridge";
+const PLUGIN_PACKAGE_NAME = "@aiwerk/openclaw-mcp-bridge";
 let cachedUpdateInfo = null;
+let cachedPluginUpdateInfo = null;
 let noticeDelivered = false;
 /**
  * Check npm registry for a newer version. Non-blocking, best-effort.
@@ -42,16 +44,59 @@ export async function checkForUpdate(logger) {
     }
     return cachedUpdateInfo;
 }
+/**
+ * Check if a wrapper plugin (e.g. openclaw-mcp-bridge) has an update.
+ * The caller passes the installed plugin version; we check npm for the latest.
+ */
+export async function checkPluginUpdate(pluginName, installedVersion, logger) {
+    if (cachedPluginUpdateInfo)
+        return cachedPluginUpdateInfo;
+    try {
+        const latest = await npmViewVersionOf(pluginName, logger);
+        const updateAvailable = latest !== installedVersion && isNewer(latest, installedVersion);
+        cachedPluginUpdateInfo = {
+            pluginName,
+            currentVersion: installedVersion,
+            latestVersion: latest,
+            updateAvailable,
+        };
+        if (updateAvailable) {
+            logger.info(`[mcp-bridge] Plugin update available: ${pluginName} ${installedVersion} → ${latest}`);
+        }
+    }
+    catch (err) {
+        logger.warn(`[mcp-bridge] Plugin version check failed: ${err instanceof Error ? err.message : err}`);
+        cachedPluginUpdateInfo = {
+            pluginName,
+            currentVersion: installedVersion,
+            latestVersion: installedVersion,
+            updateAvailable: false,
+        };
+    }
+    return cachedPluginUpdateInfo;
+}
 /**
  * Build the notice string to inject into the first tool response.
  * Returns empty string if no update or already delivered.
  */
 export function getUpdateNotice() {
-    if (noticeDelivered || !cachedUpdateInfo?.updateAvailable)
+    const coreUpdate = cachedUpdateInfo?.updateAvailable;
+    const pluginUpdate = cachedPluginUpdateInfo?.updateAvailable;
+    if (noticeDelivered || (!coreUpdate && !pluginUpdate))
         return "";
     noticeDelivered = true;
-    return (`\n\n---\nUpdate available: ${cachedUpdateInfo.currentVersion} → ${cachedUpdateInfo.latestVersion}\n` +
-        `Run: ${cachedUpdateInfo.updateCommand}`);
+    const lines = ["\n\n---"];
+    if (coreUpdate) {
+        lines.push(`Core update: ${cachedUpdateInfo.currentVersion} → ${cachedUpdateInfo.latestVersion}`);
+    }
+    if (pluginUpdate) {
+        lines.push(`Plugin update: ${cachedPluginUpdateInfo.pluginName} ${cachedPluginUpdateInfo.currentVersion} → ${cachedPluginUpdateInfo.latestVersion}`);
+    }
+    const installCmd = cachedPluginUpdateInfo?.pluginName
+        ? `openclaw plugins install ${cachedPluginUpdateInfo.pluginName}`
+        : cachedUpdateInfo.updateCommand;
+    lines.push(`Run: ${installCmd}`);
+    return lines.join("\n");
 }
 /**
  * Reset the notice flag (for testing).
@@ -89,8 +134,11 @@ export async function runUpdate(logger) {
 }
 // --- helpers ---
 function npmViewVersion(_logger) {
+    return npmViewVersionOf(PACKAGE_NAME, _logger);
+}
+function npmViewVersionOf(packageName, _logger) {
     return new Promise((resolve, reject) => {
-        execFile("npm", ["view", PACKAGE_NAME, "version"], { encoding: "utf-8", timeout: 10_000 }, (err, stdout) => {
+        execFile("npm", ["view", packageName, "version"], { encoding: "utf-8", timeout: 10_000 }, (err, stdout) => {
             if (err)
                 return reject(err);
             const ver = (stdout ?? "").trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwerk/mcp-bridge",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Standalone MCP server that multiplexes multiple MCP servers into one interface",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -45,13 +45,21 @@
     "test": "node --import tsx --test tests/*.test.ts",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build",
-    "validate-recipe": "npx tsx bin/validate-recipe.ts"
+    "validate-recipe": "npx tsx bin/validate-recipe.ts",
+    "lint": "eslint src/",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/"
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.0",
+    "@typescript-eslint/parser": "^8.57.0",
+    "eslint": "^10.0.3",
+    "prettier": "^3.8.1",
     "tsx": "^4.0.0",
     "typescript": "^5.7.0"
   }

package/scripts/install-server.sh

@@ -2,9 +2,27 @@
 set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-MCP_BRIDGE_DIR="${HOME}/.mcp-bridge"
-MCP_BRIDGE_JSON="${MCP_BRIDGE_DIR}/config.json"
-ENV_FILE="${MCP_BRIDGE_DIR}/.env"
+
+# Detect OpenClaw plugin or standalone mode
+OPENCLAW_JSON="${HOME}/.openclaw/openclaw.json"
+OPENCLAW_PLUGIN_DIR="${HOME}/.openclaw/extensions/openclaw-mcp-bridge"
+if [[ -f "$OPENCLAW_JSON" ]] && python3 -c "
+import json
+with open('$OPENCLAW_JSON') as f:
+    c = json.load(f)
+assert 'openclaw-mcp-bridge' in c.get('plugins',{}).get('entries',{})
+" 2>/dev/null; then
+    CONFIG_MODE="openclaw"
+    MCP_BRIDGE_DIR="$OPENCLAW_PLUGIN_DIR"
+    MCP_BRIDGE_JSON="$OPENCLAW_JSON"
+    ENV_FILE="${HOME}/.openclaw/.env"
+    echo "[mcp-bridge] Detected OpenClaw plugin mode"
+else
+    CONFIG_MODE="standalone"
+    MCP_BRIDGE_DIR="${HOME}/.mcp-bridge"
+    MCP_BRIDGE_JSON="${MCP_BRIDGE_DIR}/config.json"
+    ENV_FILE="${MCP_BRIDGE_DIR}/.env"
+fi
 
 usage() {
     echo "Usage: $0 <server-name> [--dry-run] [--remove]"
@@ -160,11 +178,15 @@ if [[ "$REMOVE" == "true" ]]; then
 import json, sys
 server_name = sys.argv[1]
 config_path = sys.argv[2]
+config_mode = sys.argv[3]
 with open(config_path) as f:
     cfg = json.load(f)
-servers = cfg.get('servers',{})
+if config_mode == 'openclaw':
+    servers = cfg.get('plugins',{}).get('entries',{}).get('openclaw-mcp-bridge',{}).get('config',{}).get('servers',{})
+else:
+    servers = cfg.get('servers',{})
 print('yes' if server_name in servers else 'no')
-" "$SERVER_NAME" "$MCP_BRIDGE_JSON" 2>/dev/null)
+" "$SERVER_NAME" "$MCP_BRIDGE_JSON" "$CONFIG_MODE" 2>/dev/null)
 
     if [[ "$HAS_SERVER" != "yes" ]]; then
         echo "ℹ️  Server '$SERVER_NAME' not found in config. Nothing to remove."
@@ -181,16 +203,20 @@ print('yes' if server_name in servers else 'no')
 import json, sys
 server_name = sys.argv[1]
 config_path = sys.argv[2]
+config_mode = sys.argv[3]
 with open(config_path) as f:
     cfg = json.load(f)
-servers = cfg.get('servers', {})
+if config_mode == 'openclaw':
+    servers = cfg['plugins']['entries']['openclaw-mcp-bridge']['config']['servers']
+else:
+    servers = cfg.get('servers', {})
 del servers[server_name]
 with open(config_path, 'w') as f:
     json.dump(cfg, f, indent=2)
     f.write('\n')
 print(f'✅ Removed {server_name} from config')
 print(f'ℹ️  Server recipe kept in servers/{server_name}/ (reinstall anytime)')
-" "$SERVER_NAME" "$MCP_BRIDGE_JSON" 2>/dev/null
+" "$SERVER_NAME" "$MCP_BRIDGE_JSON" "$CONFIG_MODE" 2>/dev/null
 
     # Remove env var from .env if exists
     REMOVE_ENV_VAR=""

package/scripts/validate-recipes.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+# validate-recipes.sh — Verify all recipe.json URLs are reachable (no hallucinated repos!)
+# Usage: ./scripts/validate-recipes.sh [--ci]
+# Exit code 1 if any URL is broken.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SERVERS_DIR="$SCRIPT_DIR/../servers"
+CI_MODE="${1:-}"
+ERRORS=0
+CHECKED=0
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+echo "Validating recipe URLs..."
+echo ""
+
+for recipe in "$SERVERS_DIR"/*/recipe.json; do
+  server=$(basename "$(dirname "$recipe")")
+  
+  # Extract all URLs from recipe.json
+  urls=$(python3 -c "
+import json, sys
+d = json.load(open('$recipe'))
+urls = set()
+if d.get('repository'): urls.add(d['repository'])
+if d.get('install', {}).get('repository'): urls.add(d['install']['repository'])
+if d.get('metadata', {}).get('homepage'): urls.add(d['metadata']['homepage'])
+if d.get('auth', {}).get('credentialsUrl'): urls.add(d['auth']['credentialsUrl'])
+for u in sorted(urls): print(u)
+" 2>/dev/null)
+
+  # Cross-check git repos against install-server.sh
+  install_script="$SCRIPT_DIR/install-server.sh"
+  if [ -f "$install_script" ]; then
+    # Match server name in the clone context (e.g. "wise)" or "Cloning wise")
+    script_repo=$(grep -B1 -A0 -i "${server})" "$install_script" 2>/dev/null | grep -oP "git clone \Khttps://[^ ]+" | head -1 | sed 's/\.git$//')
+    recipe_repo=$(python3 -c "
+import json
+d = json.load(open('$recipe'))
+r = d.get('install', {}).get('repository', d.get('repository', ''))
+print(r.rstrip('/').removesuffix('.git'))
+" 2>/dev/null)
+    
+    if [ -n "$script_repo" ] && [ -n "$recipe_repo" ]; then
+      script_repo_clean=$(echo "$script_repo" | sed 's/\.git$//')
+      if [ "$recipe_repo" != "$script_repo_clean" ]; then
+        echo -e "${RED}❌ MISMATCH [$server]${NC}"
+        echo "   recipe.json:       $recipe_repo"
+        echo "   install-server.sh: $script_repo_clean"
+        ERRORS=$((ERRORS + 1))
+      fi
+    fi
+  fi
+
+  # HTTP check all URLs
+  for url in $urls; do
+    CHECKED=$((CHECKED + 1))
+    status=$(curl -sI -o /dev/null -w "%{http_code}" --max-time 10 "$url" 2>/dev/null || echo "000")
+    # 401/403 are OK for credentialsUrl (login-protected pages)
+    if [ "$status" = "000" ] || [ "$status" -ge 404 ]; then
+      echo -e "${RED}❌ HTTP $status [$server] $url${NC}"
+      ERRORS=$((ERRORS + 1))
+    else
+      echo -e "${GREEN}✓${NC} [$server] $url"
+    fi
+  done
+done
+
+echo ""
+echo "Checked $CHECKED URLs across $(ls -d "$SERVERS_DIR"/*/recipe.json 2>/dev/null | wc -l) recipes."
+
+if [ $ERRORS -gt 0 ]; then
+  echo -e "${RED}$ERRORS error(s) found!${NC}"
+  exit 1
+else
+  echo -e "${GREEN}All URLs valid.${NC}"
+  exit 0
+fi

package/servers/hetzner/recipe.json

@@ -3,7 +3,7 @@
   "id": "hetzner",
   "name": "Hetzner Cloud",
   "description": "Manage Hetzner Cloud infrastructure — servers, networks, load balancers, volumes, firewalls, and more via the Hetzner Cloud API",
-  "repository": "https://github.com/valerius21/hetzner-mcp",
+  "repository": "https://github.com/dkruyt/mcp-hetzner",
 
   "transports": [
     {
@@ -26,14 +26,14 @@
 
   "install": {
     "method": "git",
-    "repository": "https://github.com/valerius21/hetzner-mcp",
+    "repository": "https://github.com/dkruyt/mcp-hetzner",
     "buildCommand": "npm install && npm run build",
     "version": "latest"
   },
 
   "metadata": {
     "homepage": "https://www.hetzner.com/cloud",
-    "author": "valerius21",
+    "author": "dkruyt",
     "tags": ["cloud", "infrastructure", "servers", "vps", "hetzner"],
     "category": "infrastructure",
     "pricing": "byok",

package/servers/imap-email/recipe.json

@@ -0,0 +1,45 @@
+{
+  "id": "imap-email",
+  "schemaVersion": 2,
+  "name": "IMAP Email",
+  "description": "Email tools for any IMAP/SMTP provider - list, read, search, send, manage emails",
+  "recipeVersion": "1.0.0",
+  "metadata": {
+    "category": "communication",
+    "tags": ["email", "imap", "smtp", "inbox"],
+    "country": "global",
+    "language": "en",
+    "homepage": "https://github.com/AIWerk/mcp-server-imap",
+    "license": "MIT",
+    "pricing": "free",
+    "maturity": "beta"
+  },
+  "transports": [
+    {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@aiwerk/mcp-server-imap"],
+      "env": {
+        "IMAP_HOST": "${IMAP_HOST}",
+        "IMAP_PORT": "${IMAP_PORT}",
+        "IMAP_USER": "${IMAP_USER}",
+        "IMAP_PASS": "${IMAP_PASS}",
+        "SMTP_HOST": "${SMTP_HOST}",
+        "SMTP_PORT": "${SMTP_PORT}",
+        "SMTP_SEND_ENABLED": "${SMTP_SEND_ENABLED}"
+      }
+    }
+  ],
+  "auth": {
+    "required": true,
+    "type": "api-key",
+    "envVars": ["IMAP_HOST", "IMAP_USER", "IMAP_PASS"],
+    "instructions": "Set your IMAP server hostname, username (email), and password. For Gmail use an App Password. Set SMTP_SEND_ENABLED=true to enable email sending.",
+    "bootstrap": "env-only"
+  },
+  "capabilities": {
+    "toolCount": 10,
+    "toolNames": ["email_list", "email_read", "email_search", "email_folders", "email_move", "email_flag", "email_delete", "email_send", "email_reply", "email_attachment"],
+    "sideEffects": "external-write"
+  }
+}

package/servers/wise/recipe.json

@@ -3,7 +3,7 @@
   "id": "wise",
   "name": "Wise",
   "description": "International money transfers and multi-currency account management via the Wise (TransferWise) API",
-  "repository": "https://github.com/kstam/wise-mcp",
+  "repository": "https://github.com/Szotasz/wise-mcp",
 
   "transports": [
     {
@@ -26,14 +26,14 @@
 
   "install": {
     "method": "git",
-    "repository": "https://github.com/kstam/wise-mcp",
+    "repository": "https://github.com/Szotasz/wise-mcp",
     "buildCommand": "npm install && npm run build",
     "version": "latest"
   },
 
   "metadata": {
     "homepage": "https://wise.com/",
-    "author": "kstam",
+    "author": "Szotasz",
     "tags": ["payments", "transfers", "international", "currency", "fintech"],
     "category": "finance",
     "pricing": "byok",