@aiwerk/mcp-bridge 2.8.45 → 3.0.0

package/dist/src/config.js

@@ -205,3 +205,82 @@ export function initConfigDir(logger) {
     }
     logger.info(`Config directory ready: ${dir}`);
 }
+export function recipeToServerConfig(recipe) {
+    // Extract optional v2 spec fields. The validator (validate-recipe.ts) accepts
+    // these on every recipe; this is the runtime plumb-through.
+    const oauth2 = recipe.auth?.oauth2;
+    const envBinding = oauth2?.envBinding;
+    const credFileType = oauth2?.credentialsFileType;
+    const cfgExtras = {};
+    if (typeof envBinding === "string" && envBinding)
+        cfgExtras.oauth2EnvBinding = envBinding;
+    if (credFileType === "google-workspace")
+        cfgExtras.oauth2CredentialsFile = { format: "google-workspace" };
+    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,
+                ...cfgExtras,
+            };
+        }
+        if (t.type === "sse" || t.type === "streamable-http") {
+            return {
+                transport: t.type,
+                description: recipe.description,
+                url: t.url,
+                headers: t.headers,
+                ...cfgExtras,
+            };
+        }
+        return null;
+    }
+    if (recipe.transport === "stdio") {
+        return {
+            transport: "stdio",
+            description: recipe.description,
+            command: recipe.command,
+            args: recipe.args,
+            env: recipe.env,
+            ...cfgExtras,
+        };
+    }
+    if (recipe.transport === "sse" || recipe.transport === "streamable-http") {
+        return {
+            transport: recipe.transport,
+            description: recipe.description,
+            url: recipe.url,
+            headers: recipe.headers,
+            ...cfgExtras,
+        };
+    }
+    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/oauth2-credentials-file.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Vendor-specific OAuth2 credentials file emitters.
+ *
+ * Some upstream MCP servers (e.g. workspace-mcp) read OAuth credentials from
+ * a JSON file rather than an Authorization header or env var. The standalone
+ * bridge writes that file at spawn time so the server can refresh its own
+ * tokens via the upstream library.
+ *
+ * Currently supports the "google-workspace" format used by
+ * taylorwilsdon/google_workspace_mcp.
+ */
+import type { StoredToken } from "./token-store.js";
+export interface GoogleWorkspaceCredentialOpts {
+    serverName: string;
+    /** Result of OAuth2TokenManager.getStoredToken(serverName). */
+    stored: StoredToken;
+    /**
+     * The Google account email. Required so workspace-mcp finds the file at
+     * <dir>/<email>.json. Pre-fetched by the caller (we don't bundle a userinfo
+     * fetch here to keep the standalone bridge offline-friendly).
+     */
+    email: string;
+    /** OAuth2 client_id used during the install OAuth flow. */
+    clientId: string;
+    /** OAuth2 client_secret used during the install OAuth flow. */
+    clientSecret: string;
+    /** Override the base directory (testing). Defaults to ~/.mcp-bridge/google-credentials. */
+    baseDirOverride?: string;
+}
+/** Resolve the base dir for google-workspace credentials files (per-server). */
+export declare function getGoogleCredentialsBaseDir(): string;
+/** Per-server dir where workspace-mcp finds <email>.json. */
+export declare function getGoogleCredentialsServerDir(serverName: string, baseOverride?: string): string;
+/**
+ * Write the google-workspace credentials file in the shape expected by
+ * workspace-mcp's LocalDirectoryCredentialStore (Google Auth Library JSON
+ * with tz-naive ISO expiry). Returns the absolute file path so the caller
+ * can log/audit. Permissions: dir 0700, file 0600.
+ */
+export declare function writeGoogleWorkspaceCredentials(opts: GoogleWorkspaceCredentialOpts): {
+    dir: string;
+    filePath: string;
+};

package/dist/src/oauth2-credentials-file.js

