@aiwerk/mcp-bridge 2.9.0 → 3.0.0

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

@@ -56,6 +56,12 @@ export interface CatalogRecipe {
         required?: boolean;
         envVars?: string[];
         credentialsUrl?: string;
+        oauth2?: {
+            envBinding?: string;
+            credentialsFileType?: "google-workspace";
+            [key: string]: unknown;
+        };
+        [key: string]: unknown;
     };
     signature?: RecipeSignature;
     localOnly?: boolean;

package/dist/src/config.js

@@ -206,6 +206,16 @@ 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") {
@@ -215,6 +225,7 @@ export function recipeToServerConfig(recipe) {
                 command: t.command,
                 args: t.args,
                 env: t.env,
+                ...cfgExtras,
             };
         }
         if (t.type === "sse" || t.type === "streamable-http") {
@@ -223,6 +234,7 @@ export function recipeToServerConfig(recipe) {
                 description: recipe.description,
                 url: t.url,
                 headers: t.headers,
+                ...cfgExtras,
             };
         }
         return null;
@@ -234,6 +246,7 @@ export function recipeToServerConfig(recipe) {
             command: recipe.command,
             args: recipe.args,
             env: recipe.env,
+            ...cfgExtras,
         };
     }
     if (recipe.transport === "sse" || recipe.transport === "streamable-http") {
@@ -242,6 +255,7 @@ export function recipeToServerConfig(recipe) {
             description: recipe.description,
             url: recipe.url,
             headers: recipe.headers,
+            ...cfgExtras,
         };
     }
     return null;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwerk/mcp-bridge",
-  "version": "2.9.0",
+  "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"