@alfe.ai/integrations 0.0.24 → 0.0.25

package/dist/index.d.ts

@@ -248,6 +248,20 @@ interface ConfigSchemaField {
   /** 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;
@@ -329,6 +343,8 @@ interface IntegrationManifest {
   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;
   /**
@@ -388,6 +404,10 @@ 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>;
 }
@@ -738,6 +758,20 @@ 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;

package/dist/index.js

@@ -808,6 +808,25 @@ function interpolateSelfConfig(obj, config) {
 	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];
+			return typeof val === "string" || typeof val === "number" ? String(val) : _match;
+		});
+		return {
+			...server,
+			env: interpolatedEnv
+		};
+	});
+}
+/**
 * Merge universal installs with runtime-specific installs from the manifest.
 */
 function resolveInstallsForRuntime(manifest, runtime) {
@@ -1045,6 +1064,19 @@ 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;
+					}
+				}
 				if (plugins.length > 0 || skills.length > 0) this.lockManager.addEntries(runtimeName, integrationId, manifest.version, plugins, skills, installPath);
 			}
 			this.state.setStatus(integrationId, "active");
@@ -1143,6 +1175,15 @@ 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}`);
+				try {
+					await applier.removeMcpServers(integrationId);
+				} catch (err) {
+					this.log.warn(`Failed to remove MCP servers for ${integrationId} from ${runtimeName}: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			}
 			this.state.setStatus(integrationId, "configured");
 			return {
 				ok: true,
@@ -1456,8 +1497,21 @@ var OpenClawApplier = class {
 					"install",
 					pkg
 				];
-				if (pkg.startsWith("@alfe.ai/")) args.push("--dangerously-force-unsafe-install");
-				await execFileAsync("openclaw", args, { timeout: 6e4 });
+				const useUnsafeFlag = pkg.startsWith("@alfe.ai/");
+				if (useUnsafeFlag) args.push("--dangerously-force-unsafe-install");
+				try {
+					await execFileAsync("openclaw", args, { timeout: 6e4 });
+				} 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");
+						await execFileAsync("openclaw", [
+							"plugins",
+							"install",
+							pkg
+						], { timeout: 6e4 });
+					} else throw err;
+				}
 			} catch (err) {
 				await new Promise((r) => {
 					setTimeout(r, 500);
@@ -1624,6 +1678,83 @@ 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),
+				"--strict-json"
+			], { 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.workspace));
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/integrations",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "description": "Integration lifecycle management for Alfe — registry, resolution, installation, and state",
   "type": "module",
   "main": "./dist/index.js",