feat(config): add MCP initialization config handling and prioritization (#12)

Introduce a handler extracting configuration from MCP client info during
initialization, enabling dynamic config setup based on client-provided
data.

Update configuration loader to prioritize MCP init config over
environment variables and other sources, ensuring runtime flexibility
and seamless integration with MCP clients.

Add comprehensive tests verifying MCP config precedence, boolean
parsing, nested config handling, and hostname extraction.

Fixes #7

Author: AbdallahAHO

src/index.ts

@@ -53,6 +53,9 @@ export async function startServer(
 			title: "Lokalise MCP Server",
 		});
 
+		// Set up MCP initialization handler to extract configuration
+		setupMcpInitializationHandler(serverInstance);
+
 		serverLogger.info("Registering MCP tools, resources, and prompts...");
 		await registerAllTools(serverInstance);
 		await registerAllResources(serverInstance);
@@ -219,3 +222,56 @@ function setupGracefulShutdown() {
 		});
 	});
 }
+
+/**
+ * Set up MCP initialization handler to extract configuration from clientInfo
+ */
+function setupMcpInitializationHandler(server: McpServer): void {
+	const initLogger = Logger.forContext(
+		"index.ts",
+		"setupMcpInitializationHandler",
+	);
+
+	// Store the original oninitialized callback
+	const originalOnInitialized = server.server.oninitialized;
+
+	// Set up a custom oninitialized callback to extract configuration
+	server.server.oninitialized = () => {
+		initLogger.debug("MCP initialization completed");
+
+		// Try to extract configuration from the client info
+		const clientVersion = server.server.getClientVersion();
+		if (clientVersion && typeof clientVersion === "object") {
+			// Look for configuration in clientInfo - Smithery typically passes config here
+			const configData: Record<string, unknown> = {};
+
+			// Extract all non-standard fields from clientInfo as potential config
+			for (const [key, value] of Object.entries(clientVersion)) {
+				if (!["name", "version", "title"].includes(key)) {
+					configData[key] = value;
+				}
+			}
+
+			// Also check for explicit config object
+			if (
+				"config" in clientVersion &&
+				typeof clientVersion.config === "object" &&
+				clientVersion.config
+			) {
+				Object.assign(configData, clientVersion.config);
+			}
+
+			if (Object.keys(configData).length > 0) {
+				initLogger.info("Extracted configuration from MCP initialization", {
+					configKeys: Object.keys(configData),
+				});
+				config.setMcpInitConfig(configData);
+			}
+		}
+
+		// Call the original callback if it existed
+		if (originalOnInitialized) {
+			originalOnInitialized();
+		}
+	};
+}

src/shared/utils/config-mcp-init.test.ts

@@ -0,0 +1,98 @@
+import { beforeEach, describe, expect, test } from "@jest/globals";
+import { config } from "./config.util.js";
+
+describe("ConfigLoader MCP Initialization", () => {
+	beforeEach(() => {
+		// Reset the config instance for each test
+		// biome-ignore lint/suspicious/noExplicitAny: Needed for testing private properties
+		(config as any).configLoaded = false;
+		// biome-ignore lint/suspicious/noExplicitAny: Needed for testing private properties
+		(config as any).mcpInitConfig = {};
+
+		// Clear any environment variables that might interfere
+		delete process.env.TEST_KEY;
+		delete process.env.LOKALISE_API_KEY;
+	});
+
+	test("should prioritize MCP init config over environment variables", () => {
+		// Set up environment variable
+		process.env.TEST_KEY = "env_value";
+
+		// Set up MCP init config (should have higher priority)
+		config.setMcpInitConfig({ TEST_KEY: "mcp_value" });
+
+		// Load config from all sources
+		config.load();
+
+		// MCP config should take precedence
+		expect(config.get("TEST_KEY")).toBe("mcp_value");
+	});
+
+	test("should fall back to environment variables when MCP config is not set", () => {
+		// Set up environment variable
+		process.env.TEST_KEY = "env_value";
+
+		// Don't set MCP config for this key
+		config.setMcpInitConfig({});
+
+		// Load config from all sources
+		config.load();
+
+		// Should fall back to environment variable
+		expect(config.get("TEST_KEY")).toBe("env_value");
+	});
+
+	test("should return default value when key is not found in any source", () => {
+		// Don't set the key anywhere
+		config.setMcpInitConfig({});
+		config.load();
+
+		// Should return the default value
+		expect(config.get("NONEXISTENT_KEY", "default_value")).toBe(
+			"default_value",
+		);
+	});
+
+	test("should handle boolean values from MCP config", () => {
+		// Set up MCP init config with boolean-like values
+		config.setMcpInitConfig({
+			BOOL_TRUE: "true",
+			BOOL_FALSE: "false",
+			BOOL_INVALID: "invalid",
+		});
+
+		config.load();
+
+		expect(config.getBoolean("BOOL_TRUE")).toBe(true);
+		expect(config.getBoolean("BOOL_FALSE")).toBe(false);
+		expect(config.getBoolean("BOOL_INVALID")).toBe(false);
+	});
+
+	test("should handle nested config object in MCP init", () => {
+		// Simulate what Smithery might pass
+		const mcpConfig = {
+			LOKALISE_API_KEY: "test_api_key",
+			LOKALISE_API_HOSTNAME: "https://api.example.com/api2/",
+			DEBUG: "true",
+		};
+
+		config.setMcpInitConfig(mcpConfig);
+		config.load();
+
+		expect(config.get("LOKALISE_API_KEY")).toBe("test_api_key");
+		expect(config.get("LOKALISE_API_HOSTNAME")).toBe(
+			"https://api.example.com/api2/",
+		);
+		expect(config.getBoolean("DEBUG")).toBe(true);
+	});
+
+	test("should extract hostname correctly from MCP config", () => {
+		config.setMcpInitConfig({
+			LOKALISE_API_HOSTNAME: "https://api.stage.lokalise.cloud/api2/",
+		});
+
+		config.load();
+
+		expect(config.getLokaliseHostname()).toBe("stage.lokalise.cloud");
+	});
+});

