@aiwerk/mcp-bridge 2.8.45 → 2.9.0

package/README.md

@@ -3,7 +3,7 @@
 [![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)
-[![Status: maintenance](https://img.shields.io/badge/status-maintenance-blue.svg)](#status)
+[![Status: active](https://img.shields.io/badge/status-active-brightgreen.svg)](#status)
 
 **Your AI, Connected to Everything.** Multiplex multiple MCP servers into one interface. One config, one connection, all your tools.
 
@@ -13,32 +13,29 @@ Works with **Claude Code**, **Codex (OpenAI)**, **Claude Desktop**, **Cursor**,
 
 ## Status
 
-`@aiwerk/mcp-bridge` is in **maintenance mode** as of 2026-04-10.
+`@aiwerk/mcp-bridge` is **actively developed** as of 2026-05-03.
 
-Primary development has moved to the hosted **AIWerk MCP Platform** at
-[aiwerkmcp.com](https://aiwerkmcp.com) — a multi-tenant hosted MCP bridge
-with catalog, authentication, per-user isolation and OAuth2 built in.
-For most use cases, the hosted platform is a simpler and more featureful
-choice than running the standalone router yourself.
+The primary use case is the **local install path for the AIWerk catalog** at
+[aiwerkmcp.com](https://aiwerkmcp.com). Some recipes (those marked
+`localOnly: true`, e.g. `chrome-devtools`) need a browser, display, USB
+device or user-specific local path that the hosted bridge cannot reach;
+this package is the recommended way to run them.
 
-This standalone package remains supported for:
+It also serves:
 
 - **OpenClaw plugin users** via [`@aiwerk/openclaw-mcp-bridge`](https://github.com/AIWerk/openclaw-mcp-bridge),
   which embeds this library and ships its own recipe-install tooling.
-- **Self-hosted / offline deployments** where talking to a hosted service
-  is not an option.
+- **Self-hosted / offline deployments** where the hosted service is not an
+  option.
 - **Library consumers** that import `McpRouter`, transports and the OAuth2
   token manager directly.
 
-The published package is frozen on version `2.8.x`. Security fixes and
-compatibility updates (new Node.js, new MCP protocol revisions) may still
-ship, but no new features are planned. The bundled `servers/` directory
-is retained as a set of **reference recipe examples** you can copy into
-your own `~/.mcp-bridge/config.json` — it is not a curated catalog and
-does not auto-update. As of this release the only remaining network
-coupling with AIWerk infrastructure has been removed: the install helper
-no longer fetches recipes over HTTP and only reads from the bundled
-`servers/` directory.
+Active development tracks the **Universal Recipe Spec v2** alongside the
+hosted bridge — new fields like `localOnly`, `multiInstance`,
+`auth.options[]` and `envBinding` are being ported, and the bundled
+`servers/` directory is being kept in sync with the catalog. The install
+helper does not fetch recipes over HTTP — recipes come from the bundled
+`servers/` directory only.
 
 ## Why?
 

package/dist/bin/mcp-bridge.js

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
-import { readFileSync, existsSync, writeFileSync, unlinkSync } from "fs";
+import { readFileSync, existsSync, writeFileSync, mkdirSync, unlinkSync } from "fs";
 import { join, dirname, resolve, extname } from "path";
 import { fileURLToPath } from "url";
 import { homedir } from "os";
 import { execFileSync, execSync } from "child_process";
-import { loadConfig, initConfigDir } from "../src/config.js";
+import { loadConfig, initConfigDir, recipeToServerConfig, collectRequiredEnvVars } from "../src/config.js";
 import { StandaloneServer } from "../src/standalone-server.js";
 import { PACKAGE_VERSION } from "../src/protocol.js";
 import { checkForUpdate, runUpdate } from "../src/update-checker.js";
 import { FileTokenStore } from "../src/token-store.js";
 import { performAuthCodeLogin, performDeviceCodeLogin } from "../src/cli-auth.js";
 import { RateLimiter } from "../src/rate-limiter.js";
+import { CatalogClient, CatalogError, CatalogSignatureError } from "../src/catalog-client.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // After tsc, this file lives at dist/bin/mcp-bridge.js.
@@ -132,6 +133,15 @@ function parseArgs(argv) {
             case "init":
                 args.command = "init";
                 break;
+            case "install":
+                args.command = "install";
+                break;
+            case "search":
+                args.command = "search";
+                break;
+            case "catalog":
+                args.command = "catalog";
+                break;
             case "remove":
             case "uninstall":
                 args.command = "remove";
@@ -185,6 +195,9 @@ Usage:
   mcp-bridge --sse --port 3000      Start as SSE server
   mcp-bridge --http --port 3000     Start as streamable-http server
   mcp-bridge init [--register <client>] [--mode router|direct]  Create config + optionally register
+  mcp-bridge install <server>       Install a server from the AIWerk catalog (signature-verified)
+  mcp-bridge catalog [--offline]    List available servers from the catalog
+  mcp-bridge search <query>         Search the catalog by keyword
   mcp-bridge remove <server>        Remove a configured server
   mcp-bridge set-env <KEY> <value>  Set an API key in ~/.mcp-bridge/.env
   mcp-bridge servers                List configured servers and current mode
@@ -488,6 +501,128 @@ function cmdLimit(args, logger) {
         process.exit(1);
     }
 }
+async function cmdInstall(serverName, args, logger) {
+    const configPath = resolveConfigPath(args.configPath);
+    const configDir = dirname(configPath);
+    if (!existsSync(configDir)) {
+        mkdirSync(configDir, { recursive: true });
+    }
+    if (!existsSync(configPath)) {
+        writeFileSync(configPath, JSON.stringify({ servers: {} }, null, 2) + "\n", "utf-8");
+        logger.info(`Created config: ${configPath}`);
+    }
+    const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+    if (!raw.servers)
+        raw.servers = {};
+    if (raw.servers[serverName]) {
+        process.stdout.write(`Server "${serverName}" is already configured.\n`);
+        process.stdout.write(`Config: ${configPath}\n`);
+        return;
+    }
+    process.stdout.write(`Fetching recipe for ${serverName} from bridge.aiwerk.ch...\n`);
+    const cacheDir = join(configDir, "recipes");
+    const client = new CatalogClient({ cacheDir, logger });
+    let recipe;
+    try {
+        recipe = await client.resolve(serverName);
+    }
+    catch (err) {
+        if (err instanceof CatalogSignatureError) {
+            logger.error(err.message);
+            process.stderr.write(`\nThe recipe was rejected because its Ed25519 signature did not match the AIWerk catalog public key. This means either the catalog was tampered with in transit, or your local cache was modified. Nothing has been written to your config.\n`);
+        }
+        else if (err instanceof CatalogError) {
+            logger.error(err.message);
+        }
+        else {
+            logger.error(`Failed to fetch recipe: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        process.exit(1);
+    }
+    if (recipe.localOnly) {
+        process.stdout.write(`\nNote: "${serverName}" is marked localOnly — it needs your local environment (browser, display, USB, or user-specific paths) and cannot run on the hosted bridge. You are installing it locally, which is the right place.\n\n`);
+    }
+    const serverConfig = recipeToServerConfig(recipe);
+    if (!serverConfig) {
+        logger.error(`Unsupported recipe format for "${serverName}"`);
+        process.exit(1);
+    }
+    const requiredVars = collectRequiredEnvVars(recipe);
+    const missing = requiredVars.filter((v) => v !== "__AUTH_REQUIRED__" && !process.env[v]);
+    raw.servers[serverName] = serverConfig;
+    writeFileSync(configPath, JSON.stringify(raw, null, 2) + "\n", "utf-8");
+    process.stdout.write(`✓ Added "${serverName}" to ${configPath}\n\n`);
+    if (missing.length > 0) {
+        process.stdout.write(`Missing environment variables:\n`);
+        for (const v of missing) {
+            process.stdout.write(`  ${v}\n`);
+        }
+        const credUrl = recipe.auth?.credentialsUrl;
+        if (typeof credUrl === "string") {
+            process.stdout.write(`\nGet credentials: ${credUrl}\n`);
+        }
+        process.stdout.write(`\nSet them in your environment or ~/.mcp-bridge/.env before starting the bridge.\n`);
+    }
+    else if (requiredVars.length > 0) {
+        process.stdout.write(`All required environment variables are set. Ready to use.\n`);
+    }
+    else {
+        process.stdout.write(`No credentials required. Ready to use.\n`);
+    }
+}
+async function cmdCatalog(args, logger) {
+    const configPath = resolveConfigPath(args.configPath);
+    const cacheDir = join(dirname(configPath), "recipes");
+    const client = new CatalogClient({ cacheDir, logger });
+    if (args.offline) {
+        const cached = client.listCached();
+        if (cached.length === 0) {
+            process.stdout.write(`No cached recipes. Run 'mcp-bridge install <server>' to fetch one.\n`);
+            return;
+        }
+        process.stdout.write(`\nCached recipes (${cached.length}):\n\n`);
+        for (const name of cached.sort()) {
+            const r = client.getCached(name);
+            const desc = r?.description ?? "";
+            process.stdout.write(`  ${name.padEnd(24)}${desc.slice(0, 60)}\n`);
+        }
+        return;
+    }
+    try {
+        const { results } = await client.list({ limit: 100 });
+        process.stdout.write(`\nAvailable servers (${results.length} from bridge.aiwerk.ch):\n\n`);
+        for (const r of results) {
+            const desc = (r.description ?? "").slice(0, 60);
+            process.stdout.write(`  ${r.name.padEnd(24)}${desc}\n`);
+        }
+        process.stdout.write(`\nInstall: mcp-bridge install <name>\n`);
+    }
+    catch (err) {
+        logger.error(`Failed to fetch catalog: ${err instanceof Error ? err.message : String(err)}`);
+        process.stderr.write(`Use 'mcp-bridge catalog --offline' to list cached recipes.\n`);
+        process.exit(1);
+    }
+}
+async function cmdSearch(query, logger) {
+    const client = new CatalogClient({ logger });
+    try {
+        const results = await client.search(query);
+        if (results.length === 0) {
+            process.stdout.write(`No matches for "${query}".\n`);
+            return;
+        }
+        process.stdout.write(`\nMatches for "${query}" (${results.length}):\n\n`);
+        for (const r of results) {
+            const desc = (r.description ?? "").slice(0, 60);
+            process.stdout.write(`  ${r.name.padEnd(24)}${desc}\n`);
+        }
+        process.stdout.write(`\nInstall: mcp-bridge install <name>\n`);
+    }
+    catch (err) {
+        logger.error(`Search failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+}
 function cmdRemove(serverName, args, logger) {
     const configPath = resolveConfigPath(args.configPath);
     if (!existsSync(configPath)) {
@@ -798,6 +933,23 @@ async function main() {
         case "limit":
             cmdLimit(args, logger);
             break;
+        case "install":
+            if (args.positional.length === 0) {
+                process.stderr.write("Usage: mcp-bridge install <server>\n");
+                process.exit(1);
+            }
+            await cmdInstall(args.positional[0], args, logger);
+            break;
+        case "catalog":
+            await cmdCatalog(args, logger);
+            break;
+        case "search":
+            if (args.positional.length === 0) {
+                process.stderr.write("Usage: mcp-bridge search <query>\n");
+                process.exit(1);
+            }
+            await cmdSearch(args.positional.join(" "), logger);
+            break;
         case "remove":
             if (args.positional.length === 0) {
                 process.stderr.write("Usage: mcp-bridge remove <server>\n");

package/dist/src/catalog-client.d.ts

@@ -1,8 +1,11 @@
 /**
- * CatalogClient — REST client for the AIWerk MCP Catalog API.
+ * CatalogClient — REST client for the AIWerk MCP catalog at bridge.aiwerk.ch.
  *
- * Default endpoint: https://catalog.aiwerk.ch
- * Supports local file caching with offline fallback.
+ * Restored 2026-05-03 after maintenance mode ended. Endpoint moved from the
+ * historical catalog.aiwerk.ch to bridge.aiwerk.ch/api/recipes/<name>/download.
+ * Every fetched recipe is Ed25519-verified against the bundled AIWerk public
+ * key before it is cached or returned. Unsigned or tampered recipes are
+ * refused.
  */
 import type { Logger } from "./types.js";
 export interface CatalogSearchResult {
@@ -12,6 +15,13 @@ export interface CatalogSearchResult {
     quality?: number;
     [key: string]: unknown;
 }
+export interface RecipeSignature {
+    algorithm: string;
+    publisherId: string;
+    value: string;
+    signedFields: string[];
+    signedAt: string;
+}
 export interface CatalogRecipe {
     name: string;
     description?: string;
@@ -30,6 +40,9 @@ export interface CatalogRecipe {
         headers?: Record<string, string>;
     }>;
     install?: {
+        method?: string;
+        package?: string;
+        version?: string;
         npm?: {
             package: string;
             version?: string;
@@ -44,34 +57,49 @@ export interface CatalogRecipe {
         envVars?: string[];
         credentialsUrl?: string;
     };
+    signature?: RecipeSignature;
+    localOnly?: boolean;
     [key: string]: unknown;
 }
 export declare class CatalogError extends Error {
     constructor(message: string);
 }
+export declare class CatalogSignatureError extends CatalogError {
+    constructor(message: string);
+}
 /**
- * CatalogClient — REST client for the AIWerk MCP Catalog API.
- *
- * NOTE: File I/O operations (readCache, writeCache, etc.) are intentionally
- * synchronous. This is acceptable for CLI tools and bridge startup, but
- * should be converted to async if used in hot paths (e.g., per-request).
+ * Verify the Ed25519 signature on a recipe against the bundled AIWerk public
+ * key. Throws CatalogSignatureError on any failure (missing signature, wrong
+ * algorithm, tampered payload, key mismatch).
+ */
+export declare function verifyRecipeSignature(recipe: CatalogRecipe): void;
+export interface CatalogClientOptions {
+    baseUrl?: string;
+    cacheDir?: string;
+    logger?: Logger;
+    staleDays?: number;
+    /** Skip signature verification (testing only). */
+    skipSignatureVerify?: boolean;
+}
+/**
+ * REST client for the AIWerk MCP catalog. File I/O is intentionally
+ * synchronous — fine for CLI tools and bridge startup. Signature verification
+ * runs on every fetch (including cache reads) so a tampered cache cannot
+ * silently slip through.
  */
 export declare class CatalogClient {
     private baseUrl;
     private cacheDir;
     private logger;
     private staleMs;
-    constructor(opts?: {
-        baseUrl?: string;
-        cacheDir?: string;
-        logger?: Logger;
-        staleDays?: number;
-    });
+    private skipSignatureVerify;
+    constructor(opts?: CatalogClientOptions);
     private fetchJson;
     private cachePath;
     private readCache;
     private writeCache;
     private isCacheStale;
+    private verifyOrThrow;
     /** Search for recipes by keyword. */
     search(query: string): Promise<CatalogSearchResult[]>;
     /** List recipes with optional filtering. */
@@ -79,23 +107,23 @@ export declare class CatalogClient {
         limit?: number;
         category?: string;
         sort?: string;
-        hostedSafe?: boolean;
     }): Promise<{
         results: CatalogSearchResult[];
         total: number;
     }>;
-    /** Download a recipe from the catalog and cache it locally. */
-    download(name: string): Promise<CatalogRecipe>;
     /**
-     * Resolve a recipe — returns cached if available, otherwise fetches from catalog.
-     * Falls back to cache when the catalog is unreachable (offline mode).
+     * Download a recipe from the catalog, verify its signature, and cache it
+     * locally. Throws CatalogSignatureError if the recipe is unsigned or
+     * tampered — nothing is written to the cache in that case.
      */
-    resolve(name: string): Promise<CatalogRecipe>;
+    download(name: string): Promise<CatalogRecipe>;
     /**
-     * Bootstrap by downloading the top N most popular recipes.
-     * Skips already-cached recipes unless they are stale.
+     * Resolve a recipe by name. Returns the cached copy if fresh; otherwise
+     * fetches from the catalog. Falls back to a stale cache if the network is
+     * unreachable. Signature is verified on both fresh and cached paths so a
+     * tampered cache cannot slip through.
      */
-    bootstrap(limit?: number, hostedSafe?: boolean): Promise<string[]>;
+    resolve(name: string): Promise<CatalogRecipe>;
     /** Synchronously read a recipe from local cache. Returns null if not cached. */
     getCached(name: string): CatalogRecipe | null;
     /** List all recipe names in the local cache. */

package/dist/src/catalog-client.js

@@ -1,45 +1,121 @@
 /**
- * CatalogClient — REST client for the AIWerk MCP Catalog API.
+ * CatalogClient — REST client for the AIWerk MCP catalog at bridge.aiwerk.ch.
  *
- * Default endpoint: https://catalog.aiwerk.ch
- * Supports local file caching with offline fallback.
+ * Restored 2026-05-03 after maintenance mode ended. Endpoint moved from the
+ * historical catalog.aiwerk.ch to bridge.aiwerk.ch/api/recipes/<name>/download.
+ * Every fetched recipe is Ed25519-verified against the bundled AIWerk public
+ * key before it is cached or returned. Unsigned or tampered recipes are
+ * refused.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-// ── Error ────────────────────────────────────────────────────────────────────
+import { createPublicKey, verify } from "node:crypto";
+// ── Public key (Ed25519, AIWerk catalog signer) ──────────────────────────────
+//
+// The hosted bridge signs every recipe with the matching private key kept in
+// pass under aiwerk/mcp-catalog-private-key. The public key is baked into
+// the standalone bundle so a fresh install does not need to fetch it.
+const AIWERK_CATALOG_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAkHESasC8Mbf2+pGe+bhKRQkgOBSPcqGj0ZWGop4TS6k=
+-----END PUBLIC KEY-----
+`;
+const SIGNED_FIELDS = [
+    "id",
+    "name",
+    "description",
+    "transports",
+    "auth",
+    "install",
+    "metadata",
+    "skill",
+    "localOnly",
+];
+// ── Errors ───────────────────────────────────────────────────────────────────
 export class CatalogError extends Error {
     constructor(message) {
         super(message);
         this.name = "CatalogError";
     }
 }
+export class CatalogSignatureError extends CatalogError {
+    constructor(message) {
+        super(message);
+        this.name = "CatalogSignatureError";
+    }
+}
 // ── Helpers ──────────────────────────────────────────────────────────────────
 const TIMEOUT_MS = 5_000;
+const DEFAULT_BASE_URL = "https://bridge.aiwerk.ch";
 const noop = {
     info: () => { },
     warn: () => { },
     error: () => { },
     debug: () => { },
 };
-// ── CatalogClient ────────────────────────────────────────────────────────────
+function stableStringify(value) {
+    if (value === null || value === undefined)
+        return JSON.stringify(value);
+    if (typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return "[" + value.map((v) => stableStringify(v)).join(",") + "]";
+    }
+    const sorted = Object.keys(value).sort();
+    const entries = sorted.map((k) => JSON.stringify(k) + ":" + stableStringify(value[k]));
+    return "{" + entries.join(",") + "}";
+}
+function canonicalSignedPayload(recipe) {
+    const subset = {};
+    for (const field of SIGNED_FIELDS) {
+        if (field in recipe) {
+            subset[field] = recipe[field];
+        }
+    }
+    return stableStringify(subset);
+}
 /**
- * CatalogClient — REST client for the AIWerk MCP Catalog API.
- *
- * NOTE: File I/O operations (readCache, writeCache, etc.) are intentionally
- * synchronous. This is acceptable for CLI tools and bridge startup, but
- * should be converted to async if used in hot paths (e.g., per-request).
+ * Verify the Ed25519 signature on a recipe against the bundled AIWerk public
+ * key. Throws CatalogSignatureError on any failure (missing signature, wrong
+ * algorithm, tampered payload, key mismatch).
+ */
+export function verifyRecipeSignature(recipe) {
+    const sig = recipe.signature;
+    if (!sig) {
+        throw new CatalogSignatureError("recipe has no signature");
+    }
+    if (sig.algorithm !== "ed25519") {
+        throw new CatalogSignatureError(`unsupported signature algorithm: ${sig.algorithm}`);
+    }
+    if (typeof sig.value !== "string" || sig.value.length === 0) {
+        throw new CatalogSignatureError("recipe signature value is empty");
+    }
+    const publicKey = createPublicKey(AIWERK_CATALOG_PUBLIC_KEY_PEM);
+    const payload = Buffer.from(canonicalSignedPayload(recipe), "utf-8");
+    const signatureBytes = Buffer.from(sig.value, "base64");
+    const ok = verify(null, payload, publicKey, signatureBytes);
+    if (!ok) {
+        throw new CatalogSignatureError("recipe signature does not match");
+    }
+}
+/**
+ * REST client for the AIWerk MCP catalog. File I/O is intentionally
+ * synchronous — fine for CLI tools and bridge startup. Signature verification
+ * runs on every fetch (including cache reads) so a tampered cache cannot
+ * silently slip through.
  */
 export class CatalogClient {
     baseUrl;
     cacheDir;
     logger;
     staleMs;
+    skipSignatureVerify;
     constructor(opts) {
-        this.baseUrl = (opts?.baseUrl ?? "https://catalog.aiwerk.ch").replace(/\/+$/, "");
+        this.baseUrl = (opts?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
         this.cacheDir = opts?.cacheDir ?? join(homedir(), ".mcp-bridge", "recipes");
         this.logger = opts?.logger ?? noop;
         this.staleMs = (opts?.staleDays ?? 7) * 24 * 60 * 60 * 1000;
+        this.skipSignatureVerify = opts?.skipSignatureVerify ?? false;
     }
     // ── Private helpers ──────────────────────────────────────────────────────
     async fetchJson(path) {
@@ -95,11 +171,23 @@ export class CatalogClient {
             return true;
         }
     }
+    verifyOrThrow(recipe, name) {
+        if (this.skipSignatureVerify)
+            return;
+        try {
+            verifyRecipeSignature(recipe);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new CatalogSignatureError(`Recipe "${name}" failed signature verification: ${reason}`);
+        }
+    }
     // ── Public API ───────────────────────────────────────────────────────────
     /** Search for recipes by keyword. */
     async search(query) {
         const encoded = encodeURIComponent(query);
-        return this.fetchJson(`/api/search?q=${encoded}`);
+        const result = await this.fetchJson(`/api/search?q=${encoded}`);
+        return Array.isArray(result) ? result : (result.results ?? []);
     }
     /** List recipes with optional filtering. */
     async list(opts) {
@@ -110,75 +198,54 @@ export class CatalogClient {
             params.set("category", opts.category);
         if (opts?.sort)
             params.set("sort", opts.sort);
-        if (opts?.hostedSafe)
-            params.set("hostedSafe", "true");
         const qs = params.toString();
         return this.fetchJson(`/api/recipes${qs ? `?${qs}` : ""}`);
     }
-    /** Download a recipe from the catalog and cache it locally. */
+    /**
+     * Download a recipe from the catalog, verify its signature, and cache it
+     * locally. Throws CatalogSignatureError if the recipe is unsigned or
+     * tampered — nothing is written to the cache in that case.
+     */
     async download(name) {
         const recipe = await this.fetchJson(`/api/recipes/${encodeURIComponent(name)}/download`);
+        this.verifyOrThrow(recipe, name);
         this.writeCache(name, recipe);
         return recipe;
     }
     /**
-     * Resolve a recipe — returns cached if available, otherwise fetches from catalog.
-     * Falls back to cache when the catalog is unreachable (offline mode).
+     * Resolve a recipe by name. Returns the cached copy if fresh; otherwise
+     * fetches from the catalog. Falls back to a stale cache if the network is
+     * unreachable. Signature is verified on both fresh and cached paths so a
+     * tampered cache cannot slip through.
      */
     async resolve(name) {
         const cached = this.readCache(name);
-        if (cached && !this.isCacheStale(name))
+        if (cached && !this.isCacheStale(name)) {
+            this.verifyOrThrow(cached, name);
             return cached;
+        }
         try {
             const recipe = await this.fetchJson(`/api/recipes/${encodeURIComponent(name)}/download`);
+            this.verifyOrThrow(recipe, name);
             this.writeCache(name, recipe);
             return recipe;
         }
         catch (err) {
+            if (err instanceof CatalogSignatureError)
+                throw err;
             if (err instanceof CatalogError && err.message.startsWith("Recipe not found:")) {
                 throw err;
             }
             if (cached) {
+                // Stale cache fallback: still verify the signature so an offline user
+                // does not run a tampered local copy.
+                this.verifyOrThrow(cached, name);
                 this.logger.warn(`Catalog unreachable for "${name}", using cached version`);
                 return cached;
             }
             throw new CatalogError(`Cannot resolve recipe "${name}": catalog unreachable and no local cache`);
         }
     }
-    /**
-     * Bootstrap by downloading the top N most popular recipes.
-     * Skips already-cached recipes unless they are stale.
-     */
-    async bootstrap(limit = 15, hostedSafe = false) {
-        const { results } = await this.list({ limit, sort: "popular", hostedSafe });
-        const names = [];
-        const toDownload = [];
-        for (const entry of results) {
-            const name = entry.name;
-            if (!this.isCacheStale(name)) {
-                names.push(name);
-                continue;
-            }
-            toDownload.push(name);
-        }
-        const BATCH_SIZE = 5;
-        for (let i = 0; i < toDownload.length; i += BATCH_SIZE) {
-            const batch = toDownload.slice(i, i + BATCH_SIZE);
-            const results = await Promise.allSettled(batch.map(async (name) => {
-                await this.download(name);
-                return name;
-            }));
-            for (const r of results) {
-                if (r.status === "fulfilled") {
-                    names.push(r.value);
-                }
-                else {
-                    this.logger.warn(`Failed to download recipe: ${r.reason}`);
-                }
-            }
-        }
-        return names;
-    }
     /** Synchronously read a recipe from local cache. Returns null if not cached. */
     getCached(name) {
         return this.readCache(name);

package/dist/src/config.d.ts

@@ -1,4 +1,4 @@
-import { BridgeConfig, Logger } from "./types.js";
+import { BridgeConfig, Logger, McpServerConfig } from "./types.js";
 /**
  * Load ~/.openclaw/.env as a fallback env source.
  *
@@ -28,3 +28,7 @@ export declare function loadConfig(options?: LoadConfigOptions): BridgeConfig;
 export declare function getConfigDir(configPath?: string): string;
 /** Initialize the config directory with template files. */
 export declare function initConfigDir(logger: Logger): void;
+import type { CatalogRecipe } from "./catalog-client.js";
+export declare function recipeToServerConfig(recipe: CatalogRecipe): McpServerConfig | null;
+/** Collect all env var names required by a recipe (auth.envVars + ${VAR} refs). */
+export declare function collectRequiredEnvVars(recipe: CatalogRecipe): string[];

package/dist/src/config.js

@@ -205,3 +205,68 @@ export function initConfigDir(logger) {
     }
     logger.info(`Config directory ready: ${dir}`);
 }
+export function recipeToServerConfig(recipe) {
+    if (Array.isArray(recipe.transports) && recipe.transports.length > 0) {
+        const t = recipe.transports[0];
+        if (t.type === "stdio") {
+            return {
+                transport: "stdio",
+                description: recipe.description,
+                command: t.command,
+                args: t.args,
+                env: t.env,
+            };
+        }
+        if (t.type === "sse" || t.type === "streamable-http") {
+            return {
+                transport: t.type,
+                description: recipe.description,
+                url: t.url,
+                headers: t.headers,
+            };
+        }
+        return null;
+    }
+    if (recipe.transport === "stdio") {
+        return {
+            transport: "stdio",
+            description: recipe.description,
+            command: recipe.command,
+            args: recipe.args,
+            env: recipe.env,
+        };
+    }
+    if (recipe.transport === "sse" || recipe.transport === "streamable-http") {
+        return {
+            transport: recipe.transport,
+            description: recipe.description,
+            url: recipe.url,
+            headers: recipe.headers,
+        };
+    }
+    return null;
+}
+/** Collect all env var names required by a recipe (auth.envVars + ${VAR} refs). */
+export function collectRequiredEnvVars(recipe) {
+    const vars = new Set();
+    if (Array.isArray(recipe.auth?.envVars)) {
+        for (const v of recipe.auth.envVars)
+            vars.add(v);
+    }
+    const envObj = Array.isArray(recipe.transports)
+        ? recipe.transports[0]?.env
+        : recipe.env;
+    if (envObj && typeof envObj === "object") {
+        for (const val of Object.values(envObj)) {
+            if (typeof val === "string") {
+                const matches = val.matchAll(/\$\{([^}]+)\}/g);
+                for (const m of matches)
+                    vars.add(m[1]);
+            }
+        }
+    }
+    if (recipe.auth?.required === true && vars.size === 0) {
+        vars.add("__AUTH_REQUIRED__");
+    }
+    return Array.from(vars);
+}

package/dist/src/validate-recipe.js

@@ -274,6 +274,68 @@ export function validateRecipe(recipe) {
             }
         }
     }
+    // ── v2 spec field acceptance (Universal Recipe Spec v2, fields added since 2.8.x) ──
+    //
+    // These are typo-guarded boolean/string checks. Recipes shipped from the
+    // hosted bridge use them; the standalone runtime mostly informs the user
+    // and does not enforce hosted-only semantics (e.g. localOnly is not a
+    // gate locally — every recipe runs on the user's machine anyway).
+    // localOnly: top-level boolean. Hosted bridge refuses these recipes;
+    // standalone accepts them and lets the user spawn locally.
+    if (recipe.localOnly !== undefined && typeof recipe.localOnly !== "boolean") {
+        errors.push(`localOnly must be boolean, got ${typeof recipe.localOnly}`);
+    }
+    // multiInstance + instanceNameHint: hosted-only semantics today. Standalone
+    // accepts the fields without enforcing multi-instance install behavior.
+    if (recipe.multiInstance !== undefined && typeof recipe.multiInstance !== "boolean") {
+        errors.push(`multiInstance must be boolean, got ${typeof recipe.multiInstance}`);
+    }
+    if (recipe.instanceNameHint !== undefined && typeof recipe.instanceNameHint !== "string") {
+        errors.push(`instanceNameHint must be string, got ${typeof recipe.instanceNameHint}`);
+    }
+    // auth.options[]: multi-auth picker. If present, must be an array of objects
+    // with an id (string), label (string), and type (string).
+    const authOptions = recipe.auth?.options;
+    if (authOptions !== undefined) {
+        if (!Array.isArray(authOptions)) {
+            errors.push("auth.options must be an array");
+        }
+        else {
+            for (let i = 0; i < authOptions.length; i++) {
+                const opt = authOptions[i];
+                if (!opt || typeof opt !== "object") {
+                    errors.push(`auth.options[${i}]: must be an object`);
+                    continue;
+                }
+                if (typeof opt.id !== "string" || opt.id.trim().length === 0) {
+                    errors.push(`auth.options[${i}]: id is required (non-empty string)`);
+                }
+                if (typeof opt.label !== "string" || opt.label.trim().length === 0) {
+                    errors.push(`auth.options[${i}]: label is required (non-empty string)`);
+                }
+                if (typeof opt.type !== "string" || opt.type.trim().length === 0) {
+                    errors.push(`auth.options[${i}]: type is required (non-empty string)`);
+                }
+                if (opt.recommended !== undefined && typeof opt.recommended !== "boolean") {
+                    errors.push(`auth.options[${i}]: recommended must be boolean if present`);
+                }
+            }
+        }
+    }
+    // oauth2.envBinding: env var name to bind the OAuth access_token at spawn time.
+    // oauth2.credentialsFileType: marks recipes that need a credentials file
+    //   written to disk (e.g. workspace-mcp). Standalone reads but does not yet
+    //   write the file; will be plumbed through OAuth2 token manager when the
+    //   feature is needed locally.
+    const oauth2 = recipe.auth?.oauth2;
+    if (oauth2 && typeof oauth2 === "object") {
+        if (oauth2.envBinding !== undefined && typeof oauth2.envBinding !== "string") {
+            errors.push(`auth.oauth2.envBinding must be string, got ${typeof oauth2.envBinding}`);
+        }
+        if (oauth2.credentialsFileType !== undefined && typeof oauth2.credentialsFileType !== "string") {
+            errors.push(`auth.oauth2.credentialsFileType must be string, got ${typeof oauth2.credentialsFileType}`);
+        }
+    }
     // ── Build result ───────────────────────────────────────────────────────────
     const valid = errors.length === 0;
     const result = { valid, errors, warnings };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwerk/mcp-bridge",
-  "version": "2.8.45",
+  "version": "2.9.0",
   "description": "Standalone MCP server that multiplexes multiple MCP servers into one interface",
   "type": "module",
   "main": "./dist/src/index.js",