@alfe.ai/integrations 0.0.32 → 0.1.0

package/dist/index.d.ts

@@ -1,4 +1,8 @@
+import { IntegrationManifest, IntegrationStateEntry, IntegrationStatus, IntegrationsStateFile, McpServerDeclaration, PluginInstall, SkillInstall } from "@alfe.ai/integration-manifest";
+import { Manager } from "@alfe.ai/mcp-bundler";
+
 //#region src/registry.d.ts
+
 /**
  * Registry — fetches the integration registry index from the integrations service.
  *
@@ -216,187 +220,16 @@ declare class Installer {
   isInstalled(name: string): boolean;
 }
 //#endregion
-//#region ../integration-manifest/dist/index.d.ts
-//#region src/types.d.ts
-
-/**
- * TypeScript types for the Alfe integration manifest (`alfe-integration.yaml`).
- *
- * These are the canonical types used by all packages that interact with
- * integration manifests -- registry, lifecycle manager, CLI, etc.
- */
-type ConfigFieldType = 'secret' | 'string' | 'number' | 'boolean' | 'enum' | 'select' | 'multi_select' | 'oauth_connect';
-interface SelectOption {
-  value: string;
-  label: string;
-}
-interface ConfigSchemaField {
-  key: string;
-  type: ConfigFieldType;
-  label: string;
-  description?: string;
-  required: boolean;
-  default?: string | number | boolean;
-  /** Who can mutate this field at runtime. Default: 'admin' */
-  editable: 'admin' | 'agent';
-  /** Only used when type === 'enum' */
-  options?: string[];
-  /** Structured options for select/multi_select fields */
-  select_options?: SelectOption[];
-  /** OAuth provider identifier for oauth_connect fields */
-  oauth_provider?: string;
-  /** Force specific scope groups for OAuth (e.g. ["chat"]) — hides other scopes in the dashboard */
-  oauth_scopes?: string[];
-  /** Integration ID to patch on OAuth callback (when using a shared OAuth provider) */
-  oauth_integration_id?: string;
-  /** If true, this field is not shown in the dashboard UI (install wizard or configure modal) */
-  hidden?: boolean;
-  /** Only show this field if another field has a truthy value (string) or matches a specific value (object) */
-  depends_on_field?: string | {
-    key: string;
-    value: string | number | boolean;
-  };
-  /** Only show this field if a specific integration is installed */
-  depends_on_integration?: string;
-}
-interface McpServerDeclaration {
-  /** Unique identifier within this integration */
-  id: string;
-  /** Command to spawn (e.g., 'npx', 'node', 'xero-mcp-proxy') */
-  command: string;
-  /** Arguments for the command */
-  args?: string[];
-  /** Environment variables — supports {{config.KEY}} interpolation from config + secrets */
-  env?: Record<string, string>;
-  /** Working directory (optional) */
-  cwd?: string;
-  /** If true, applier skips auto-application — a lifecycle hook manages this MCP server instead */
-  hook_managed?: boolean;
-}
-interface CommandDeclaration {
-  /** Dot-namespaced command name (e.g. "support.diagnostic") */
-  name: string;
-  /** Relative path to handler file within integration directory */
-  handler: string;
-  /** Exported function name (default: "handle") */
-  method?: string;
-  /** Timeout in milliseconds (default: 30000) */
-  timeout_ms?: number;
-  /** Human-readable description */
-  description?: string;
-}
-interface SkillInstall {
-  /** Relative path within the integration repo to the skill directory */
-  path?: string;
-  /** ClawHub skill slug to install from the registry */
-  clawhub?: string;
-}
-interface PluginInstall {
-  /** npm package name to install */
-  package: string;
-}
-type AgentRuntime = 'openclaw' | 'nanoclaw' | (string & {});
-interface RuntimeInstall {
-  plugins?: PluginInstall[];
-  skills?: SkillInstall[];
-  /** Deep-merged into the runtime's agent config on activation */
-  config?: Record<string, unknown>;
-}
-interface InstallTargets {
-  /** Universal skills — applied to all runtimes */
-  skills?: SkillInstall[];
-  /** Universal plugins — applied to all runtimes */
-  plugins?: PluginInstall[];
-  /** Per-runtime installs */
-  runtimes?: Record<AgentRuntime, RuntimeInstall>;
-}
-interface IntegrationHooks {
-  pre_install?: string;
-  post_install?: string;
-  post_activate?: string;
-  pre_uninstall?: string;
-  post_uninstall?: string;
-  health_check?: string;
-}
-interface IntegrationPricingPlan {
-  name: string;
-  price: number;
-  currency?: string;
-  interval?: 'month' | 'year';
-}
-interface IntegrationPricing {
-  type: 'free' | 'paid' | 'usage';
-  /** Single price (shorthand for integrations with one plan) */
-  price?: number;
-  currency?: string;
-  interval?: 'month' | 'year';
-  /** Description of usage-based pricing (for type: 'usage') */
-  description?: string;
-  /** Multiple plans/tiers (e.g., starter, growth, scale) */
-  plans?: Record<string, IntegrationPricingPlan>;
-}
-interface IntegrationAuthor {
-  name: string;
-  url?: string;
-}
-interface IntegrationManifest {
-  id: string;
-  name: string;
-  version: string;
-  description: string;
-  /** Simple author string (legacy) or structured author object */
-  author: string | IntegrationAuthor;
-  license: string;
-  depends_on: string[];
-  min_gateway_version: string;
-  installs: InstallTargets;
-  config_schema: ConfigSchemaField[];
-  capabilities: string[];
-  hooks: IntegrationHooks;
-  commands: CommandDeclaration[];
-  /** MCP servers to configure in the agent runtime */
-  mcp_servers: McpServerDeclaration[];
-  /** Git repository URL (HTTPS) — not present in YAML, injected by the publish API */
-  repository?: string;
-  /**
-   * Agent runtimes this integration supports.
-   * If omitted or empty, the integration is considered universal (all runtimes).
-   * Example: ['openclaw'] means this integration only works with OpenClaw.
-   */
-  supported_agents?: AgentRuntime[];
-  /**
-   * Scopes where this integration can be installed.
-   * Default: ['agent'] (per-agent only).
-   * 'org' means it can be installed at the org level and cascades to all agents.
-   */
-  supported_scopes?: ('agent' | 'org')[];
-  /** Marketplace metadata */
-  publisherId?: string;
-  icon?: string;
-  pricing?: IntegrationPricing;
-  preview_images?: string[];
-  /** Long-form features list for the detail view */
-  features?: string[];
-}
-type IntegrationStatus = 'installing' | 'installed' | 'configured' | 'active' | 'error';
-interface IntegrationStateEntry {
-  status: IntegrationStatus;
-  version: string;
-  installedAt: string;
-  config: Record<string, unknown>;
-  error?: string;
-  /** Number of consecutive auto-reinstall attempts. Reset on success or explicit reinstall. */
-  reinstallAttempts?: number;
-}
-interface IntegrationsStateFile {
-  version: number;
-  integrations: Record<string, IntegrationStateEntry>;
-}
-//#endregion
 //#region src/runtime-applier.d.ts
 /**
  * RuntimeApplier — interface for applying/removing plugins and skills
  * to a specific agent runtime (OpenClaw, NanoClaw, etc.).
+ *
+ * Note: MCP server registration is NOT here — it moved to the
+ * runtime-agnostic `McpApplier` (`appliers/mcp-applier.ts`) which
+ * writes via the bundler manager + openclaw.json mirror. Removing
+ * the per-runtime `applyMcpServers` / `removeMcpServers` was part of
+ * the bundler-as-primitive cleanup (see `project_mcp_tool_lift_workstream`).
  */
 interface RuntimeApplier {
   /** The runtime identifier (e.g. 'openclaw', 'nanoclaw') */
@@ -419,14 +252,65 @@ interface RuntimeApplier {
   applyConfig(integrationId: string, config: Record<string, unknown>): Promise<void>;
   /** Remove config previously applied by an integration */
   removeConfig(integrationId: string): Promise<void>;
-  /** Configure MCP servers in this runtime */
-  applyMcpServers(integrationId: string, servers: McpServerDeclaration[]): Promise<void>;
-  /** Remove MCP servers previously applied by an integration */
-  removeMcpServers(integrationId: string): Promise<void>;
   /** Check if this runtime is available (e.g. workspace directory exists) */
   isAvailable(): Promise<boolean>;
 }
 //#endregion
+//#region src/appliers/mcp-applier.d.ts
+/**
+ * Minimal contract the applier needs from the agent API client.
+ * Wider than a single typed method so callers don't have to depend on
+ * the exact `AgentApiClient` shape — particularly handy for tests and
+ * for the eventual `getCredentials(provider)` generalisation.
+ */
+interface CredentialsResolver {
+  getCredentials: (provider: string) => Promise<Record<string, unknown> | undefined>;
+}
+/**
+ * Daemon-level platform context exposed to `{{alfe.<key>}}` env
+ * interpolation. Reserved namespace so manifests can reference things
+ * like the agent's cloud apiUrl (for OAuth redirect URIs) without
+ * colliding with user-supplied `{{config.<key>}}`.
+ */
+interface PlatformContext {
+  /** The agent's cloud apiUrl (e.g. https://api.alfe.ai). */
+  apiUrl?: string;
+}
+interface McpApplierOptions {
+  manager: Manager;
+  credentials: CredentialsResolver;
+  /** Optional — when omitted, `{{alfe.X}}` references are left as-is. */
+  platform?: PlatformContext;
+}
+declare class McpApplier {
+  private readonly manager;
+  private readonly credentials;
+  private readonly platform;
+  constructor(opts: McpApplierOptions);
+  /**
+   * Register every server declared by an integration. Idempotent —
+   * re-running for the same integration overwrites entries in place
+   * (the manager preserves `addedAt`). Returns the list of ids that
+   * actually landed in the store.
+   *
+   * Awaits `manager.flush()` before returning so the openclaw.json
+   * mirror write has fired by the time the caller proceeds. Without
+   * this, an integration activation's success ack would race ahead of
+   * the runtime's openclaw.json update — the cloud would see
+   * `actual.status = active` while OpenClaw still has the stale MCP
+   * set in memory, violating the actual-status protocol contract.
+   */
+  applyForIntegration(integrationId: string, servers: McpServerDeclaration[], mergedConfig: Record<string, unknown>): Promise<string[]>;
+  /**
+   * Drop every entry owned by this integration. Like `applyForIntegration`,
+   * awaits the mirror flush so the runtime is signalled before the call
+   * resolves — the uninstall ack shouldn't outrun openclaw.json being
+   * cleaned up.
+   */
+  removeForIntegration(integrationId: string): Promise<string[]>;
+  private resolveEnv;
+}
+//#endregion
 //#region src/types.d.ts
 /**
  * Integration command parameter types.
@@ -462,6 +346,15 @@ interface IntegrationManagerOptions {
   lockPath?: string;
   /** Fetcher for the integration registry — should be wired to api-client */
   registryFetcher: RegistryFetcher;
+  /**
+   * Runtime-agnostic MCP server applier. The manager routes
+   * `mcp_servers` declarations through it once per integration (the
+   * applier writes to the bundler store + openclaw.json mirror).
+   * Required — there is no fallback path; integrations with
+   * `mcp_servers` will skip MCP registration silently if this is
+   * omitted (the warn log makes this visible).
+   */
+  mcpApplier?: McpApplier;
 }
 interface ManagerResponse {
   ok: boolean;
@@ -496,6 +389,7 @@ declare class IntegrationManager {
   private installer;
   private runtimeAppliers;
   private lockManager;
+  private mcpApplier;
   /** In-memory secret store — NEVER persisted to disk */
   private secrets;
   constructor(options: IntegrationManagerOptions);
@@ -825,20 +719,6 @@ declare class OpenClawApplier implements RuntimeApplier {
    * then removes them via `openclaw config unset`.
    */
   removeConfig(integrationId: string): Promise<void>;
-  /**
-   * Configure MCP servers in OpenClaw via `openclaw config set --batch-json`.
-   *
-   * Each server is written as `mcp.servers.{integrationId}-{serverId}.*`.
-   * Applied servers are tracked in the tracking file for clean removal.
-   */
-  applyMcpServers(integrationId: string, servers: McpServerDeclaration[]): Promise<void>;
-  /**
-   * Remove MCP servers previously applied by an integration.
-   *
-   * Reads the tracking file to find which `mcp.servers.*` keys this integration set,
-   * then removes them via `openclaw config unset`.
-   */
-  removeMcpServers(integrationId: string): Promise<void>;
   isAvailable(): Promise<boolean>;
   private readTracking;
   private writeTracking;
@@ -954,4 +834,4 @@ declare class IntegrationManagerAdapter implements IIntegrationManager {
   resetReinstallAttempts(integrationId: string): void;
 }
 //#endregion
-export { type HookEnvOptions, type HookResult, type IIntegrationManager, type InstalledInfo, Installer, InstallerError, type IntegrationConfigureParams, type IntegrationHealthParams, type IntegrationInfo, type IntegrationInstallParams, IntegrationManager, IntegrationManagerAdapter, type IntegrationManagerOptions, type IntegrationRemoveParams, LockManager, OpenClawApplier, type OpenClawApplierOptions, Registry, type RegistryEntry, type RegistryFetcher, type RegistryIndex, RegistryResolveError, type ResolvedIntegration, Resolver, type RuntimeApplier, type RuntimeDesiredState, type RuntimeLockFile, type RuntimePluginEntry, type RuntimeSkillEntry, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext };
+export { type CredentialsResolver, type HookEnvOptions, type HookResult, type IIntegrationManager, type InstalledInfo, Installer, InstallerError, type IntegrationConfigureParams, type IntegrationHealthParams, type IntegrationInfo, type IntegrationInstallParams, IntegrationManager, IntegrationManagerAdapter, type IntegrationManagerOptions, type IntegrationRemoveParams, LockManager, McpApplier, type McpApplierOptions, OpenClawApplier, type OpenClawApplierOptions, type PlatformContext, Registry, type RegistryEntry, type RegistryFetcher, type RegistryIndex, RegistryResolveError, type ResolvedIntegration, Resolver, type RuntimeApplier, type RuntimeDesiredState, type RuntimeLockFile, type RuntimePluginEntry, type RuntimeSkillEntry, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext };

package/dist/index.js

@@ -130,7 +130,7 @@ var Resolver = class {
 * can resolve them via Node's upward module resolution.
 */
 const execFileAsync$1 = promisify(execFile);
-const log$1 = createLogger("Installer");
+const log$2 = createLogger("Installer");
 const INTEGRATIONS_DIR = join(homedir(), ".alfe", "integrations");
 const GIT_TIMEOUT_MS = 6e4;
 const NPM_TIMEOUT_MS = 6e4;
@@ -292,7 +292,7 @@ var Installer = class {
 			dependencies: { ...SHARED_PACKAGES }
 		};
 		writeFileSync(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + "\n", "utf-8");
-		log$1.info("Installing shared @alfe.ai packages for integration hooks");
+		log$2.info("Installing shared @alfe.ai packages for integration hooks");
 		await this.runNpmInstall(this.basePath);
 		this.sharedPackagesReady = true;
 	}
@@ -302,7 +302,7 @@ var Installer = class {
 	*/
 	async installLocalDependencies(installPath) {
 		if (!existsSync(join(installPath, "package.json"))) return;
-		log$1.info({ path: installPath }, "Installing integration-specific npm dependencies");
+		log$2.info({ path: installPath }, "Installing integration-specific npm dependencies");
 		await this.runNpmInstall(installPath);
 	}
 	async runNpmInstall(cwd) {
@@ -811,35 +811,30 @@ async function runHookWithContext(integrationPath, hookScript, options) {
 * Deep-walk an object and replace `{{config.KEY}}` patterns with values
 * from the per-agent config. Used to compose manifest runtime config
 * with per-agent secrets (e.g., gateway token).
+*
+* Whole-value substitution: when a string is exactly `{{config.KEY}}` with
+* no surrounding text, the raw config value is substituted preserving its
+* type (array, object, boolean, …). For interpolation inside a larger
+* string, only string/number values are substituted; other types fall
+* through to keep the placeholder.
 */
+const FULL_PLACEHOLDER = /^\{\{config\.([a-zA-Z0-9_]+)\}\}$/;
 function interpolateSelfConfig(obj, config) {
 	const result = {};
-	for (const [key, value] of Object.entries(obj)) if (typeof value === "string") result[key] = value.replace(/\{\{config\.([a-zA-Z0-9_]+)\}\}/g, (_match, configKey) => {
-		const val = config[configKey];
-		return typeof val === "string" || typeof val === "number" ? String(val) : _match;
-	});
-	else if (value && typeof value === "object" && !Array.isArray(value)) result[key] = interpolateSelfConfig(value, config);
-	else result[key] = value;
-	return result;
-}
-/**
-* Interpolate `{{config.KEY}}` patterns in MCP server env vars using
-* the merged config + secrets dict. Returns new declarations with
-* interpolated env values; skips hook_managed servers.
-*/
-function interpolateMcpServerEnvs(servers, mergedConfig) {
-	return servers.filter((s) => !s.hook_managed).map((server) => {
-		if (!server.env) return server;
-		const interpolatedEnv = {};
-		for (const [key, value] of Object.entries(server.env)) interpolatedEnv[key] = value.replace(/\{\{config\.([a-zA-Z0-9_]+)\}\}/g, (_match, configKey) => {
-			const val = mergedConfig[configKey];
+	for (const [key, value] of Object.entries(obj)) if (typeof value === "string") {
+		const wholeMatch = FULL_PLACEHOLDER.exec(value);
+		if (wholeMatch) {
+			const raw = config[wholeMatch[1]];
+			result[key] = raw !== void 0 ? raw : value;
+			continue;
+		}
+		result[key] = value.replace(/\{\{config\.([a-zA-Z0-9_]+)\}\}/g, (_match, configKey) => {
+			const val = config[configKey];
 			return typeof val === "string" || typeof val === "number" ? String(val) : _match;
 		});
-		return {
-			...server,
-			env: interpolatedEnv
-		};
-	});
+	} else if (value && typeof value === "object" && !Array.isArray(value)) result[key] = interpolateSelfConfig(value, config);
+	else result[key] = value;
+	return result;
 }
 /**
 * Merge universal installs with runtime-specific installs from the manifest.
@@ -861,6 +856,7 @@ var IntegrationManager = class {
 	installer;
 	runtimeAppliers;
 	lockManager;
+	mcpApplier;
 	/** In-memory secret store — NEVER persisted to disk */
 	secrets = /* @__PURE__ */ new Map();
 	constructor(options) {
@@ -870,6 +866,7 @@ var IntegrationManager = class {
 		this.installer = new Installer(options.integrationsDir);
 		this.runtimeAppliers = options.runtimeAppliers ?? /* @__PURE__ */ new Map();
 		this.lockManager = new LockManager(options.lockPath);
+		this.mcpApplier = options.mcpApplier;
 	}
 	/**
 	* Install an integration from the registry.
@@ -1088,22 +1085,20 @@ var IntegrationManager = class {
 					await applier.applyConfig(integrationId, interpolatedConfig);
 					configApplied = true;
 				}
-				const mcpServers = manifest.mcp_servers ?? [];
-				if (mcpServers.length > 0) {
-					const secretEntries = this.secrets.get(integrationId);
-					const interpolatedServers = interpolateMcpServerEnvs(mcpServers, {
-						...entry.config,
-						...secretEntries ? Object.fromEntries(secretEntries) : {}
-					});
-					if (interpolatedServers.length > 0) {
-						this.log.info(`Applying ${String(interpolatedServers.length)} MCP server(s) for ${integrationId} to ${runtimeName}`);
-						await applier.applyMcpServers(integrationId, interpolatedServers);
-						configApplied = true;
-					}
-				}
 				const appliedPlugins = plugins.filter((p) => !pluginFailures.includes(p.package));
 				if (appliedPlugins.length > 0 || skills.length > 0) this.lockManager.addEntries(runtimeName, integrationId, manifest.version, appliedPlugins, skills, installPath);
 			}
+			const mcpServers = manifest.mcp_servers ?? [];
+			if (mcpServers.length > 0) if (!this.mcpApplier) this.log.warn(`Integration "${integrationId}" declares ${String(mcpServers.length)} mcp_server(s) but no mcpApplier is wired — skipping MCP registration`);
+			else {
+				const secretEntries = this.secrets.get(integrationId);
+				const mergedConfig = {
+					...entry.config,
+					...secretEntries ? Object.fromEntries(secretEntries) : {}
+				};
+				this.log.info(`Applying ${String(mcpServers.length)} MCP server(s) for ${integrationId} via bundler manager`);
+				await this.mcpApplier.applyForIntegration(integrationId, mcpServers, mergedConfig);
+			}
 			this.state.setStatus(integrationId, "active");
 			if (manifest.hooks.post_activate) {
 				this.log.info(`Running post_activate hook: ${manifest.hooks.post_activate}`);
@@ -1201,13 +1196,12 @@ var IntegrationManager = class {
 					this.log.warn(`Failed to remove config for ${integrationId} from ${runtimeName}: ${err instanceof Error ? err.message : String(err)}`);
 				}
 			}
-			for (const [runtimeName, applier] of this.runtimeAppliers) {
-				if (!await applier.isAvailable()) continue;
-				this.log.info(`Removing MCP servers for ${integrationId} from ${runtimeName}`);
+			if (this.mcpApplier) {
+				this.log.info(`Removing MCP servers for ${integrationId} via bundler manager`);
 				try {
-					await applier.removeMcpServers(integrationId);
+					await this.mcpApplier.removeForIntegration(integrationId);
 				} catch (err) {
-					this.log.warn(`Failed to remove MCP servers for ${integrationId} from ${runtimeName}: ${err instanceof Error ? err.message : String(err)}`);
+					this.log.warn(`Failed to remove MCP servers for ${integrationId} via bundler manager: ${err instanceof Error ? err.message : String(err)}`);
 				}
 			}
 			this.state.setStatus(integrationId, "configured");
@@ -1507,7 +1501,7 @@ var IntegrationManager = class {
 * is stored in a separate tracking file (config.json) for clean removal.
 */
 const execFileAsync = promisify(execFile);
-const log = createLogger("OpenClawApplier");
+const log$1 = createLogger("OpenClawApplier");
 const DEFAULT_SKILLS_DIR = join(homedir(), ".alfe", "skills");
 function flattenConfig(obj, prefix = "") {
 	const entries = [];
@@ -1585,11 +1579,11 @@ var OpenClawApplier = class {
 		await this.ensurePluginsAllow(pkg);
 		this.cleanupUntrackedExtensionInstall(pkg);
 		if (opts?.force && this.isPluginInstalled(pkg)) {
-			log.info({ pkg }, "Force mode — uninstalling plugin before reinstall");
+			log$1.info({ pkg }, "Force mode — uninstalling plugin before reinstall");
 			try {
 				await this.removePlugin(pkg);
 			} catch (err) {
-				log.warn({
+				log$1.warn({
 					pkg,
 					err: err instanceof Error ? err.message : String(err)
 				}, "Failed to uninstall plugin during force reinstall — proceeding");
@@ -1610,7 +1604,7 @@ var OpenClawApplier = class {
 				} catch (err) {
 					const errText = err instanceof Error ? `${err.message}\n${err.stderr ?? ""}` : String(err);
 					if (useUnsafeFlag && errText.includes("unknown option")) {
-						log.info({ pkg }, "OpenClaw does not support --dangerously-force-unsafe-install, retrying without");
+						log$1.info({ pkg }, "OpenClaw does not support --dangerously-force-unsafe-install, retrying without");
 						await execFileAsync("openclaw", baseArgs, { timeout: 6e4 });
 					} else throw err;
 				}
@@ -1619,7 +1613,7 @@ var OpenClawApplier = class {
 					setTimeout(r, 500);
 				});
 				if (!this.isPluginInstalled(pkg)) throw err;
-				log.warn({
+				log$1.warn({
 					pkg,
 					err: err instanceof Error ? err.message : String(err)
 				}, "openclaw plugins install exited with warnings but plugin is installed");
@@ -1654,7 +1648,7 @@ var OpenClawApplier = class {
 				JSON.stringify(updated)
 			], { timeout: 1e4 });
 		} catch (err) {
-			log.warn({
+			log$1.warn({
 				err: err instanceof Error ? err.message : String(err),
 				pkg
 			}, "Failed to set plugins.allow via openclaw config set");
@@ -1707,12 +1701,12 @@ var OpenClawApplier = class {
 					recursive: true,
 					force: true
 				});
-				log.info({
+				log$1.info({
 					pkg,
 					removed: fullPath
 				}, "Removed untracked extensions/ install — will reinstall via npm path");
 			} catch (err) {
-				log.warn({
+				log$1.warn({
 					pkg,
 					removed: fullPath,
 					err: err instanceof Error ? err.message : String(err)
@@ -1735,21 +1729,21 @@ var OpenClawApplier = class {
 		return Promise.resolve();
 	}
 	async applyClawHubSkill(slug) {
-		log.info({ slug }, "Installing skill from ClawHub");
+		log$1.info({ slug }, "Installing skill from ClawHub");
 		try {
 			await execFileAsync("openclaw", [
 				"skills",
 				"install",
 				slug
 			], { timeout: 6e4 });
-			log.info({ slug }, "ClawHub skill installed");
+			log$1.info({ slug }, "ClawHub skill installed");
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			if (msg.includes("already exists") || msg.includes("Skill already exists")) {
-				log.info({ slug }, "ClawHub skill already installed (skipped)");
+				log$1.info({ slug }, "ClawHub skill already installed (skipped)");
 				return;
 			}
-			log.error({
+			log$1.error({
 				slug,
 				err: msg
 			}, "ClawHub skill install failed");
@@ -1762,7 +1756,7 @@ var OpenClawApplier = class {
 				recursive: true,
 				force: true
 			});
-			log.info({ slug }, "ClawHub skill removed");
+			log$1.info({ slug }, "ClawHub skill removed");
 		}
 		return Promise.resolve();
 	}
@@ -1798,7 +1792,7 @@ var OpenClawApplier = class {
 					JSON.stringify(merged)
 				], { timeout: 1e4 });
 			} catch (err) {
-				log.error({
+				log$1.error({
 					err: err instanceof Error ? err.message : String(err),
 					parentPath
 				}, "Failed to set config subtree via openclaw config set");
@@ -1813,7 +1807,7 @@ var OpenClawApplier = class {
 				JSON.stringify(leaves)
 			], { timeout: 1e4 });
 		} catch (err) {
-			log.error({
+			log$1.error({
 				err: err instanceof Error ? err.message : String(err),
 				batch: leaves
 			}, "Failed to set config via openclaw config set --batch-json");
@@ -1839,7 +1833,7 @@ var OpenClawApplier = class {
 				path
 			], { timeout: 1e4 });
 		} catch (err) {
-			log.warn({
+			log$1.warn({
 				err: err instanceof Error ? err.message : String(err),
 				path
 			}, "Failed to unset config via openclaw config unset");
@@ -1861,7 +1855,7 @@ var OpenClawApplier = class {
 					JSON.stringify(remaining)
 				], { timeout: 1e4 });
 			} catch (err) {
-				log.warn({
+				log$1.warn({
 					err: err instanceof Error ? err.message : String(err),
 					parentPath
 				}, "Failed to update parent config during remove");
@@ -1870,82 +1864,6 @@ var OpenClawApplier = class {
 		tracking._integrations = Object.fromEntries(Object.entries(integrations).filter(([key]) => key !== integrationId));
 		this.writeTracking(tracking);
 	}
-	/**
-	* Configure MCP servers in OpenClaw via `openclaw config set --batch-json`.
-	*
-	* Each server is written as `mcp.servers.{integrationId}-{serverId}.*`.
-	* Applied servers are tracked in the tracking file for clean removal.
-	*/
-	async applyMcpServers(integrationId, servers) {
-		if (servers.length === 0) return;
-		const batch = [];
-		const trackedKeys = [];
-		for (const server of servers) {
-			const prefix = `mcp.servers.${`${integrationId}-${server.id}`}`;
-			batch.push({
-				path: `${prefix}.command`,
-				value: server.command
-			});
-			if (server.args && server.args.length > 0) batch.push({
-				path: `${prefix}.args`,
-				value: server.args
-			});
-			if (server.env) for (const [envKey, envVal] of Object.entries(server.env)) batch.push({
-				path: `${prefix}.env.${envKey}`,
-				value: envVal
-			});
-			if (server.cwd) batch.push({
-				path: `${prefix}.cwd`,
-				value: server.cwd
-			});
-			trackedKeys.push(prefix);
-		}
-		try {
-			await execFileAsync("openclaw", [
-				"config",
-				"set",
-				"--batch-json",
-				JSON.stringify(batch)
-			], { timeout: 1e4 });
-		} catch (err) {
-			log.error({
-				err: err instanceof Error ? err.message : String(err),
-				batch
-			}, "Failed to set MCP server config via openclaw config set --batch-json");
-			throw err;
-		}
-		const tracking = this.readTracking();
-		const mcpTracking = tracking._mcpServers ?? {};
-		mcpTracking[integrationId] = trackedKeys;
-		tracking._mcpServers = mcpTracking;
-		this.writeTracking(tracking);
-	}
-	/**
-	* Remove MCP servers previously applied by an integration.
-	*
-	* Reads the tracking file to find which `mcp.servers.*` keys this integration set,
-	* then removes them via `openclaw config unset`.
-	*/
-	async removeMcpServers(integrationId) {
-		const tracking = this.readTracking();
-		const mcpTracking = tracking._mcpServers ?? {};
-		if (!(integrationId in mcpTracking)) return;
-		const prefixes = mcpTracking[integrationId];
-		for (const prefix of prefixes) try {
-			await execFileAsync("openclaw", [
-				"config",
-				"unset",
-				prefix
-			], { timeout: 1e4 });
-		} catch (err) {
-			log.warn({
-				err: err instanceof Error ? err.message : String(err),
-				prefix
-			}, "Failed to unset MCP server config via openclaw config unset");
-		}
-		tracking._mcpServers = Object.fromEntries(Object.entries(mcpTracking).filter(([key]) => key !== integrationId));
-		this.writeTracking(tracking);
-	}
 	isAvailable() {
 		return Promise.resolve(existsSync(this.home));
 	}
@@ -1963,6 +1881,128 @@ var OpenClawApplier = class {
 	}
 };
 //#endregion
+//#region src/appliers/mcp-applier.ts
+const log = createLogger("McpApplier");
+const CONFIG_TEMPLATE_RE = /\{\{config\.([a-zA-Z0-9_]+)\}\}/g;
+const CREDENTIALS_TEMPLATE_RE = /\{\{credentials\.([a-z0-9-]+)\.([a-zA-Z0-9_]+)\}\}/g;
+const ALFE_TEMPLATE_RE = /\{\{alfe\.([a-zA-Z0-9_]+)\}\}/g;
+var McpApplier = class {
+	manager;
+	credentials;
+	platform;
+	constructor(opts) {
+		this.manager = opts.manager;
+		this.credentials = opts.credentials;
+		this.platform = opts.platform ?? {};
+	}
+	/**
+	* Register every server declared by an integration. Idempotent —
+	* re-running for the same integration overwrites entries in place
+	* (the manager preserves `addedAt`). Returns the list of ids that
+	* actually landed in the store.
+	*
+	* Awaits `manager.flush()` before returning so the openclaw.json
+	* mirror write has fired by the time the caller proceeds. Without
+	* this, an integration activation's success ack would race ahead of
+	* the runtime's openclaw.json update — the cloud would see
+	* `actual.status = active` while OpenClaw still has the stale MCP
+	* set in memory, violating the actual-status protocol contract.
+	*/
+	async applyForIntegration(integrationId, servers, mergedConfig) {
+		const owner = `integration:${integrationId}`;
+		const applied = [];
+		for (const server of servers) {
+			const id = `${integrationId}-${server.id}`;
+			const envResolved = await this.resolveEnv(server, mergedConfig);
+			if (envResolved == null) {
+				log.info({
+					integrationId,
+					server: server.id,
+					provider: server.requires_credentials
+				}, "Skipping MCP server registration — required credentials missing or fetch failed");
+				continue;
+			}
+			await this.manager.addServer(toBundlerConfig(server, envResolved), {
+				id,
+				owner
+			});
+			applied.push(id);
+		}
+		await this.manager.flush();
+		return applied;
+	}
+	/**
+	* Drop every entry owned by this integration. Like `applyForIntegration`,
+	* awaits the mirror flush so the runtime is signalled before the call
+	* resolves — the uninstall ack shouldn't outrun openclaw.json being
+	* cleaned up.
+	*/
+	async removeForIntegration(integrationId) {
+		const owner = `integration:${integrationId}`;
+		const removed = await this.manager.removeServersByOwner(owner);
+		await this.manager.flush();
+		return removed;
+	}
+	async resolveEnv(server, mergedConfig) {
+		if (!server.env || Object.keys(server.env).length === 0) return {};
+		const needsCredentials = server.requires_credentials;
+		let credentialsCache;
+		if (needsCredentials) {
+			try {
+				credentialsCache = await this.credentials.getCredentials(needsCredentials);
+			} catch (err) {
+				log.warn({
+					err: errMsg(err),
+					provider: needsCredentials
+				}, "Credentials fetch threw — skipping MCP registration");
+				return null;
+			}
+			if (!credentialsCache || Object.keys(credentialsCache).length === 0) return null;
+		}
+		const resolved = {};
+		for (const [key, value] of Object.entries(server.env)) {
+			const interpolated = interpolateString(value, mergedConfig, credentialsCache, this.platform);
+			if (needsCredentials && hasCredentialsPlaceholder(interpolated)) {
+				log.warn({
+					provider: needsCredentials,
+					key
+				}, "Credentials interpolation left a placeholder — skipping MCP registration");
+				return null;
+			}
+			resolved[key] = interpolated;
+		}
+		return resolved;
+	}
+};
+function hasCredentialsPlaceholder(value) {
+	return /\{\{credentials\.[a-z0-9-]+\.[a-zA-Z0-9_]+\}\}/.test(value);
+}
+function interpolateString(value, mergedConfig, credentials, platform) {
+	let next = value.replace(CONFIG_TEMPLATE_RE, (match, configKey) => {
+		const v = mergedConfig[configKey];
+		return typeof v === "string" || typeof v === "number" ? String(v) : match;
+	});
+	if (credentials) next = next.replace(CREDENTIALS_TEMPLATE_RE, (match, _provider, field) => {
+		const v = credentials[field];
+		return typeof v === "string" || typeof v === "number" ? String(v) : match;
+	});
+	next = next.replace(ALFE_TEMPLATE_RE, (match, platformKey) => {
+		const v = platform[platformKey];
+		return typeof v === "string" || typeof v === "number" ? String(v) : match;
+	});
+	return next;
+}
+function toBundlerConfig(server, resolvedEnv) {
+	const cfg = { command: server.command };
+	if (server.args && server.args.length > 0) cfg.args = server.args;
+	if (Object.keys(resolvedEnv).length > 0) cfg.env = resolvedEnv;
+	if (server.cwd) cfg.cwd = server.cwd;
+	return cfg;
+}
+function errMsg(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
 //#region src/adapter.ts
 var IntegrationManagerAdapter = class {
 	constructor(manager) {
@@ -2021,4 +2061,4 @@ var IntegrationManagerAdapter = class {
 	}
 };
 //#endregion
-export { Installer, InstallerError, IntegrationManager, IntegrationManagerAdapter, LockManager, OpenClawApplier, Registry, RegistryResolveError, Resolver, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext };
+export { Installer, InstallerError, IntegrationManager, IntegrationManagerAdapter, LockManager, McpApplier, OpenClawApplier, Registry, RegistryResolveError, Resolver, StateManager, buildHookEnv, resolveInstallsForRuntime, runHook, runHookWithContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/integrations",
-  "version": "0.0.32",
+  "version": "0.1.0",
   "description": "Integration lifecycle management for Alfe — registry, resolution, installation, and state",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,7 +13,8 @@
   },
   "dependencies": {
     "@auriclabs/logger": "^0.1.1",
-    "@alfe.ai/integration-manifest": "^0.0.11"
+    "@alfe.ai/integration-manifest": "^0.1.0",
+    "@alfe.ai/mcp-bundler": "^0.1.0"
   },
   "files": [
     "dist"