src/shared/utils/config.util.ts

@@ -6,13 +6,15 @@ import { Logger } from "./logger.util.js";
 
 /**
  * Configuration loader that handles multiple sources with priority:
- * 1. Direct ENV pass (process.env)
- * 2. .env file in project root
- * 3. Global config file at $HOME/.mcp/configs.json
+ * 1. MCP initialization config (from clientInfo)
+ * 2. Direct ENV pass (process.env)
+ * 3. .env file in project root
+ * 4. Global config file at $HOME/.mcp/configs.json
  */
 class ConfigLoader {
 	private packageName: string;
 	private configLoaded = false;
+	private mcpInitConfig: Record<string, unknown> = {};
 
 	/**
 	 * Create a new ConfigLoader instance
@@ -22,6 +24,22 @@ class ConfigLoader {
 		this.packageName = packageName;
 	}
 
+	/**
+	 * Set configuration from MCP initialization (highest priority)
+	 * @param config Configuration object from MCP clientInfo
+	 */
+	setMcpInitConfig(config: Record<string, unknown>): void {
+		const methodLogger = Logger.forContext(
+			"utils/config.util.ts",
+			"setMcpInitConfig",
+		);
+
+		this.mcpInitConfig = { ...config };
+		methodLogger.debug("MCP initialization configuration set", {
+			keysCount: Object.keys(config).length,
+		});
+	}
+
 	/**
 	 * Load configuration from all sources with proper priority
 	 */
@@ -35,15 +53,18 @@ class ConfigLoader {
 
 		methodLogger.debug("Loading configuration...");
 
-		// Priority 3: Load from global config file
+		// Priority 4: Load from global config file
 		this.loadFromGlobalConfig();
 
-		// Priority 2: Load from .env file
+		// Priority 3: Load from .env file
 		this.loadFromEnvFile();
 
-		// Priority 1: Direct ENV pass is already in process.env
+		// Priority 2: Direct ENV pass is already in process.env
 		// No need to do anything as it already has highest priority
 
+		// Priority 1: MCP init config is handled in get() method
+		// No need to set process.env as it might conflict with existing values
+
 		this.configLoaded = true;
 		methodLogger.debug("Configuration loaded successfully");
 	}
@@ -92,7 +113,7 @@ class ConfigLoader {
 
 			// Determine the potential keys for the current package
 			const shortKey = "boilerplate"; // Project-specific short key
-			const fullPackageName = this.packageName; // e.g., '@aashari/boilerplate-mcp-server'
+			const fullPackageName = this.packageName; // e.g., 'lokalise-mcp'
 			const unscopedPackageName =
 				fullPackageName.split("/")[1] || fullPackageName; // e.g., 'boilerplate-mcp-server'
 
@@ -145,6 +166,12 @@ class ConfigLoader {
 	 * @returns The configuration value or the default value
 	 */
 	get(key: string, defaultValue?: string): string | undefined {
+		// Priority 1: MCP initialization config
+		if (this.mcpInitConfig[key] !== undefined) {
+			return String(this.mcpInitConfig[key]);
+		}
+
+		// Priority 2: Environment variables
 		return process.env[key] || defaultValue;
 	}
 
@@ -196,4 +223,4 @@ class ConfigLoader {
 }
 
 // Create and export a singleton instance with the package name from package.json
-export const config = new ConfigLoader("@aashari/boilerplate-mcp-server");
+export const config = new ConfigLoader("lokalise-mcp");