@electric-ax/agents-mcp 0.2.0

package/dist/index.cjs

@@ -0,0 +1,1169 @@
+"use strict";
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __modelcontextprotocol_sdk_client_index_js = __toESM(require("@modelcontextprotocol/sdk/client/index.js"));
+const __modelcontextprotocol_sdk_client_streamableHttp_js = __toESM(require("@modelcontextprotocol/sdk/client/streamableHttp.js"));
+const __modelcontextprotocol_sdk_client_stdio_js = __toESM(require("@modelcontextprotocol/sdk/client/stdio.js"));
+const node_fs_promises = __toESM(require("node:fs/promises"));
+const node_fs = __toESM(require("node:fs"));
+const node_child_process = __toESM(require("node:child_process"));
+const node_path = __toESM(require("node:path"));
+
+//#region src/tools.ts
+const MCP_TOOLS_SENTINEL = Symbol.for(`@electric-ax/agents-mcp/tools-sentinel`);
+function isMcpToolsSentinel(x) {
+	return !!x && typeof x === `object` && x[MCP_TOOLS_SENTINEL] === true;
+}
+const mcp = { tools(allowlist) {
+	return [{
+		[MCP_TOOLS_SENTINEL]: true,
+		allowlist
+	}];
+} };
+function filterByAllowlist(serverNames, allowlist) {
+	if (allowlist === void 0) return [...serverNames];
+	const set = new Set(allowlist);
+	return serverNames.filter((n) => set.has(n));
+}
+
+//#endregion
+//#region src/credentials/auth-store.ts
+function createAuthStore() {
+	const tokens = new Map();
+	const clients = new Map();
+	const hooks = new Map();
+	return {
+		seedTokens(server, t) {
+			tokens.set(server, t);
+		},
+		seedClient(server, c) {
+			clients.set(server, c);
+		},
+		registerHooks(server, h) {
+			hooks.set(server, h);
+		},
+		clearCredentials(server) {
+			tokens.delete(server);
+			clients.delete(server);
+		},
+		forget(server) {
+			tokens.delete(server);
+			clients.delete(server);
+			hooks.delete(server);
+		},
+		getOAuthTokens(server) {
+			return tokens.get(server);
+		},
+		async saveOAuthTokens(server, t) {
+			tokens.set(server, t);
+			const h = hooks.get(server);
+			if (h?.onTokensChanged) await h.onTokensChanged(t);
+		},
+		getOAuthClientInfo(server) {
+			return clients.get(server);
+		},
+		async saveOAuthClientInfo(server, c) {
+			clients.set(server, c);
+			const h = hooks.get(server);
+			if (h?.onClientRegistered) await h.onClientRegistered(c);
+		}
+	};
+}
+
+//#endregion
+//#region src/transports/http.ts
+function createHttpTransport(opts) {
+	const fetchImpl = opts.fetchImpl ?? fetch;
+	const transport = new __modelcontextprotocol_sdk_client_streamableHttp_js.StreamableHTTPClientTransport(new URL(opts.url), {
+		authProvider: opts.authProvider,
+		fetch: opts.headerProvider ? async (url, init) => {
+			const headers = new Headers(init?.headers);
+			const h = await opts.headerProvider();
+			if (h) headers.set(h.name, h.value);
+			return fetchImpl(url, {
+				...init,
+				headers
+			});
+		} : fetchImpl
+	});
+	const client = new __modelcontextprotocol_sdk_client_index_js.Client({
+		name: `@electric-ax/agents-mcp`,
+		version: `0.1.0`
+	}, { capabilities: {} });
+	return {
+		client,
+		async connect() {
+			await client.connect(transport);
+		},
+		async close() {
+			await client.close();
+		}
+	};
+}
+
+//#endregion
+//#region src/transports/stdio.ts
+function createStdioTransport(opts) {
+	const transport = new __modelcontextprotocol_sdk_client_stdio_js.StdioClientTransport({
+		command: opts.command,
+		args: opts.args ?? [],
+		env: opts.env
+	});
+	const client = new __modelcontextprotocol_sdk_client_index_js.Client({
+		name: `@electric-ax/agents-mcp`,
+		version: `0.1.0`
+	}, { capabilities: {} });
+	return {
+		client,
+		async connect() {
+			await client.connect(transport);
+		},
+		async close() {
+			await client.close();
+		}
+	};
+}
+
+//#endregion
+//#region src/auth/api-key.ts
+function buildApiKeyHeader(apiKey, opts = {}) {
+	return {
+		name: opts.headerName ?? `Authorization`,
+		value: (opts.valuePrefix ?? ``) + apiKey
+	};
+}
+
+//#endregion
+//#region src/auth/sdk-provider.ts
+function createSdkOAuthProvider(opts) {
+	const redirect = opts.redirectUri ?? `${opts.publicUrl.replace(/\/$/, ``)}/oauth/callback/${opts.server}`;
+	let codeVerifier;
+	let lastAuthUrl;
+	const toSdkTokens = (t) => ({
+		access_token: t.accessToken,
+		refresh_token: t.refreshToken,
+		expires_in: t.expiresAt ? Math.max(0, t.expiresAt - Math.floor(Date.now() / 1e3)) : void 0,
+		token_type: t.tokenType ?? `Bearer`,
+		scope: t.scope
+	});
+	const fromSdkTokens = (t) => ({
+		accessToken: t.access_token,
+		refreshToken: t.refresh_token,
+		expiresAt: t.expires_in ? Math.floor(Date.now() / 1e3) + t.expires_in : void 0,
+		tokenType: t.token_type,
+		scope: t.scope
+	});
+	const toSdkClientInfo = (c) => ({
+		client_id: c.clientId,
+		client_secret: c.clientSecret,
+		redirect_uris: c.redirectUris ?? [redirect]
+	});
+	const fromSdkClientInfo = (c) => ({
+		clientId: c.client_id,
+		clientSecret: c.client_secret,
+		redirectUris: c.redirect_uris?.map(String),
+		registeredAt: Math.floor(Date.now() / 1e3)
+	});
+	return {
+		get redirectUrl() {
+			return redirect;
+		},
+		get clientMetadata() {
+			return {
+				client_name: `@electric-ax/agents-mcp`,
+				redirect_uris: [redirect],
+				grant_types: [`authorization_code`, `refresh_token`],
+				response_types: [`code`],
+				token_endpoint_auth_method: `client_secret_post`,
+				scope: opts.scopes?.join(` `)
+			};
+		},
+		async clientInformation() {
+			const saved = opts.authStore.getOAuthClientInfo(opts.server);
+			return saved ? toSdkClientInfo(saved) : void 0;
+		},
+		async saveClientInformation(info) {
+			await opts.authStore.saveOAuthClientInfo(opts.server, fromSdkClientInfo(info));
+		},
+		async tokens() {
+			const saved = opts.authStore.getOAuthTokens(opts.server);
+			return saved ? toSdkTokens(saved) : void 0;
+		},
+		async saveTokens(tokens) {
+			await opts.authStore.saveOAuthTokens(opts.server, fromSdkTokens(tokens));
+		},
+		redirectToAuthorization(url) {
+			lastAuthUrl = url.toString();
+		},
+		saveCodeVerifier(v) {
+			codeVerifier = v;
+		},
+		async codeVerifier() {
+			if (!codeVerifier) throw new Error(`No PKCE codeVerifier set for "${opts.server}"`);
+			return codeVerifier;
+		},
+		peekAuthUrl() {
+			return lastAuthUrl;
+		},
+		clearAuthUrl() {
+			lastAuthUrl = void 0;
+		}
+	};
+}
+
+//#endregion
+//#region src/auth/client-credentials.ts
+/**
+* Minimal OAuthClientProvider implementing only what's needed for clientCredentials:
+* lazy fetches a token on `tokens()`. The SDK's transport uses `tokens()` to attach
+* Authorization headers and re-calls on 401.
+*/
+function createClientCredentialsProvider(opts) {
+	let cached;
+	return {
+		get redirectUrl() {
+			return ``;
+		},
+		get clientMetadata() {
+			return {};
+		},
+		async clientInformation() {
+			return {
+				client_id: opts.clientId,
+				client_secret: opts.clientSecret
+			};
+		},
+		async saveClientInformation() {},
+		async tokens() {
+			const now = Math.floor(Date.now() / 1e3);
+			if (cached && cached.expiresAt - 30 > now) return {
+				access_token: cached.access_token,
+				token_type: `Bearer`
+			};
+			const body = new URLSearchParams({
+				grant_type: `client_credentials`,
+				client_id: opts.clientId,
+				client_secret: opts.clientSecret
+			});
+			if (opts.scopes?.length) body.set(`scope`, opts.scopes.join(` `));
+			if (opts.audience) body.set(`audience`, opts.audience);
+			if (opts.resource) body.set(`resource`, opts.resource);
+			const res = await fetch(opts.tokenUrl, {
+				method: `POST`,
+				headers: { "Content-Type": `application/x-www-form-urlencoded` },
+				body
+			});
+			if (!res.ok) throw new Error(`clientCredentials token endpoint ${res.status}`);
+			const json = await res.json();
+			cached = {
+				access_token: json.access_token,
+				expiresAt: now + (json.expires_in ?? 300)
+			};
+			return {
+				access_token: json.access_token,
+				token_type: `Bearer`
+			};
+		},
+		async saveTokens() {},
+		redirectToAuthorization() {},
+		saveCodeVerifier() {},
+		async codeVerifier() {
+			return ``;
+		}
+	};
+}
+
+//#endregion
+//#region src/registry.ts
+function hashConfig(c) {
+	const parts = [
+		c.name,
+		c.transport,
+		c.url ?? ``,
+		c.auth?.mode ?? `none`,
+		String(c.timeoutMs ?? ``)
+	];
+	if (c.auth && (c.auth.mode === `authorizationCode` || c.auth.mode === `clientCredentials`)) parts.push((c.auth.scopes ?? []).slice().sort().join(`,`));
+	if (c.transport === `stdio`) parts.push(c.command, (c.args ?? []).join(` `));
+	return parts.join(`|`);
+}
+function makeError(kind, message) {
+	return {
+		kind,
+		message
+	};
+}
+function createRegistry(opts) {
+	const entries = new Map();
+	const authStore = opts.authStore ?? createAuthStore();
+	const buildTransport = async (cfg) => {
+		if (cfg.transport === `stdio`) {
+			if (opts.transportFactoryOverride) return { transport: opts.transportFactoryOverride(cfg) };
+			return { transport: createStdioTransport({
+				name: cfg.name,
+				command: cfg.command,
+				args: cfg.args,
+				env: cfg.env
+			}) };
+		}
+		if (cfg.auth.mode === `none`) {
+			if (opts.transportFactoryOverride) return { transport: opts.transportFactoryOverride(cfg) };
+			return { transport: createHttpTransport({
+				name: cfg.name,
+				url: cfg.url
+			}) };
+		}
+		if (cfg.auth.mode === `apiKey`) {
+			if (opts.transportFactoryOverride) return { transport: opts.transportFactoryOverride(cfg) };
+			if (!cfg.auth.key) return { error: makeError(`auth_unavailable`, `no auth.key for ${cfg.name} (apiKey mode requires the secret inline)`) };
+			const header = buildApiKeyHeader(cfg.auth.key, {
+				headerName: cfg.auth.headerName,
+				valuePrefix: cfg.auth.valuePrefix
+			});
+			const headerProvider = async () => header;
+			return { transport: createHttpTransport({
+				name: cfg.name,
+				url: cfg.url,
+				headerProvider
+			}) };
+		}
+		if (cfg.auth.mode === `authorizationCode`) {
+			const publicUrl = opts.publicUrl ?? `http://localhost`;
+			const provider = createSdkOAuthProvider({
+				server: cfg.name,
+				publicUrl,
+				authStore,
+				scopes: cfg.auth.scopes,
+				redirectUri: cfg.auth.redirectUri,
+				resource: cfg.auth.resource
+			});
+			if (opts.transportFactoryOverride) return {
+				transport: opts.transportFactoryOverride(cfg, void 0, provider),
+				provider
+			};
+			return {
+				transport: createHttpTransport({
+					name: cfg.name,
+					url: cfg.url,
+					authProvider: provider
+				}),
+				provider
+			};
+		}
+		if (cfg.auth.mode === `clientCredentials`) {
+			if (!cfg.auth.clientId || !cfg.auth.clientSecret) return { error: makeError(`auth_unavailable`, `clientCredentials mode requires auth.clientId and auth.clientSecret inline for ${cfg.name}`) };
+			const ccProvider = createClientCredentialsProvider({
+				tokenUrl: cfg.auth.tokenUrl,
+				clientId: cfg.auth.clientId,
+				clientSecret: cfg.auth.clientSecret,
+				scopes: cfg.auth.scopes,
+				audience: cfg.auth.audience,
+				resource: cfg.auth.resource
+			});
+			if (opts.transportFactoryOverride) return { transport: opts.transportFactoryOverride(cfg, void 0, void 0) };
+			return { transport: createHttpTransport({
+				name: cfg.name,
+				url: cfg.url,
+				authProvider: ccProvider
+			}) };
+		}
+		return { error: makeError(`auth_unavailable`, `auth.mode=${cfg.auth.mode} not implemented`) };
+	};
+	const connectAndList = async (entry, provider) => {
+		if (!entry.transport) return {
+			state: `error`,
+			id: entry.config.name,
+			error: entry.error ?? makeError(`transport_error`, `no transport`)
+		};
+		try {
+			await entry.transport.connect();
+			const out = await entry.transport.client.listTools();
+			entry.tools = out.tools.map((t) => ({
+				name: t.name,
+				description: t.description,
+				inputSchema: t.inputSchema
+			}));
+			entry.capabilities = entry.transport.client.getServerCapabilities?.();
+			entry.status = `ready`;
+			notify();
+			return {
+				state: `ready`,
+				id: entry.config.name,
+				toolCount: entry.tools.length
+			};
+		} catch (err) {
+			const authUrl = provider?.peekAuthUrl();
+			if (authUrl) {
+				entry.status = `authenticating`;
+				entry.authUrl = authUrl;
+				entry.provider = provider;
+				notify();
+				try {
+					opts.openAuthorizeUrl?.(authUrl, entry.config.name);
+				} catch {}
+				return {
+					state: `authenticating`,
+					id: entry.config.name,
+					authUrl
+				};
+			}
+			entry.status = `error`;
+			const e = makeError(`transport_error`, err.message);
+			entry.error = e;
+			notify();
+			return {
+				state: `error`,
+				id: entry.config.name,
+				error: e
+			};
+		}
+	};
+	let seq = 0;
+	const subscribers = new Set();
+	const snapshot = () => ({
+		seq: ++seq,
+		servers: registry.list()
+	});
+	const notify = () => {
+		if (subscribers.size === 0) return;
+		const snap = snapshot();
+		for (const h of subscribers) try {
+			h(snap);
+		} catch {}
+	};
+	const registry = {
+		subscribe(handler) {
+			subscribers.add(handler);
+			try {
+				handler({
+					seq: 0,
+					servers: registry.list()
+				});
+			} catch {}
+			return () => {
+				subscribers.delete(handler);
+			};
+		},
+		async addServer(cfg) {
+			const existing = entries.get(cfg.name);
+			const hash = hashConfig(cfg);
+			if (existing && existing.configHash === hash && existing.status === `ready`) return {
+				state: `ready`,
+				id: cfg.name,
+				toolCount: existing.tools.length
+			};
+			if (existing) await Promise.resolve(existing.transport?.close()).catch(() => {});
+			if (cfg.auth?.mode === `authorizationCode`) {
+				if (cfg.auth.tokens) authStore.seedTokens(cfg.name, cfg.auth.tokens);
+				if (cfg.auth.client) authStore.seedClient(cfg.name, cfg.auth.client);
+				authStore.registerHooks(cfg.name, {
+					onTokensChanged: cfg.auth.onTokensChanged,
+					onClientRegistered: cfg.auth.onClientRegistered
+				});
+			}
+			const built = await buildTransport(cfg);
+			const entry = {
+				config: cfg,
+				configHash: hash,
+				status: built.transport ? `connecting` : `error`,
+				transport: built.transport,
+				error: built.error,
+				authUrl: built.authUrl,
+				tools: [],
+				provider: built.provider
+			};
+			entries.set(cfg.name, entry);
+			if (built.error) {
+				notify();
+				return {
+					state: `error`,
+					id: cfg.name,
+					error: built.error
+				};
+			}
+			if (built.authUrl) {
+				entry.status = `authenticating`;
+				notify();
+				try {
+					opts.openAuthorizeUrl?.(built.authUrl, cfg.name);
+				} catch {}
+				return {
+					state: `authenticating`,
+					id: cfg.name,
+					authUrl: built.authUrl
+				};
+			}
+			return await connectAndList(entry, built.provider);
+		},
+		async applyConfig(cfg) {
+			const seen = new Set(cfg.servers.map((s) => s.name));
+			const results = [];
+			for (const s of cfg.servers) results.push(await registry.addServer(s));
+			for (const name of [...entries.keys()]) if (!seen.has(name)) await registry.removeServer(name);
+			return results;
+		},
+		async removeServer(name) {
+			const e = entries.get(name);
+			if (!e) return;
+			await Promise.resolve(e.transport?.close()).catch(() => {});
+			entries.delete(name);
+			authStore.forget(name);
+			notify();
+		},
+		list() {
+			return [...entries.values()].map((e) => ({
+				name: e.config.name,
+				status: e.status,
+				toolCount: e.tools.length,
+				transport: e.config.transport,
+				authMode: e.config.auth?.mode,
+				authUrl: e.authUrl,
+				error: e.error,
+				tools: e.tools,
+				capabilities: e.capabilities
+			}));
+		},
+		get(name) {
+			return entries.get(name);
+		},
+		async finishAuth(serverName, code, _state) {
+			const e = entries.get(serverName);
+			if (!e) throw new Error(`unknown server "${serverName}"`);
+			const provider = e.provider;
+			if (!provider) throw new Error(`server "${serverName}" has no OAuth provider`);
+			const serverUrl = e.config.url;
+			if (!serverUrl) throw new Error(`server "${serverName}" has no URL — cannot complete token exchange`);
+			const { auth } = await import(`@modelcontextprotocol/sdk/client/auth.js`);
+			await auth(provider, {
+				serverUrl,
+				authorizationCode: code
+			});
+			provider.clearAuthUrl();
+			return await registry.addServer(e.config);
+		},
+		async disable(name) {
+			const e = entries.get(name);
+			if (!e) throw new Error(`unknown server "${name}"`);
+			await Promise.resolve(e.transport?.close()).catch(() => {});
+			e.transport = void 0;
+			e.tools = [];
+			e.authUrl = void 0;
+			e.status = `disabled`;
+			e.error = void 0;
+			notify();
+		},
+		async enable(name) {
+			const e = entries.get(name);
+			if (!e) throw new Error(`unknown server "${name}"`);
+			if (e.status !== `disabled`) return {
+				state: `ready`,
+				id: name,
+				toolCount: e.tools.length
+			};
+			return await registry.addServer(e.config);
+		},
+		async reauthorize(name) {
+			const e = entries.get(name);
+			if (!e) return;
+			if (e.config.auth?.mode !== `authorizationCode`) return;
+			if (e.status === `disabled`) return;
+			await Promise.resolve(e.transport?.close()).catch(() => {});
+			authStore.clearCredentials(name);
+			e.status = `connecting`;
+			e.tools = [];
+			e.capabilities = void 0;
+			e.authUrl = void 0;
+			e.error = void 0;
+			notify();
+			const built = await buildTransport(e.config);
+			e.transport = built.transport;
+			e.error = built.error;
+			e.authUrl = built.authUrl;
+			e.provider = built.provider;
+			if (built.error || !built.transport) {
+				e.status = `error`;
+				notify();
+				return;
+			}
+			if (built.authUrl) {
+				e.status = `authenticating`;
+				notify();
+				try {
+					opts.openAuthorizeUrl?.(built.authUrl, name);
+				} catch {}
+				return;
+			}
+			await connectAndList(e, built.provider);
+		},
+		async close() {
+			const transports = [...entries.values()].map((e) => e.transport).filter((t) => Boolean(t));
+			await Promise.all(transports.map((t) => Promise.resolve(t.close()).catch(() => {})));
+			for (const name of [...entries.keys()]) authStore.forget(name);
+			entries.clear();
+			notify();
+		}
+	};
+	return registry;
+}
+
+//#endregion
+//#region src/config/env-expand.ts
+const RE = /\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g;
+function expandString(s, env) {
+	const missing = [];
+	const value = s.replace(RE, (_, name) => {
+		const v = env[name];
+		if (v === void 0) {
+			missing.push(name);
+			return ``;
+		}
+		return v;
+	});
+	return {
+		value,
+		missing
+	};
+}
+function expandEnv(s, env = process.env) {
+	return expandString(s, env).value;
+}
+expandEnv.detailed = (s, env = process.env) => expandString(s, env);
+expandEnv.deep = function deep(input, env = process.env) {
+	if (typeof input === `string`) return expandString(input, env).value;
+	if (Array.isArray(input)) return input.map((x) => deep(x, env));
+	if (input && typeof input === `object`) {
+		const out = {};
+		for (const [k, v] of Object.entries(input)) out[k] = deep(v, env);
+		return out;
+	}
+	return input;
+};
+
+//#endregion
+//#region src/config/loader.ts
+const KNOWN_AUTH_MODES = new Set([
+	`none`,
+	`apiKey`,
+	`clientCredentials`,
+	`authorizationCode`
+]);
+const FORBIDDEN_REF_KEYS = [
+	`valueRef`,
+	`clientIdRef`,
+	`clientSecretRef`
+];
+function fail(msg) {
+	throw new Error(`mcp.json: ${msg}`);
+}
+function parseConfig(raw, env = process.env) {
+	if (!raw || typeof raw !== `object`) fail(`not an object`);
+	const top = Object.keys(raw);
+	for (const k of top) if (k !== `servers`) fail(`unknown top-level field "${k}"`);
+	const serversObj = raw.servers;
+	if (!serversObj || typeof serversObj !== `object`) fail(`missing "servers" object`);
+	const servers = [];
+	for (const [name, entry] of Object.entries(serversObj)) {
+		if (!entry || typeof entry !== `object`) fail(`server "${name}" not an object`);
+		const e = entry;
+		if (e.transport !== `http` && e.transport !== `stdio`) fail(`server "${name}" transport must be 'http' or 'stdio'`);
+		const auth = e.auth ?? { mode: `none` };
+		if (typeof auth.mode !== `string` || !KNOWN_AUTH_MODES.has(auth.mode)) fail(`server "${name}" auth.mode invalid`);
+		for (const k of FORBIDDEN_REF_KEYS) if (k in auth) fail(`server "${name}" uses forbidden "${k}" — secrets are not configured in mcp.json (pass them inline on the auth config at the call site)`);
+		if (e.transport === `http`) {
+			if (typeof e.url !== `string`) fail(`server "${name}" missing url`);
+			servers.push({
+				name,
+				transport: `http`,
+				url: expandEnv(e.url, env),
+				auth: expandEnv.deep(auth, env),
+				timeoutMs: typeof e.timeoutMs === `number` ? e.timeoutMs : void 0
+			});
+		} else {
+			if (typeof e.command !== `string`) fail(`server "${name}" missing command`);
+			const args = Array.isArray(e.args) ? e.args.map((a) => expandEnv(String(a), env)) : [];
+			servers.push({
+				name,
+				transport: `stdio`,
+				command: expandEnv(e.command, env),
+				args,
+				env: e.env && typeof e.env === `object` ? Object.fromEntries(Object.entries(e.env).map(([k, v]) => [k, expandEnv(String(v), env)])) : void 0,
+				auth: expandEnv.deep(auth, env),
+				timeoutMs: typeof e.timeoutMs === `number` ? e.timeoutMs : void 0
+			});
+		}
+	}
+	return {
+		servers,
+		raw
+	};
+}
+async function loadConfig(path$1, env = process.env) {
+	const text = await node_fs_promises.default.readFile(path$1, `utf-8`);
+	return parseConfig(JSON.parse(text), env);
+}
+
+//#endregion
+//#region src/config/watcher.ts
+/**
+* Start watching `path` for changes. Each modification triggers
+* `loadConfig(path)` (debounced) and forwards the parsed config to
+* `onChange`, or any error to `onError`. The caller is responsible
+* for performing the initial load — `watchConfig` only sets up the
+* subscription so the caller can fully await its first apply before
+* subsequent change events start firing.
+*/
+async function watchConfig(path$1, opts) {
+	const debounce = opts.debounceMs ?? 200;
+	let timer;
+	const reload = async () => {
+		try {
+			const cfg = await loadConfig(path$1, opts.env);
+			opts.onChange(cfg);
+		} catch (err) {
+			opts.onError?.(err);
+		}
+	};
+	const watcher = node_fs.default.watch(path$1, () => {
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(reload, debounce);
+	});
+	return () => {
+		if (timer) clearTimeout(timer);
+		watcher.close();
+	};
+}
+
+//#endregion
+//#region src/transports/timeout.ts
+const DEFAULT_TIMEOUT_MS = 3e4;
+var TimeoutError = class extends Error {
+	kind = `timeout`;
+	constructor(ms) {
+		super(`MCP tool call timed out after ${ms}ms`);
+	}
+};
+function withTimeout(p, ms) {
+	let timer;
+	const guard = new Promise((_, reject) => {
+		timer = setTimeout(() => reject(new TimeoutError(ms)), ms);
+	});
+	return Promise.race([p, guard]).finally(() => {
+		if (timer) clearTimeout(timer);
+	});
+}
+
+//#endregion
+//#region src/bridge/tool-bridge.ts
+const PREFIX = `mcp`;
+const MAX_LEN = 128;
+function sanitize(name) {
+	return name.replace(/[^A-Za-z0-9_-]/g, `_`);
+}
+function prefixToolName(server, tool) {
+	const full = `${PREFIX}__${sanitize(server)}__${sanitize(tool)}`;
+	return full.length > MAX_LEN ? full.slice(0, MAX_LEN) : full;
+}
+/**
+* Coerce an MCP tool's inputSchema into a shape downstream LLM adapters can
+* consume safely. Some servers send `{ type: 'object' }` with no `properties`
+* for no-arg tools; pi-agent-core walks `inputSchema.properties` and crashes on
+* undefined. We default `properties` to `{}` and `required` to `[]` for object
+* schemas; non-object schemas pass through unchanged.
+*/
+function normalizeInputSchema(schema) {
+	if (!schema || typeof schema !== `object`) return {
+		type: `object`,
+		properties: {},
+		required: []
+	};
+	const s = schema;
+	if (s.type !== `object`) return schema;
+	if (s.properties && typeof s.properties === `object`) return schema;
+	return {
+		...s,
+		properties: {},
+		required: Array.isArray(s.required) ? s.required : []
+	};
+}
+/**
+* Build a BridgedTool from a synthetic (non-MCP-server-backed) call. Used by
+* the resource and prompt bridges. Caller supplies the JSON schema directly.
+*/
+function makeSyntheticBridgedTool(opts) {
+	return {
+		name: opts.name,
+		server: opts.server,
+		description: opts.description,
+		inputSchema: opts.schema,
+		parameters: opts.schema,
+		label: opts.label,
+		async call(args) {
+			return await opts.run(args);
+		},
+		async execute(_toolCallId, params, signal) {
+			const result = await opts.run(params, signal);
+			return {
+				content: Array.isArray(result?.content) ? result.content : [],
+				details: result
+			};
+		}
+	};
+}
+function bridgeMcpTool(opts) {
+	const name = prefixToolName(opts.server, opts.tool.name);
+	const schema = normalizeInputSchema(opts.tool.inputSchema);
+	const ms = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const invoke = async (args, extra) => {
+		const onProgress = extra?.onProgress ?? opts.onProgress;
+		const signal = extra?.signal ?? opts.signal;
+		const callArgs = onProgress !== void 0 || signal !== void 0 ? [
+			{
+				name: opts.tool.name,
+				arguments: args
+			},
+			void 0,
+			{
+				onProgress,
+				signal
+			}
+		] : [{
+			name: opts.tool.name,
+			arguments: args
+		}];
+		return await withTimeout(opts.client.callTool(...callArgs), ms);
+	};
+	return {
+		name,
+		server: opts.server,
+		description: opts.tool.description,
+		inputSchema: schema,
+		parameters: schema,
+		label: opts.tool.name,
+		async call(args) {
+			try {
+				return await invoke(args);
+			} catch (err) {
+				const e = err;
+				if (e.kind === `timeout`) throw err;
+				const wrapped = {
+					kind: `transport_error`,
+					message: e.message ?? String(err)
+				};
+				throw wrapped;
+			}
+		},
+		async execute(_toolCallId, params, signal) {
+			const result = await invoke(params, { signal });
+			return {
+				content: Array.isArray(result?.content) ? result.content : [],
+				details: result
+			};
+		}
+	};
+}
+
+//#endregion
+//#region src/bridge/resource-bridge.ts
+function buildResourceTools(opts) {
+	const ms = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	return [makeSyntheticBridgedTool({
+		name: prefixToolName(opts.server, `list_resources`),
+		server: opts.server,
+		label: `list_resources`,
+		description: `List resources on ${opts.server}`,
+		schema: {
+			type: `object`,
+			properties: {},
+			required: []
+		},
+		run: () => withTimeout(opts.client.listResources(), ms)
+	}), makeSyntheticBridgedTool({
+		name: prefixToolName(opts.server, `read_resource`),
+		server: opts.server,
+		label: `read_resource`,
+		description: `Read a resource from ${opts.server}`,
+		schema: {
+			type: `object`,
+			properties: { uri: { type: `string` } },
+			required: [`uri`]
+		},
+		run: (args) => withTimeout(opts.client.readResource(args), ms)
+	})];
+}
+
+//#endregion
+//#region src/bridge/prompt-bridge.ts
+function buildPromptTools(opts) {
+	const ms = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	return [makeSyntheticBridgedTool({
+		name: prefixToolName(opts.server, `list_prompts`),
+		server: opts.server,
+		label: `list_prompts`,
+		description: `List prompts on ${opts.server}`,
+		schema: {
+			type: `object`,
+			properties: {},
+			required: []
+		},
+		run: () => withTimeout(opts.client.listPrompts(), ms)
+	}), makeSyntheticBridgedTool({
+		name: prefixToolName(opts.server, `get_prompt`),
+		server: opts.server,
+		label: `get_prompt`,
+		description: `Get a prompt template from ${opts.server}`,
+		schema: {
+			type: `object`,
+			properties: {
+				name: { type: `string` },
+				arguments: {
+					type: `object`,
+					additionalProperties: true
+				}
+			},
+			required: [`name`]
+		},
+		run: (args) => withTimeout(opts.client.getPrompt(args), ms)
+	})];
+}
+
+//#endregion
+//#region src/persistence/keychain.ts
+async function run(cmd, args, stdin) {
+	return new Promise((resolve) => {
+		const proc = (0, node_child_process.spawn)(cmd, args, { stdio: [
+			`pipe`,
+			`pipe`,
+			`pipe`
+		] });
+		const out = [];
+		const err = [];
+		proc.stdout.on(`data`, (b) => {
+			out.push(b);
+		});
+		proc.stderr.on(`data`, (b) => {
+			err.push(b);
+		});
+		proc.on(`error`, (e) => {
+			resolve({
+				stdout: ``,
+				stderr: e.message,
+				code: -1
+			});
+		});
+		proc.on(`close`, (code) => {
+			resolve({
+				stdout: Buffer.concat(out).toString(`utf8`),
+				stderr: Buffer.concat(err).toString(`utf8`),
+				code
+			});
+		});
+		if (stdin != null) proc.stdin.end(stdin);
+		else proc.stdin.end();
+	});
+}
+const macosBackend = {
+	async get(service, account) {
+		const r = await run(`security`, [
+			`find-generic-password`,
+			`-s`,
+			service,
+			`-a`,
+			account,
+			`-w`
+		]);
+		if (r.code === 0) return r.stdout.replace(/\n$/, ``);
+		if (/could not be found/i.test(r.stderr)) return void 0;
+		throw new Error(`security find-generic-password failed: ${r.stderr.trim()}`);
+	},
+	async set(service, account, value) {
+		const r = await run(`security`, [
+			`add-generic-password`,
+			`-s`,
+			service,
+			`-a`,
+			account,
+			`-w`,
+			value,
+			`-U`
+		]);
+		if (r.code !== 0) throw new Error(`security add-generic-password failed: ${r.stderr.trim()}`);
+	}
+};
+const linuxBackend = {
+	async get(service, account) {
+		const r = await run(`secret-tool`, [
+			`lookup`,
+			`service`,
+			service,
+			`account`,
+			account
+		]);
+		if (r.code === 0) return r.stdout.replace(/\n$/, ``);
+		if (r.code === 1 && r.stderr.trim() === ``) return void 0;
+		throw new Error(`secret-tool lookup failed: ${r.stderr.trim()}`);
+	},
+	async set(service, account, value) {
+		const r = await run(`secret-tool`, [
+			`store`,
+			`--label`,
+			`${service}/${account}`,
+			`service`,
+			service,
+			`account`,
+			account
+		], value);
+		if (r.code !== 0) throw new Error(`secret-tool store failed: ${r.stderr.trim()}`);
+	}
+};
+function pickBackend() {
+	if (process.platform === `darwin`) return macosBackend;
+	if (process.platform === `linux`) return linuxBackend;
+	return void 0;
+}
+/**
+* Opt-in helper for OAuth-mode `auth` configs. Loads any persisted tokens
+* and DCR client info from the OS keychain on startup, and returns the
+* matching `onTokensChanged` / `onClientRegistered` callbacks so the SDK
+* writes refreshed material back.
+*
+*   const honeycomb = await keychainPersistence({ server: 'honeycomb' })
+*   await mcpRegistry.addServer({
+*     name: 'honeycomb',
+*     transport: 'http',
+*     url: 'https://mcp.honeycomb.io/mcp',
+*     auth: {
+*       mode: 'authorizationCode',
+*       flow: 'browser',
+*       scopes: ['mcp:read'],
+*       ...honeycomb,
+*     },
+*   })
+*
+* Backend is chosen by `process.platform`:
+*   - darwin → `/usr/bin/security` (no extra deps)
+*   - linux  → `secret-tool` from libsecret-tools (apt: libsecret-tools)
+*   - win32  → not implemented yet — falls back to no-op callbacks
+*
+* If the chosen CLI isn't installed (e.g. minimal Linux container without
+* libsecret), reads/writes throw on first use; the registry surfaces
+* that as a connect-time error and the OAuth flow continues without
+* persistence.
+*/
+async function keychainPersistence(opts) {
+	const service = opts.service ?? `electric-agents`;
+	const backend = opts.backend ?? pickBackend();
+	if (!backend) {
+		console.warn(`[agents-mcp] keychainPersistence: ${process.platform} not supported yet — ${opts.server} OAuth tokens will not persist`);
+		return {
+			onTokensChanged: async () => {},
+			onClientRegistered: async () => {}
+		};
+	}
+	const [tokensRaw, clientRaw] = await Promise.all([backend.get(service, `tokens:${opts.server}`), backend.get(service, `client:${opts.server}`)]);
+	return {
+		tokens: tokensRaw ? JSON.parse(tokensRaw) : void 0,
+		client: clientRaw ? JSON.parse(clientRaw) : void 0,
+		onTokensChanged: async (t) => {
+			await backend.set(service, `tokens:${opts.server}`, JSON.stringify(t));
+		},
+		onClientRegistered: async (c) => {
+			await backend.set(service, `client:${opts.server}`, JSON.stringify(c));
+		}
+	};
+}
+
+//#endregion
+//#region src/persistence/file.ts
+async function readSafe(file) {
+	try {
+		const stat = await node_fs_promises.default.stat(file);
+		if ((stat.mode & 511) !== 384) throw new Error(`${file} has permissions ${(stat.mode & 511).toString(8)}; refusing to read (require 0600).`);
+		const text = await node_fs_promises.default.readFile(file, `utf-8`);
+		return text.trim() ? JSON.parse(text) : {};
+	} catch (err) {
+		if (err.code === `ENOENT`) return {};
+		throw err;
+	}
+}
+async function writeSafe(file, data) {
+	await node_fs_promises.default.mkdir(node_path.default.dirname(file), { recursive: true });
+	const tmp = `${file}.tmp`;
+	await node_fs_promises.default.writeFile(tmp, JSON.stringify(data, null, 2), { mode: 384 });
+	await node_fs_promises.default.rename(tmp, file);
+}
+/**
+* Opt-in helper for OAuth-mode `auth` configs. Mirrors `keychainPersistence`
+* but persists to a JSON file on disk (mode 0600). Right tool when no OS
+* keychain is available — CI runners, minimal Linux containers, etc.
+*
+*   const honeycomb = await filePersistence({
+*     path: './.electric-agents/credentials.json',
+*     server: 'honeycomb',
+*   })
+*   await mcpRegistry.addServer({ ..., auth: { ..., ...honeycomb } })
+*/
+async function filePersistence(opts) {
+	const data = await readSafe(opts.path);
+	return {
+		tokens: data.tokens?.[opts.server],
+		client: data.client?.[opts.server],
+		onTokensChanged: async (t) => {
+			const cur = await readSafe(opts.path);
+			cur.tokens = {
+				...cur.tokens ?? {},
+				[opts.server]: t
+			};
+			await writeSafe(opts.path, cur);
+		},
+		onClientRegistered: async (c) => {
+			const cur = await readSafe(opts.path);
+			cur.client = {
+				...cur.client ?? {},
+				[opts.server]: c
+			};
+			await writeSafe(opts.path, cur);
+		}
+	};
+}
+
+//#endregion
+//#region src/index.ts
+const VERSION = `0.1.0`;
+
+//#endregion
+exports.MCP_TOOLS_SENTINEL = MCP_TOOLS_SENTINEL
+exports.VERSION = VERSION
+exports.bridgeMcpTool = bridgeMcpTool
+exports.buildPromptTools = buildPromptTools
+exports.buildResourceTools = buildResourceTools
+exports.createRegistry = createRegistry
+exports.filePersistence = filePersistence
+exports.filterByAllowlist = filterByAllowlist
+exports.isMcpToolsSentinel = isMcpToolsSentinel
+exports.keychainPersistence = keychainPersistence
+exports.loadConfig = loadConfig
+exports.mcp = mcp
+exports.parseConfig = parseConfig
+exports.prefixToolName = prefixToolName
+exports.watchConfig = watchConfig