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);
@@ -86,6 +89,34 @@ export async function startServer(
 			transportInstance = transport;
 
 			app.all(mcpEndpoint, (req: Request, res: Response) => {
+				// Extract query parameters for Smithery configuration
+				const queryConfig = req.query;
+				if (Object.keys(queryConfig).length > 0) {
+					serverLogger.debug("Received query parameters", { queryConfig });
+
+					// Parse dot-notation query parameters into nested objects
+					const parsedConfig: Record<string, unknown> = {};
+					for (const [key, value] of Object.entries(queryConfig)) {
+						// Handle dot notation (e.g., server.host -> { server: { host: value } })
+						const parts = key.split(".");
+						let current = parsedConfig;
+
+						for (let i = 0; i < parts.length - 1; i++) {
+							const part = parts[i];
+							if (!(part in current)) {
+								current[part] = {};
+							}
+							current = current[part] as Record<string, unknown>;
+						}
+
+						// Set the final value
+						current[parts[parts.length - 1]] = value;
+					}
+
+					// Set the HTTP query configuration with highest priority
+					config.setHttpQueryConfig(parsedConfig);
+				}
+
 				transport.handleRequest(req, res, req.body).catch((err: unknown) => {
 					serverLogger.error("Error in transport.handleRequest", err);
 					if (!res.headersSent) {
@@ -219,3 +250,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,16 @@ 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> = {};
+	private httpQueryConfig: Record<string, unknown> = {};
 
 	/**
 	 * Create a new ConfigLoader instance
@@ -22,6 +25,39 @@ class ConfigLoader {
 		this.packageName = packageName;
 	}
 
+	/**
+	 * Set configuration from HTTP query parameters (highest priority for Smithery)
+	 * @param config Configuration object from HTTP query parameters
+	 */
+	setHttpQueryConfig(config: Record<string, unknown>): void {
+		const methodLogger = Logger.forContext(
+			"utils/config.util.ts",
+			"setHttpQueryConfig",
+		);
+
+		this.httpQueryConfig = { ...config };
+		methodLogger.debug("HTTP query parameter configuration set", {
+			keysCount: Object.keys(config).length,
+			keys: Object.keys(config),
+		});
+	}
+
+	/**
+	 * Set configuration from MCP initialization (second 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 +71,21 @@ class ConfigLoader {
 
 		methodLogger.debug("Loading configuration...");
 
-		// Priority 3: Load from global config file
+		// Priority 5: Load from global config file
 		this.loadFromGlobalConfig();
 
-		// Priority 2: Load from .env file
+		// Priority 4: Load from .env file
 		this.loadFromEnvFile();
 
-		// Priority 1: Direct ENV pass is already in process.env
+		// Priority 3: Direct ENV pass is already in process.env
 		// No need to do anything as it already has highest priority
 
+		// Priority 2: MCP init config is handled in get() method
+		// No need to set process.env as it might conflict with existing values
+
+		// Priority 1: HTTP query config is handled in get() method
+		// This has the highest priority for Smithery deployments
+
 		this.configLoaded = true;
 		methodLogger.debug("Configuration loaded successfully");
 	}
@@ -91,12 +133,11 @@ class ConfigLoader {
 			const config = JSON.parse(configContent);
 
 			// 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'
+				fullPackageName.split("/")[1] || fullPackageName; // e.g., 'lokalise-mcp'
 
-			const potentialKeys = [shortKey, fullPackageName, unscopedPackageName];
+			const potentialKeys = [fullPackageName, unscopedPackageName];
 			let foundConfigSection: {
 				environments?: Record<string, unknown>;
 			} | null = null;
@@ -145,6 +186,17 @@ class ConfigLoader {
 	 * @returns The configuration value or the default value
 	 */
 	get(key: string, defaultValue?: string): string | undefined {
+		// Priority 1: HTTP query parameters (highest priority for Smithery)
+		if (this.httpQueryConfig[key] !== undefined) {
+			return String(this.httpQueryConfig[key]);
+		}
+
+		// Priority 2: MCP initialization config
+		if (this.mcpInitConfig[key] !== undefined) {
+			return String(this.mcpInitConfig[key]);
+		}
+
+		// Priority 3: Environment variables
 		return process.env[key] || defaultValue;
 	}
 
@@ -196,4 +248,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");

src/shared/utils/transport.util.ts

@@ -184,9 +184,16 @@ export async function fetchLokaliseApi<T>(
 	// Get credentials (token is required)
 	const credentials = getLokaliseApiCredentials();
 
-	// Construct the full URL
-	const baseUrl = "https://api.stage.lokalise.cloud/api2//api2";
-	const url = `${baseUrl}${path}`;
+	// Get the API hostname from configuration
+	const apiHostname =
+		config.get("LOKALISE_API_HOSTNAME") || "https://api.lokalise.com/api2/";
+
+	// Ensure the hostname ends with a slash and remove any duplicate slashes
+	const baseUrl = apiHostname.endsWith("/")
+		? apiHostname.slice(0, -1)
+		: apiHostname;
+	const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+	const url = `${baseUrl}${normalizedPath}`;
 
 	methodLogger.debug(`Constructed Lokalise API URL: ${url}`);