@aiwerk/mcp-bridge 3.0.0 → 3.0.2

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

@@ -64,7 +64,12 @@ export interface CatalogRecipe {
         [key: string]: unknown;
     };
     signature?: RecipeSignature;
-    localOnly?: boolean;
+    /**
+     * Local-only marker. Boolean form (true) blocks hosted install entirely;
+     * string[] form lists tool names the hosted bridge hides from tools/list
+     * (standalone ignores the array — all tools run locally).
+     */
+    localOnly?: boolean | string[];
     [key: string]: unknown;
 }
 export declare class CatalogError extends Error {

package/dist/src/oauth2-credentials-file.d.ts

@@ -41,3 +41,16 @@ export declare function writeGoogleWorkspaceCredentials(opts: GoogleWorkspaceCre
     dir: string;
     filePath: string;
 };
+/**
+ * Resolve the user's Google email by hitting the userinfo endpoint with the
+ * given access token. Used at spawn time when no cached credentials file
+ * exists yet for the server. Throws on HTTP error or missing email.
+ */
+export declare function fetchGoogleUserEmail(accessToken: string): Promise<string>;
+/**
+ * Look up a previously written credentials file for this server and return
+ * the embedded Google email (the file basename, sans .json). Returns null
+ * if no credentials file exists yet. Used to skip the userinfo fetch on
+ * subsequent spawns of the same server.
+ */
+export declare function findCachedEmailForServer(serverName: string, baseOverride?: string): string | null;

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

@@ -9,7 +9,7 @@
  * Currently supports the "google-workspace" format used by
  * taylorwilsdon/google_workspace_mcp.
  */
-import { mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { mkdirSync, writeFileSync, chmodSync, readdirSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 /** Resolve the base dir for google-workspace credentials files (per-server). */
@@ -50,3 +50,42 @@ export function writeGoogleWorkspaceCredentials(opts) {
     chmodSync(filePath, 0o600);
     return { dir, filePath };
 }
+/**
+ * Resolve the user's Google email by hitting the userinfo endpoint with the
+ * given access token. Used at spawn time when no cached credentials file
+ * exists yet for the server. Throws on HTTP error or missing email.
+ */
+export async function fetchGoogleUserEmail(accessToken) {
+    const res = await fetch("https://www.googleapis.com/oauth2/v2/userinfo", {
+        headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`google userinfo fetch failed: HTTP ${res.status}: ${text.slice(0, 200)}`);
+    }
+    const json = (await res.json());
+    if (typeof json.email !== "string" || json.email.length === 0) {
+        throw new Error("google userinfo response missing email");
+    }
+    return json.email;
+}
+/**
+ * Look up a previously written credentials file for this server and return
+ * the embedded Google email (the file basename, sans .json). Returns null
+ * if no credentials file exists yet. Used to skip the userinfo fetch on
+ * subsequent spawns of the same server.
+ */
+export function findCachedEmailForServer(serverName, baseOverride) {
+    const dir = getGoogleCredentialsServerDir(serverName, baseOverride);
+    if (!existsSync(dir))
+        return null;
+    try {
+        const files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+        if (files.length === 0)
+            return null;
+        return files[0].slice(0, -".json".length);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/oauth2-token-manager.d.ts

@@ -31,6 +31,14 @@ export declare class OAuth2TokenManager {
     getToken(config: OAuth2Config): Promise<string>;
     invalidate(tokenUrl: string, clientId: string): void;
     clear(): void;
+    /**
+     * Read the persistent stored token for a server (auth_code / device_code
+     * flows). Returns null if no token store is configured or the server has
+     * never authenticated. Used by the credentialsFileType writer to populate
+     * a credentials file with refresh_token + scopes after `getTokenForAuthCode`
+     * (or device_code) has refreshed and persisted the token.
+     */
+    getStoredToken(serverName: string): import("./token-store.js").StoredToken | null;
     /**
      * Get a token for an authorization_code flow server.
      * Checks TokenStore, refreshes if expired, throws if unavailable.

package/dist/src/oauth2-token-manager.js

@@ -41,6 +41,16 @@ export class OAuth2TokenManager {
         this.tokenCache.clear();
         this.inflight.clear();
     }
+    /**
+     * Read the persistent stored token for a server (auth_code / device_code
+     * flows). Returns null if no token store is configured or the server has
+     * never authenticated. Used by the credentialsFileType writer to populate
+     * a credentials file with refresh_token + scopes after `getTokenForAuthCode`
+     * (or device_code) has refreshed and persisted the token.
+     */
+    getStoredToken(serverName) {
+        return this.tokenStore?.load(serverName) ?? null;
+    }
     /**
      * Get a token for an authorization_code flow server.
      * Checks TokenStore, refreshes if expired, throws if unavailable.

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

@@ -100,6 +100,23 @@ export declare function resolveAuthHeadersAsync(config: McpServerConfig, tokenMa
  * 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 OAuth2 credentials into a vendor-specific credentials file and
+ * return the env var binding (e.g. GOOGLE_MCP_CREDENTIALS_DIR for the
+ * google-workspace format consumed by workspace-mcp). The bridge writes
+ * <base>/<server>/<email>.json with the access_token + refresh_token + scopes
+ * and points the spawned process at the directory.
+ *
+ * Only auth_code and device_code grants are supported (workspace-mcp's
+ * primary use case); client_credentials lacks the persistent refresh_token
+ * the file format requires.
+ *
+ * Returns an empty record if config.oauth2CredentialsFile is not set.
+ * Throws on missing token store, missing stored token, or userinfo fetch
+ * failure (the spawn surfaces a clear error rather than booting a server
+ * that cannot read credentials).
+ */
+export declare function resolveOauth2CredentialsFileAsync(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

@@ -293,6 +293,75 @@ export async function resolveOauth2EnvAsync(config, tokenManager, extraEnv, envF
         return {};
     return { [config.oauth2EnvBinding]: token };
 }
+/**
+ * Resolve OAuth2 credentials into a vendor-specific credentials file and
+ * return the env var binding (e.g. GOOGLE_MCP_CREDENTIALS_DIR for the
+ * google-workspace format consumed by workspace-mcp). The bridge writes
+ * <base>/<server>/<email>.json with the access_token + refresh_token + scopes
+ * and points the spawned process at the directory.
+ *
+ * Only auth_code and device_code grants are supported (workspace-mcp's
+ * primary use case); client_credentials lacks the persistent refresh_token
+ * the file format requires.
+ *
+ * Returns an empty record if config.oauth2CredentialsFile is not set.
+ * Throws on missing token store, missing stored token, or userinfo fetch
+ * failure (the spawn surfaces a clear error rather than booting a server
+ * that cannot read credentials).
+ */
+export async function resolveOauth2CredentialsFileAsync(config, tokenManager, extraEnv, envFallback, serverName) {
+    const cf = config.oauth2CredentialsFile;
+    if (!cf)
+        return {};
+    if (cf.format !== "google-workspace") {
+        throw new Error(`[mcp-bridge] Unsupported oauth2CredentialsFile.format: ${cf.format}`);
+    }
+    if (!serverName) {
+        throw new Error("[mcp-bridge] serverName is required for oauth2CredentialsFile resolution");
+    }
+    if (!config.auth || config.auth.type !== "oauth2") {
+        throw new Error(`[mcp-bridge] oauth2CredentialsFile requires auth.type === "oauth2" for server ${serverName}`);
+    }
+    // Refresh + resolve clientId/clientSecret. Force the right grant flow
+    // through the token manager so the StoredToken is populated/up-to-date.
+    let resolvedClientId = "";
+    let resolvedClientSecret = "";
+    if (isAuthCodeOAuth2(config.auth)) {
+        const ac = resolveAuthCodeOAuth2Config(config, extraEnv, envFallback);
+        resolvedClientId = ac.clientId ?? "";
+        resolvedClientSecret = ac.clientSecret ?? "";
+        await tokenManager.getTokenForAuthCode(serverName, ac);
+    }
+    else if (isDeviceCodeOAuth2(config.auth)) {
+        const dc = resolveDeviceCodeOAuth2Config(config, extraEnv, envFallback);
+        resolvedClientId = dc.clientId;
+        resolvedClientSecret = dc.clientSecret ?? "";
+        await tokenManager.getTokenForDeviceCode(serverName, dc);
+    }
+    else {
+        throw new Error(`[mcp-bridge] oauth2CredentialsFile requires auth_code or device_code grant for server ${serverName}; client_credentials lacks a persistent refresh_token`);
+    }
+    const stored = tokenManager.getStoredToken(serverName);
+    if (!stored) {
+        throw new Error(`[mcp-bridge] No stored OAuth2 token for server "${serverName}". Run: mcp-bridge auth login ${serverName}`);
+    }
+    // Lazy import keeps the helper module out of the cold-start path for
+    // servers that do not use the credentials-file feature.
+    const credMod = await import("./oauth2-credentials-file.js");
+    let email = credMod.findCachedEmailForServer(serverName);
+    if (!email) {
+        email = await credMod.fetchGoogleUserEmail(stored.accessToken);
+    }
+    const { dir } = credMod.writeGoogleWorkspaceCredentials({
+        serverName,
+        stored,
+        email,
+        clientId: resolvedClientId,
+        clientSecret: resolvedClientSecret,
+    });
+    const envVar = cf.envVar ?? "GOOGLE_MCP_CREDENTIALS_DIR";
+    return { [envVar]: dir };
+}
 /**
  * Resolve server headers and merge auth headers (auth takes precedence).
  */

package/dist/src/transport-stdio.js

@@ -1,5 +1,5 @@
 import { spawn } from "child_process";
-import { BaseTransport, resolveEnvRecord, resolveArgs, resolveOauth2EnvAsync } from "./transport-base.js";
+import { BaseTransport, resolveEnvRecord, resolveArgs, resolveOauth2EnvAsync, resolveOauth2CredentialsFileAsync } from "./transport-base.js";
 export class StdioTransport extends BaseTransport {
     process = null;
     framingMode = "auto";
@@ -42,7 +42,17 @@ export class StdioTransport extends BaseTransport {
                 throw error;
             }
         }
-        const env = { ...process.env, ...configEnv, ...oauthEnv };
+        let credFileEnv = {};
+        if (this.config.oauth2CredentialsFile && this.tokenManager) {
+            try {
+                credFileEnv = await resolveOauth2CredentialsFileAsync(this.config, this.tokenManager, undefined, undefined, this.serverName);
+            }
+            catch (error) {
+                this.logger.error(`[mcp-bridge] Failed to resolve OAuth2 credentials file for stdio server ${this.serverName ?? "<unnamed>"}:`, error);
+                throw error;
+            }
+        }
+        const env = { ...process.env, ...configEnv, ...oauthEnv, ...credFileEnv };
         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/validate-recipe.js

@@ -280,10 +280,30 @@ export function validateRecipe(recipe) {
     // 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}`);
+    // localOnly: two accepted forms.
+    //   - boolean true  → hosted bridge refuses install entirely (chrome-devtools);
+    //                     standalone accepts and spawns locally
+    //   - string[]      → per-tool hosted-bridge filter (the listed names are
+    //                     stripped from tools/list on hosted); standalone IGNORES
+    //                     the array — every tool runs locally regardless.
+    // Standalone runtime accepts both forms; we only validate the shape here so
+    // a typo (`"yes"`, number, object) is caught at recipe-load time.
+    if (recipe.localOnly !== undefined) {
+        const lo = recipe.localOnly;
+        if (typeof lo === "boolean") {
+            // OK
+        }
+        else if (Array.isArray(lo)) {
+            if (lo.length === 0) {
+                errors.push("localOnly array must be non-empty (use false or omit instead)");
+            }
+            else if (lo.some((t) => typeof t !== "string" || t.trim().length === 0)) {
+                errors.push("localOnly array must contain only non-empty tool-name strings");
+            }
+        }
+        else {
+            errors.push(`localOnly must be boolean or string[], got ${typeof lo}`);
+        }
     }
     // multiInstance + instanceNameHint: hosted-only semantics today. Standalone
     // accepts the fields without enforcing multi-instance install behavior.

package/package.json

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