@aiwerk/mcp-bridge 2.1.0 → 2.1.1

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.1",
   "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/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"
+  }
+}