@mongodb-js/agent-engine-runner-shared 0.11.3

package/dist/mcp_oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp_oauth.d.ts","sourceRoot":"","sources":["../src/mcp_oauth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAOpF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE,eAAO,MAAM,6BAA6B,sCACL,CAAC;AACtC,eAAO,MAAM,8BAA8B,mCAAmC,CAAC;AAC/E;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC;AAgND;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,CAER;AAqGD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,sBAAsB,EAC9B,QAAQ,CAAC,EAAE,MAAM,GAChB,mBAAmB,CAIrB;AAkHD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,sBAAsB,EAC9B,QAAQ,CAAC,EAAE,MAAM,GAChB,mBAAmB,CAmBrB"}

package/dist/mcp_oauth.js

@@ -0,0 +1,389 @@
+/**
+ * OAuth provider and file-backed token storage for remote MCP servers.
+ *
+ * Port of `agent_engine_runner_shared/mcp_oauth.py`, adapted to `@modelcontextprotocol/sdk`'s
+ * `OAuthClientProvider` interface — a lower-level, method-based contract
+ * (`tokens()`/`saveTokens()`/`clientInformation()`/...) rather than Python's
+ * httpx-`Auth`-flow-based `OAuthClientProvider`. The cache file format/path
+ * is kept byte-identical to the Python side so `agentengine dev mcp auth
+ * login/status/upload` (Go CLI) and this runtime read/write the same file
+ * regardless of which SDK the agent uses.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { lock } from "proper-lockfile";
+import { ClientCredentialsProvider } from "@modelcontextprotocol/sdk/client/auth-extensions.js";
+export const DEFAULT_MCP_OAUTH_CLIENT_NAME = "Atlas Agent Engine Dev MCP Client";
+export const DEFAULT_MCP_OAUTH_REDIRECT_URI = "http://127.0.0.1:8765/callback";
+/**
+ * Cache directory, resolved at call time — not a module-level constant.
+ *
+ * `materializeMcpOauthSecretCache()` (in `mcp_oauth_secret.ts`) sets
+ * `AGENTIC_MCP_OAUTH_DIR` at startup. A frozen import-time const would capture
+ * the value from before that runs whenever this module is imported first (e.g.
+ * via the package barrel), so the reader and writer could resolve to different
+ * directories. Reading the env on each call keeps them in lockstep regardless
+ * of import order.
+ */
+export function mcpOauthCacheDir() {
+    return (process.env["AGENTIC_MCP_OAUTH_DIR"] ??
+        path.join(os.homedir(), ".agentic", "mcp-oauth"));
+}
+const CACHE_SCHEMA_VERSION = 1;
+function secondsUntilExpiry(rawExpiry) {
+    if (typeof rawExpiry !== "string" || rawExpiry === "")
+        return undefined;
+    const expiry = new Date(rawExpiry);
+    if (Number.isNaN(expiry.getTime()))
+        return undefined;
+    return Math.max(0, Math.floor((expiry.getTime() - Date.now()) / 1000));
+}
+/** Token storage backed by the shared `agentengine dev` cache file. */
+class FileOAuthTokenStorage {
+    serverName;
+    serverUrl;
+    cacheDir;
+    clientId;
+    configuredScope;
+    constructor(serverName, serverUrl, cacheDir = mcpOauthCacheDir(), clientId, configuredScope) {
+        this.serverName = serverName;
+        this.serverUrl = serverUrl;
+        this.cacheDir = cacheDir;
+        this.clientId = clientId;
+        this.configuredScope = configuredScope;
+    }
+    get path() {
+        return path.join(this.cacheDir, `${mcpOauthCacheName(this.serverName, this.serverUrl)}.json`);
+    }
+    readPayload() {
+        try {
+            const raw = fs.readFileSync(this.path, "utf-8");
+            const parsed = JSON.parse(raw);
+            return parsed !== null && typeof parsed === "object"
+                ? parsed
+                : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    payloadMatches(payload) {
+        if (payload.server_url !== this.serverUrl)
+            return false;
+        if (this.clientId !== undefined) {
+            return (payload.client_id === this.clientId &&
+                payload.configured_scope === (this.configuredScope ?? null));
+        }
+        return true;
+    }
+    /**
+     * Read-modify-write under an advisory file lock.
+     *
+     * The final write is atomic (tmp file + rename), but without a lock around
+     * the read-modify-write as a whole, two processes racing a token refresh
+     * for the same server (e.g. two concurrent Tool Pod invocations) can
+     * clobber each other's update: the second writer's `readPayload()` can run
+     * before the first writer's rename lands, silently discarding it.
+     */
+    async writePayload(values) {
+        fs.mkdirSync(this.cacheDir, { recursive: true, mode: 0o700 });
+        let release;
+        try {
+            // `realpath: false` — the cache file may not exist yet on first write,
+            // and resolving symlinks isn't needed for a same-process-family lock.
+            // Retries require the async API (`lockSync` rejects a `retries` option).
+            release = await lock(this.path, {
+                realpath: false,
+                stale: 5000,
+                retries: { retries: 10, minTimeout: 20, maxTimeout: 200 },
+            });
+        }
+        catch (err) {
+            throw new Error(`failed to acquire MCP OAuth cache lock for ${JSON.stringify(this.path)}: ` +
+                `${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        }
+        try {
+            const payload = this.readPayload();
+            Object.assign(payload, {
+                schema_version: CACHE_SCHEMA_VERSION,
+                server_name: this.serverName,
+                server_url: this.serverUrl,
+                updated_at: new Date().toISOString(),
+            });
+            if (this.clientId !== undefined) {
+                payload.client_id = this.clientId;
+                payload.configured_scope = this.configuredScope ?? null;
+            }
+            Object.assign(payload, values);
+            const tmpName = path.join(this.cacheDir, `.tmp-${mcpOauthCacheName(this.serverName, this.serverUrl)}-${process.pid}-${Date.now()}`);
+            fs.writeFileSync(tmpName, `${JSON.stringify(payload, null, 2)}\n`, {
+                encoding: "utf-8",
+                mode: 0o600,
+            });
+            fs.renameSync(tmpName, this.path);
+        }
+        finally {
+            await release();
+        }
+    }
+    getTokens() {
+        const payload = this.readPayload();
+        if (!this.payloadMatches(payload))
+            return undefined;
+        const tokenData = payload.tokens;
+        if (!tokenData ||
+            typeof tokenData !== "object" ||
+            !tokenData["access_token"]) {
+            return undefined;
+        }
+        let expiresIn = secondsUntilExpiry(tokenData["expiry"]);
+        if (expiresIn === undefined &&
+            typeof tokenData["expires_in"] === "number") {
+            expiresIn = tokenData["expires_in"];
+        }
+        return {
+            access_token: String(tokenData["access_token"]),
+            token_type: tokenData["token_type"] || "Bearer",
+            refresh_token: tokenData["refresh_token"],
+            expires_in: expiresIn,
+            scope: tokenData["scope"],
+        };
+    }
+    async saveTokens(tokens) {
+        const tokenData = { ...tokens };
+        if (typeof tokenData["expires_in"] === "number") {
+            const expiry = new Date(Date.now() + tokenData["expires_in"] * 1000);
+            tokenData["expiry"] = expiry.toISOString();
+            delete tokenData["expires_in"];
+        }
+        await this.writePayload({ tokens: tokenData });
+    }
+    getClientInfo() {
+        const payload = this.readPayload();
+        if (!this.payloadMatches(payload))
+            return undefined;
+        const clientData = payload.client;
+        if (!clientData ||
+            typeof clientData !== "object" ||
+            !clientData["client_id"]) {
+            return undefined;
+        }
+        return {
+            redirect_uris: clientData["redirect_uris"] ?? [
+                DEFAULT_MCP_OAUTH_REDIRECT_URI,
+            ],
+            token_endpoint_auth_method: clientData["token_endpoint_auth_method"],
+            grant_types: clientData["grant_types"] ?? [
+                "authorization_code",
+                "refresh_token",
+            ],
+            response_types: clientData["response_types"] ?? ["code"],
+            scope: clientData["scope"],
+            client_name: clientData["client_name"],
+            client_id: clientData["client_id"],
+            client_secret: clientData["client_secret"],
+            client_id_issued_at: clientData["client_id_issued_at"],
+            client_secret_expires_at: clientData["client_secret_expires_at"],
+        };
+    }
+    async saveClientInfo(clientInfo) {
+        await this.writePayload({
+            client: clientInfo,
+        });
+    }
+}
+const READABLE_NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const UNSAFE_NAME_CHAR_RE = /[^A-Za-z0-9_-]+/g;
+const LEADING_TRAILING_DASH_UNDERSCORE_RE = /^[-_]+|[-_]+$/g;
+/**
+ * Return a collision-free cache basename scoped to alias and endpoint.
+ * agent.yaml imposes no charset on aliases, so uniqueness comes from hashing
+ * the raw alias whenever the readable form would lose information, and from
+ * the endpoint hash that stops the same alias sharing credentials across
+ * different MCP servers.
+ */
+export function mcpOauthCacheName(serverName, serverUrl) {
+    return `${cacheBase(serverName)}-${sha256Hex(serverUrl)}`;
+}
+function cacheBase(name) {
+    if (READABLE_NAME_RE.test(name))
+        return name;
+    let safe = name
+        .trim()
+        .replace(UNSAFE_NAME_CHAR_RE, "-")
+        .replace(LEADING_TRAILING_DASH_UNDERSCORE_RE, "");
+    if (safe.length > 40) {
+        safe = safe.slice(0, 40).replace(LEADING_TRAILING_DASH_UNDERSCORE_RE, "");
+    }
+    const rawHash = sha256Hex(name).slice(0, 16);
+    return safe === "" ? rawHash : `${safe}-${rawHash}`;
+}
+function sha256Hex(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+const INTERACTIVE_LOGIN_REQUIRED_MESSAGE = (serverName) => `mcp server '${serverName}' requires cached OAuth credentials; run 'agentengine dev mcp auth login ${serverName}'`;
+/**
+ * Non-interactive OAuth provider for the interactive `oauth` auth mode.
+ *
+ * Reads/refreshes tokens the CLI's `agentengine dev mcp auth login` already
+ * cached to `mcpOauthCacheDir()`. Never initiates a fresh authorization
+ * flow itself — the runtime process has no browser/loopback listener, so any
+ * attempt to do so raises telling the user to run the CLI login command.
+ */
+class FileBackedOAuthProvider {
+    serverName;
+    storage;
+    _clientMetadata;
+    constructor(serverName, config, redirectUri, cacheDir) {
+        this.serverName = serverName;
+        this.storage = new FileOAuthTokenStorage(serverName, config.url, cacheDir, undefined, config.auth.scope ?? undefined);
+        this._clientMetadata = {
+            redirect_uris: [redirectUri],
+            client_name: config.auth.client_name ?? DEFAULT_MCP_OAUTH_CLIENT_NAME,
+            scope: config.auth.scope,
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            // A loopback client cannot keep a client secret. Omitting this lets
+            // servers apply RFC 7591's client_secret_basic default and mint a
+            // secret the token exchange then has no way to send.
+            token_endpoint_auth_method: "none",
+        };
+    }
+    get redirectUrl() {
+        const [redirectUri] = this._clientMetadata.redirect_uris;
+        if (redirectUri === undefined) {
+            throw new Error("MCP OAuth client metadata has no redirect_uris");
+        }
+        return redirectUri;
+    }
+    get clientMetadata() {
+        return this._clientMetadata;
+    }
+    clientInformation() {
+        return this.storage.getClientInfo();
+    }
+    async saveClientInformation(info) {
+        await this.storage.saveClientInfo(info);
+    }
+    tokens() {
+        return this.storage.getTokens();
+    }
+    async saveTokens(tokens) {
+        await this.storage.saveTokens(tokens);
+    }
+    redirectToAuthorization() {
+        throw new Error(INTERACTIVE_LOGIN_REQUIRED_MESSAGE(this.serverName));
+    }
+    saveCodeVerifier() {
+        throw new Error(INTERACTIVE_LOGIN_REQUIRED_MESSAGE(this.serverName));
+    }
+    codeVerifier() {
+        throw new Error(INTERACTIVE_LOGIN_REQUIRED_MESSAGE(this.serverName));
+    }
+}
+/**
+ * Return a non-interactive OAuth provider for a configured MCP server.
+ *
+ * `cacheDir` overrides `mcpOauthCacheDir()` — used by tests and any caller
+ * that needs an isolated cache location instead of the shared `agentengine dev`
+ * cache directory.
+ */
+export function makeMcpOauthAuth(serverName, config, cacheDir) {
+    const redirectUri = config.auth.redirect_uri ?? DEFAULT_MCP_OAUTH_REDIRECT_URI;
+    return new FileBackedOAuthProvider(serverName, config, redirectUri, cacheDir);
+}
+/**
+ * `client_credentials` OAuth provider with file-backed token caching.
+ *
+ * Wraps the SDK's `ClientCredentialsProvider` (which only caches tokens
+ * in-memory) so refreshed tokens persist across process restarts, matching
+ * Python's `CachedClientCredentialsOAuthProvider`. When `auth.token_url` is
+ * configured (Atlas-style out-of-band token endpoint), pre-seeds discovery
+ * state so the SDK's `auth()` orchestrator skips RFC 9728/8414 discovery and
+ * posts directly to that endpoint — mirroring Python's
+ * `DirectClientCredentialsOAuthProvider`.
+ */
+class FileBackedClientCredentialsProvider {
+    inner;
+    storage;
+    tokenUrl;
+    constructor(serverName, config, clientId, clientSecret, cacheDir) {
+        this.inner = new ClientCredentialsProvider({
+            clientId,
+            clientSecret,
+            scope: config.auth.scope ?? undefined,
+        });
+        this.storage = new FileOAuthTokenStorage(serverName, config.url, cacheDir, clientId, config.auth.scope ?? undefined);
+        this.tokenUrl = config.auth.token_url;
+    }
+    get redirectUrl() {
+        return undefined;
+    }
+    get clientMetadata() {
+        return this.inner.clientMetadata;
+    }
+    clientInformation() {
+        return this.inner.clientInformation();
+    }
+    saveClientInformation(info) {
+        this.inner.saveClientInformation(info);
+    }
+    tokens() {
+        return this.storage.getTokens();
+    }
+    async saveTokens(tokens) {
+        await this.storage.saveTokens(tokens);
+        this.inner.saveTokens(tokens);
+    }
+    redirectToAuthorization() {
+        this.inner.redirectToAuthorization();
+    }
+    saveCodeVerifier() {
+        this.inner.saveCodeVerifier();
+    }
+    codeVerifier() {
+        return this.inner.codeVerifier();
+    }
+    prepareTokenRequest(scope) {
+        return this.inner.prepareTokenRequest(scope);
+    }
+    discoveryState() {
+        if (this.tokenUrl === null)
+            return undefined;
+        return {
+            authorizationServerUrl: this.tokenUrl,
+            authorizationServerMetadata: {
+                issuer: this.tokenUrl,
+                authorization_endpoint: this.tokenUrl,
+                token_endpoint: this.tokenUrl,
+                response_types_supported: ["token"],
+            },
+        };
+    }
+    saveDiscoveryState() {
+        // No-op: the token URL is static config, not something discovery
+        // produces — nothing to persist beyond what discoveryState() returns.
+    }
+}
+function requiredEnvValue(serverName, fieldName, envName) {
+    const value = envName === null ? undefined : process.env[envName];
+    if (value === undefined || value.trim() === "") {
+        throw new Error(`mcp server '${serverName}' auth.${fieldName} references missing env var ${envName}`);
+    }
+    return value.trim();
+}
+/**
+ * Return a client-credentials OAuth provider for a configured MCP server.
+ *
+ * `cacheDir` overrides `mcpOauthCacheDir()` — used by tests and any caller
+ * that needs an isolated cache location instead of the shared `agentengine dev`
+ * cache directory.
+ */
+export function makeMcpClientCredentialsAuth(serverName, config, cacheDir) {
+    const auth = config.auth;
+    const clientId = requiredEnvValue(serverName, "client_id_env", auth.client_id_env);
+    const clientSecret = requiredEnvValue(serverName, "client_secret_env", auth.client_secret_env);
+    return new FileBackedClientCredentialsProvider(serverName, config, clientId, clientSecret, cacheDir);
+}

package/dist/mcp_oauth_secret.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Materialize deployed MCP OAuth secrets into the file-backed token cache.
+ *
+ * Port of `agent_engine_runner_shared/mcp_oauth_secret.py`. On deploy the platform injects
+ * each server's OAuth cache as a base64-encoded `AGENTIC_MCP_OAUTH_B64_*` env
+ * var; this decodes them into the cache directory that `mcp_oauth.ts` reads,
+ * keeping the on-disk layout byte-identical to the Python side so either SDK
+ * (and the Go CLI) can read the same files.
+ */
+interface MaterializeOptions {
+    defaultCacheDir?: string;
+}
+/**
+ * Establish the writable runtime cache and decode MCP OAuth secrets into it.
+ *
+ * Sets `AGENTIC_MCP_OAUTH_DIR` (if unset) so the reader in `mcp_oauth.ts`
+ * resolves the same directory. Returns the number of secrets materialized.
+ */
+export declare function materializeMcpOauthSecretCache({ defaultCacheDir, }?: MaterializeOptions): Promise<number>;
+export {};
+//# sourceMappingURL=mcp_oauth_secret.d.ts.map

package/dist/mcp_oauth_secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp_oauth_secret.d.ts","sourceRoot":"","sources":["../src/mcp_oauth_secret.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH,UAAU,kBAAkB;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAOD;;;;;GAKG;AACH,wBAAsB,8BAA8B,CAAC,EACnD,eAA8C,GAC/C,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB3C"}

package/dist/mcp_oauth_secret.js

@@ -0,0 +1,122 @@
+/**
+ * Materialize deployed MCP OAuth secrets into the file-backed token cache.
+ *
+ * Port of `agent_engine_runner_shared/mcp_oauth_secret.py`. On deploy the platform injects
+ * each server's OAuth cache as a base64-encoded `AGENTIC_MCP_OAUTH_B64_*` env
+ * var; this decodes them into the cache directory that `mcp_oauth.ts` reads,
+ * keeping the on-disk layout byte-identical to the Python side so either SDK
+ * (and the Go CLI) can read the same files.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { lock } from "proper-lockfile";
+import { mcpOauthCacheName } from "./mcp_oauth.js";
+const MCP_OAUTH_DIR_ENV = "AGENTIC_MCP_OAUTH_DIR";
+const MCP_OAUTH_SECRET_ENV_PREFIX = "AGENTIC_MCP_OAUTH_B64_";
+const PLATFORM_MCP_OAUTH_CACHE_DIR = "/tmp/agentic/mcp-oauth";
+const SAFE_ENV_CACHE_NAME_RE = /^[A-Z0-9_]+$/;
+const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+/**
+ * Establish the writable runtime cache and decode MCP OAuth secrets into it.
+ *
+ * Sets `AGENTIC_MCP_OAUTH_DIR` (if unset) so the reader in `mcp_oauth.ts`
+ * resolves the same directory. Returns the number of secrets materialized.
+ */
+export async function materializeMcpOauthSecretCache({ defaultCacheDir = PLATFORM_MCP_OAUTH_CACHE_DIR, } = {}) {
+    const cacheDir = process.env[MCP_OAUTH_DIR_ENV] ?? defaultCacheDir;
+    if (process.env[MCP_OAUTH_DIR_ENV] === undefined) {
+        process.env[MCP_OAUTH_DIR_ENV] = cacheDir;
+    }
+    fs.mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+    let materialized = 0;
+    for (const [envName, encodedCache] of mcpOauthSecretEnv()) {
+        const { rawCache, payload } = decodeCacheSecret(envName, encodedCache);
+        const cacheName = cacheNameFor(envName, payload);
+        await writeCacheFile(cacheDir, cacheName, rawCache);
+        delete process.env[envName];
+        materialized += 1;
+    }
+    return materialized;
+}
+function mcpOauthSecretEnv() {
+    return Object.entries(process.env)
+        .filter((entry) => entry[0].startsWith(MCP_OAUTH_SECRET_ENV_PREFIX) &&
+        entry[1] !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+function decodeCacheSecret(envName, encodedCache) {
+    // Strict base64: mirror Python's `validate=True`. Node's decoder silently
+    // drops out-of-alphabet characters, so reject them up front rather than
+    // materializing a truncated cache.
+    if (encodedCache.length % 4 !== 0 || !BASE64_RE.test(encodedCache)) {
+        throw new Error(`invalid MCP OAuth secret ${envName}: value is not valid base64`);
+    }
+    const rawCache = Buffer.from(encodedCache, "base64");
+    let payload;
+    try {
+        payload = JSON.parse(rawCache.toString("utf-8"));
+    }
+    catch (err) {
+        throw new Error(`invalid MCP OAuth secret ${envName}: decoded value is not valid JSON`, { cause: err });
+    }
+    if (payload === null ||
+        typeof payload !== "object" ||
+        Array.isArray(payload)) {
+        throw new Error(`invalid MCP OAuth secret ${envName}: decoded value must be a JSON object`);
+    }
+    return { rawCache, payload: payload };
+}
+function cacheNameFor(envName, payload) {
+    // The runtime looks the cache up by the configured server URL's hash, so a
+    // payload without server_url could never be found — fail loudly instead of
+    // materializing an unreadable file.
+    const serverUrl = payload["server_url"];
+    if (typeof serverUrl !== "string" || serverUrl.trim() === "") {
+        throw new Error(`invalid MCP OAuth secret ${envName}: missing server_url`);
+    }
+    const payloadServerName = payload["server_name"];
+    if (typeof payloadServerName === "string" &&
+        payloadServerName.trim() !== "") {
+        return mcpOauthCacheName(payloadServerName, serverUrl);
+    }
+    const envCacheName = envName.slice(MCP_OAUTH_SECRET_ENV_PREFIX.length);
+    if (envCacheName === "" || !SAFE_ENV_CACHE_NAME_RE.test(envCacheName)) {
+        throw new Error(`invalid MCP OAuth secret ${envName}: invalid cache name`);
+    }
+    return mcpOauthCacheName(envCacheName.toLowerCase(), serverUrl);
+}
+async function writeCacheFile(cacheDir, cacheName, rawCache) {
+    const cacheFile = path.join(cacheDir, `${cacheName}.json`);
+    let release;
+    try {
+        // Same lock target/params as `mcp_oauth.ts`'s writePayload, so a
+        // materialize write and a runtime token refresh can't clobber each other.
+        release = await lock(cacheFile, {
+            realpath: false,
+            stale: 5000,
+            retries: { retries: 10, minTimeout: 20, maxTimeout: 200 },
+        });
+    }
+    catch (err) {
+        throw new Error(`failed to acquire MCP OAuth cache lock for ${JSON.stringify(cacheFile)}: ` +
+            `${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    const tmpName = path.join(cacheDir, `.tmp-${cacheName}-${process.pid}-${Date.now()}`);
+    try {
+        try {
+            fs.writeFileSync(tmpName, rawCache, { mode: 0o600 });
+            fs.renameSync(tmpName, cacheFile);
+        }
+        finally {
+            try {
+                fs.unlinkSync(tmpName);
+            }
+            catch {
+                // Already renamed into place, or never created — nothing to clean up.
+            }
+        }
+    }
+    finally {
+        await release();
+    }
+}

package/dist/mcp_tools.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Framework-neutral helpers for remote MCP tool discovery and execution.
+ *
+ * Port of `agent_engine_runner_shared/mcp_tools.py`. Built directly on
+ * `@modelcontextprotocol/sdk` (mirroring Python's `mcp` PyPI package) rather
+ * than a framework-specific adapter, since the platform needs custom result
+ * normalization, egress host derivation, and the Tool-Pod/AER dispatch split
+ * that a framework wrapper doesn't support.
+ */
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { RuntimeMCPConfig, RuntimeMCPServerConfig } from "./agent_config.js";
+/** Raised when remote MCP configuration cannot be resolved. */
+export declare class MCPConfigError extends Error {
+    constructor(message: string);
+}
+/** Raised when a remote MCP tool returns an MCP error result or a transport failure occurs. */
+export declare class MCPToolError extends Error {
+    constructor(message: string);
+}
+/** Discovered MCP tool bound to a configured server. */
+export interface MCPToolBinding {
+    readonly serverName: string;
+    readonly toolName: string;
+    readonly sdkToolName: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    readonly serverConfig: RuntimeMCPServerConfig;
+}
+/** JSON/BSON-safe result returned by an MCP `tools/call` invocation. */
+export interface MCPToolResult {
+    readonly content: unknown[];
+    readonly structuredContent: Record<string, unknown> | null;
+    readonly isError: boolean;
+}
+/** Return the server-prefixed SDK name for a remote MCP tool. */
+export declare function makeMcpSdkToolName(serverName: string, toolName: string): string;
+/** Resolve headers for a remote MCP server without exposing secret values in config. */
+export declare function resolveMcpHeaders(serverName: string, config: RuntimeMCPServerConfig): Record<string, string>;
+/** Resolve an MCP SDK OAuth provider for the configured auth mode, if any. */
+export declare function resolveMcpAuth(serverName: string, config: RuntimeMCPServerConfig): Promise<OAuthClientProvider | undefined>;
+/** Return the outbound hosts needed to reach a configured MCP server. */
+export declare function mcpServerNetworkHosts(config: RuntimeMCPServerConfig): string[];
+/**
+ * Discover remote MCP tools for all configured servers.
+ *
+ * Mirrors common MCP client adapters: initialize each server, call
+ * `tools/list`, then expose the returned schemas as framework-native tools.
+ */
+export declare function discoverMcpTools(config: RuntimeMCPConfig): Promise<MCPToolBinding[]>;
+/**
+ * Map an SDK-visible tool name back to configured MCP call metadata.
+ *
+ * AER discovers remote MCP schemas at startup and exposes server-prefixed
+ * names such as `github__search_issues` to the LLM. Tool Pods skip
+ * `tools/list` startup discovery, so call-time execution resolves that SDK
+ * name against `agent.yaml` and calls the original MCP tool name.
+ */
+export declare function resolveConfiguredMcpToolBinding(config: RuntimeMCPConfig, sdkToolName: string, mcpServerName: string, mcpToolName: string): MCPToolBinding | null;
+/** Return whether `sdkToolName` belongs to a configured MCP server. */
+export declare function isConfiguredMcpSdkToolName(config: RuntimeMCPConfig, sdkToolName: string): boolean;
+/** Execute a remote MCP tool and normalize its result. */
+export declare function callMcpTool(binding: MCPToolBinding, args: Record<string, unknown>): Promise<MCPToolResult>;
+/** Create the async callable used to invoke a discovered MCP tool. */
+export declare function makeMcpToolCallable(binding: MCPToolBinding): (args: Record<string, unknown>) => Promise<MCPToolResult>;
+/** Convert an MCP `CallToolResult` into a JSON-safe result, raising on an error result. */
+export declare function normalizeMcpToolResult(result: {
+    content?: unknown[];
+    structuredContent?: unknown;
+    isError?: boolean;
+}): MCPToolResult;
+//# sourceMappingURL=mcp_tools.d.ts.map

package/dist/mcp_tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp_tools.d.ts","sourceRoot":"","sources":["../src/mcp_tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAEpF,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAO3B,+DAA+D;AAC/D,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,+FAA+F;AAC/F,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,QAAQ,CAAC,YAAY,EAAE,sBAAsB,CAAC;CAC/C;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,CAIR;AAqBD,wFAAwF;AACxF,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,sBAAsB,GAC7B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwBxB;AAED,8EAA8E;AAC9E,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAsB1C;AAED,yEAAyE;AACzE,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,sBAAsB,GAC7B,MAAM,EAAE,CAOV;AAQD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,cAAc,EAAE,CAAC,CA2C3B;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,gBAAgB,EACxB,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAClB,cAAc,GAAG,IAAI,CA4BvB;AAED,uEAAuE;AACvE,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,gBAAgB,EACxB,WAAW,EAAE,MAAM,GAClB,OAAO,CAWT;AAED,0DAA0D;AAC1D,wBAAsB,WAAW,CAC/B,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,aAAa,CAAC,CAuBxB;AAED,sEAAsE;AACtE,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,GACtB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAE3D;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,aAAa,CA8ChB"}