@@ -0,0 +1,52 @@
+/**
+ * Vendor-specific OAuth2 credentials file emitters.
+ *
+ * Some upstream MCP servers (e.g. workspace-mcp) read OAuth credentials from
+ * a JSON file rather than an Authorization header or env var. The standalone
+ * bridge writes that file at spawn time so the server can refresh its own
+ * tokens via the upstream library.
+ *
+ * Currently supports the "google-workspace" format used by
+ * taylorwilsdon/google_workspace_mcp.
+ */
+import { mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Resolve the base dir for google-workspace credentials files (per-server). */
+export function getGoogleCredentialsBaseDir() {
+    if (process.env.MCP_BRIDGE_GOOGLE_CREDENTIALS_DIR) {
+        return process.env.MCP_BRIDGE_GOOGLE_CREDENTIALS_DIR;
+    }
+    return join(homedir(), ".mcp-bridge", "google-credentials");
+}
+/** Per-server dir where workspace-mcp finds <email>.json. */
+export function getGoogleCredentialsServerDir(serverName, baseOverride) {
+    const base = baseOverride ?? getGoogleCredentialsBaseDir();
+    return join(base, serverName);
+}
+/**
+ * Write the google-workspace credentials file in the shape expected by
+ * workspace-mcp's LocalDirectoryCredentialStore (Google Auth Library JSON
+ * with tz-naive ISO expiry). Returns the absolute file path so the caller
+ * can log/audit. Permissions: dir 0700, file 0600.
+ */
+export function writeGoogleWorkspaceCredentials(opts) {
+    const dir = getGoogleCredentialsServerDir(opts.serverName, opts.baseDirOverride);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // workspace-mcp / google-auth-library expects expiry as a tz-naive
+    // ISO datetime (Python datetime.fromisoformat). Strip the trailing Z.
+    const expiry = new Date(opts.stored.expiresAt).toISOString().replace(/Z$/, "");
+    const credential = {
+        token: opts.stored.accessToken,
+        refresh_token: opts.stored.refreshToken ?? "",
+        token_uri: "https://oauth2.googleapis.com/token",
+        client_id: opts.clientId,
+        client_secret: opts.clientSecret,
+        scopes: opts.stored.scopes ?? [],
+        expiry,
+    };
+    const filePath = join(dir, `${opts.email}.json`);
+    writeFileSync(filePath, JSON.stringify(credential, null, 2), { mode: 0o600 });
+    chmodSync(filePath, 0o600);
+    return { dir, filePath };
+}

package/dist/src/standalone-server.js

@@ -738,7 +738,7 @@ export class StandaloneServer {
             case "sse":
                 return new SseTransport(serverConfig, this.config, this.logger, onReconnected, this.tokenManager, () => this.nextRequestId(), serverName);
             case "stdio":
-                return new StdioTransport(serverConfig, this.config, this.logger, onReconnected, () => this.nextRequestId());
+                return new StdioTransport(serverConfig, this.config, this.logger, onReconnected, () => this.nextRequestId(), this.tokenManager, serverName);
             case "streamable-http":
                 return new StreamableHttpTransport(serverConfig, this.config, this.logger, onReconnected, this.tokenManager, () => this.nextRequestId(), serverName);
             default:

package/dist/src/transport-base.d.ts

@@ -92,6 +92,14 @@ export declare function resolveOAuth2Config(config: McpServerConfig, extraEnv?:
 export declare function resolveAuthCodeOAuth2Config(config: McpServerConfig, extraEnv?: Record<string, string | undefined>, envFallback?: () => Record<string, string>): AuthCodeOAuth2Config;
 export declare function resolveDeviceCodeOAuth2Config(config: McpServerConfig, extraEnv?: Record<string, string | undefined>, envFallback?: () => Record<string, string>): DeviceCodeOAuth2Config;
 export declare function resolveAuthHeadersAsync(config: McpServerConfig, tokenManager: OAuth2TokenManager, extraEnv?: Record<string, string | undefined>, envFallback?: () => Record<string, string>, serverName?: string): Promise<Record<string, string>>;
+/**
+ * Resolve OAuth2 access token into a stdio env-var binding (for servers that
+ * read credentials from a specific env var, e.g. GITHUB_PERSONAL_ACCESS_TOKEN).
+ * Returns an empty record if no envBinding is configured or auth is not OAuth2.
+ * Sourced from McpServerConfig.oauth2EnvBinding (set by recipeToServerConfig
+ * from recipe.auth.oauth2.envBinding).
+ */
+export declare function resolveOauth2EnvAsync(config: McpServerConfig, tokenManager: OAuth2TokenManager, extraEnv?: Record<string, string | undefined>, envFallback?: () => Record<string, string>, serverName?: string): Promise<Record<string, string>>;
 /**
  * Resolve server headers and merge auth headers (auth takes precedence).
  */

package/dist/src/transport-base.js

@@ -241,32 +241,58 @@ export function resolveDeviceCodeOAuth2Config(config, extraEnv, envFallback) {
         ...(scopes && scopes.length > 0 ? { scopes } : {}),
     };
 }
+/**
+ * Resolve an OAuth2 access token by picking the correct flow (auth code, device
+ * code, or client credentials). Returns null if config.auth is not OAuth2.
+ * Shared between resolveAuthHeadersAsync (HTTP transports) and
+ * resolveOauth2EnvAsync (stdio transports with envBinding).
+ */
+async function resolveOauth2AccessToken(config, tokenManager, extraEnv, envFallback, serverName) {
+    if (!config.auth || config.auth.type !== "oauth2")
+        return null;
+    if (isAuthCodeOAuth2(config.auth)) {
+        if (!serverName) {
+            throw new Error("[mcp-bridge] serverName is required for authorization_code OAuth2 flow");
+        }
+        const authCodeConfig = resolveAuthCodeOAuth2Config(config, extraEnv, envFallback);
+        return tokenManager.getTokenForAuthCode(serverName, authCodeConfig);
+    }
+    if (isDeviceCodeOAuth2(config.auth)) {
+        if (!serverName) {
+            throw new Error("[mcp-bridge] serverName is required for device_code OAuth2 flow");
+        }
+        const deviceCodeConfig = resolveDeviceCodeOAuth2Config(config, extraEnv, envFallback);
+        return tokenManager.getTokenForDeviceCode(serverName, deviceCodeConfig);
+    }
+    const oauth2Config = resolveOAuth2Config(config, extraEnv, envFallback);
+    return tokenManager.getToken(oauth2Config);
+}
 export async function resolveAuthHeadersAsync(config, tokenManager, extraEnv, envFallback, serverName) {
     if (!config.auth)
         return {};
     if (config.auth.type === "oauth2") {
-        if (isAuthCodeOAuth2(config.auth)) {
-            if (!serverName) {
-                throw new Error("[mcp-bridge] serverName is required for authorization_code OAuth2 flow");
-            }
-            const authCodeConfig = resolveAuthCodeOAuth2Config(config, extraEnv, envFallback);
-            const token = await tokenManager.getTokenForAuthCode(serverName, authCodeConfig);
+        const token = await resolveOauth2AccessToken(config, tokenManager, extraEnv, envFallback, serverName);
+        if (token)
             return { Authorization: `Bearer ${token}` };
-        }
-        if (isDeviceCodeOAuth2(config.auth)) {
-            if (!serverName) {
-                throw new Error("[mcp-bridge] serverName is required for device_code OAuth2 flow");
-            }
-            const deviceCodeConfig = resolveDeviceCodeOAuth2Config(config, extraEnv, envFallback);
-            const token = await tokenManager.getTokenForDeviceCode(serverName, deviceCodeConfig);
-            return { Authorization: `Bearer ${token}` };
-        }
-        const oauth2Config = resolveOAuth2Config(config, extraEnv, envFallback);
-        const token = await tokenManager.getToken(oauth2Config);
-        return { Authorization: `Bearer ${token}` };
+        return {};
     }
     return resolveAuthHeaders(config, extraEnv, envFallback);
 }
+/**
+ * Resolve OAuth2 access token into a stdio env-var binding (for servers that
+ * read credentials from a specific env var, e.g. GITHUB_PERSONAL_ACCESS_TOKEN).
+ * Returns an empty record if no envBinding is configured or auth is not OAuth2.
+ * Sourced from McpServerConfig.oauth2EnvBinding (set by recipeToServerConfig
+ * from recipe.auth.oauth2.envBinding).
+ */
+export async function resolveOauth2EnvAsync(config, tokenManager, extraEnv, envFallback, serverName) {
+    if (!config.oauth2EnvBinding)
+        return {};
+    const token = await resolveOauth2AccessToken(config, tokenManager, extraEnv, envFallback, serverName);
+    if (!token)
+        return {};
+    return { [config.oauth2EnvBinding]: token };
+}
 /**
  * Resolve server headers and merge auth headers (auth takes precedence).
  */

package/dist/src/transport-stdio.d.ts

@@ -1,10 +1,14 @@
-import { McpRequest, McpResponse } from "./types.js";
+import { McpRequest, McpResponse, McpServerConfig, McpClientConfig, Logger, RequestIdGenerator } from "./types.js";
 import { BaseTransport } from "./transport-base.js";
+import type { OAuth2TokenManager } from "./oauth2-token-manager.js";
 export declare class StdioTransport extends BaseTransport {
     private process;
     private framingMode;
     private stdoutBuffer;
     private isShuttingDown;
+    private readonly tokenManager?;
+    private readonly serverName?;
+    constructor(config: McpServerConfig, clientConfig: McpClientConfig, logger: Logger, onReconnected?: () => Promise<void>, requestIdGenerator?: RequestIdGenerator, tokenManager?: OAuth2TokenManager, serverName?: string);
     protected get transportName(): string;
     connect(): Promise<void>;
     private startProcess;

package/dist/src/transport-stdio.js

@@ -1,10 +1,17 @@
 import { spawn } from "child_process";
-import { BaseTransport, resolveEnvRecord, resolveArgs } from "./transport-base.js";
+import { BaseTransport, resolveEnvRecord, resolveArgs, resolveOauth2EnvAsync } from "./transport-base.js";
 export class StdioTransport extends BaseTransport {
     process = null;
     framingMode = "auto";
     stdoutBuffer = Buffer.alloc(0);
     isShuttingDown = false;
+    tokenManager;
+    serverName;
+    constructor(config, clientConfig, logger, onReconnected, requestIdGenerator, tokenManager, serverName) {
+        super(config, clientConfig, logger, onReconnected, requestIdGenerator);
+        this.tokenManager = tokenManager;
+        this.serverName = serverName;
+    }
     get transportName() { return "stdio"; }
     async connect() {
         if (!this.config.command) {
@@ -25,7 +32,17 @@ export class StdioTransport extends BaseTransport {
         if (!this.config.command)
             return;
         const configEnv = resolveEnvRecord(this.config.env || {}, "env key");
-        const env = { ...process.env, ...configEnv };
+        let oauthEnv = {};
+        if (this.config.oauth2EnvBinding && this.tokenManager) {
+            try {
+                oauthEnv = await resolveOauth2EnvAsync(this.config, this.tokenManager, undefined, undefined, this.serverName);
+            }
+            catch (error) {
+                this.logger.error(`[mcp-bridge] Failed to resolve OAuth2 envBinding for stdio server ${this.serverName ?? "<unnamed>"}:`, error);
+                throw error;
+            }
+        }
+        const env = { ...process.env, ...configEnv, ...oauthEnv };
         const args = resolveArgs(this.config.args || [], env);
         if (process.env.DEBUG_STDIO_ENV) {
             this.logger.info(`[mcp-bridge] stdio spawn: ${this.config.command} ${args.join(" ")}`);

package/dist/src/types.d.ts

@@ -48,6 +48,24 @@ export interface McpServerConfig {
     url?: string;
     headers?: Record<string, string>;
     auth?: HttpAuthConfig;
+    /**
+     * If set, the OAuth2 access token is injected into the spawned process
+     * (or HTTP request env) under this name instead of (or in addition to) the
+     * default Authorization header. Used by stdio servers that read their
+     * credentials from a specific env var (e.g. GITHUB_PERSONAL_ACCESS_TOKEN).
+     * Sourced from recipe.auth.oauth2.envBinding.
+     */
+    oauth2EnvBinding?: string;
+    /**
+     * If set, the OAuth2 token + refresh token are written to a credentials
+     * file in a vendor-specific format, and the file path is injected into
+     * the spawned process via env var. Sourced from recipe.auth.oauth2.credentialsFileType.
+     * Format dictates the file shape (e.g. "google-workspace" follows Google's tz-naive expiry).
+     */
+    oauth2CredentialsFile?: {
+        format: "google-workspace";
+        envVar?: string;
+    };
     command?: string;
     args?: string[];
     env?: Record<string, string>;

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": "3.0.0",
   "description": "Standalone MCP server that multiplexes multiple MCP servers into one interface",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -45,7 +45,7 @@
     "test": "node --import tsx --test tests/*.test.ts",
     "typecheck": "tsc --noEmit",
     "postinstall": "node scripts/postinstall.cjs",
-    "prepublishOnly": "tsc && bash scripts/validate-recipes.sh && node -e \"const v=require('./package.json').version;const fs=require('fs');const cl=fs.readFileSync('CHANGELOG.md','utf8');if(!cl.includes('['+v+']')){console.error('ERROR: CHANGELOG.md missing entry for v'+v);process.exit(1)}\"",
+    "prepublishOnly": "bash $HOME/agent-memory/commons/scripts/prepublish-safety.sh && tsc && bash scripts/validate-recipes.sh && node -e \"const v=require('./package.json').version;const fs=require('fs');const cl=fs.readFileSync('CHANGELOG.md','utf8');if(!cl.includes('['+v+']')){console.error('ERROR: CHANGELOG.md missing entry for v'+v);process.exit(1)}\"",
     "validate-recipe": "npx tsx bin/validate-recipe.ts",
     "lint": "eslint src/",
     "format": "prettier --write src/",

package/scripts/validate-recipes.sh

@@ -4,6 +4,10 @@
 # Exit code 1 if any URL is broken.
 
 set -uo pipefail
+# nullglob: an unmatched glob expands to nothing, not the literal pattern.
+# Without this, an empty `servers/` (as of v3.0.0) would make the loop
+# try to read `servers/*/recipe.json` literally and fail.
+shopt -s nullglob
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 SERVERS_DIR="$SCRIPT_DIR/../servers"