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.

Author: AbdallahAHO

Dockerfile

@@ -26,6 +26,12 @@ COPY --from=builder /app/dist ./dist
 
 # Default environment
 ENV TRANSPORT_MODE=http
+ENV LOKALISE_API_KEY=YOUR_LOKALISE_API_KEY_HERE
+ENV LOKALISE_API_HOSTNAME=https://api.stage.lokalise.cloud/api2/
+ENV DEBUG=true
+ENV MCP_SERVER_MODE=true
+ENV NODE_ENV=production
+
 EXPOSE 3000
 
 CMD ["node", "dist/index.js"]

docs/CONFIGURATION.md

@@ -0,0 +1,200 @@
+# Configuration Management
+
+## Overview
+
+The Lokalise MCP server uses a centralized configuration management system that provides:
+- **Single entry point** for all configuration access
+- **Strong typing** with TypeScript and Zod validation
+- **Priority-based** configuration loading from multiple sources
+- **Environment-specific** configuration support
+
+## Configuration Priority
+
+Configuration values are loaded from multiple sources with the following priority (highest to lowest):
+
+1. **HTTP Query Parameters** (Smithery) - Passed via query strings
+2. **MCP Initialization Config** - From clientInfo during MCP initialization
+3. **Environment Variables** - Direct process.env values
+4. **`.env` File** - Project root .env file
+5. **Global Config File** - `~/.mcp/configs.json`
+
+Higher priority sources override lower priority ones.
+
+## Usage
+
+### Import the Config Utility
+
+```typescript
+import { config } from "./shared/utils/config.util.js";
+```
+
+### Load Configuration
+
+Configuration is automatically loaded when first accessed, but can be explicitly loaded:
+
+```typescript
+config.load(); // Called automatically in main entry point
+```
+
+### Access Configuration Values
+
+All configuration access should go through typed getter methods:
+
+```typescript
+// Core configuration
+const apiKey = config.getLokaliseApiKey();        // Required, throws if not set
+const apiHost = config.getLokaliseApiHostname();  // With default fallback
+
+// Server configuration
+const transportMode = config.getTransportMode();  // "stdio" | "http"
+const port = config.getPort();                    // Default: 3000
+
+// Debug configuration
+const isDebug = config.isDebugEnabled();          // boolean
+const debugPattern = config.getDebugPattern();    // string | undefined
+
+// Environment detection
+const isTest = config.isTestEnvironment();        // Detects test environment
+const isMcpServer = config.isMcpServerMode();     // MCP server vs CLI mode
+const nodeEnv = config.getNodeEnv();              // "development" | "test" | "production"
+```
+
+### Set Configuration from Different Sources
+
+```typescript
+// Set HTTP query configuration (highest priority)
+config.setHttpQueryConfig({
+  LOKALISE_API_KEY: "key_from_query",
+  debug_mode: true
+});
+
+// Set MCP initialization configuration
+config.setMcpInitConfig({
+  LOKALISE_API_KEY: "key_from_mcp",
+  DEBUG: false
+});
+```
+
+### Validate Configuration
+
+```typescript
+const validation = config.validate();
+if (!validation.valid) {
+  console.error("Configuration errors:", validation.errors);
+}
+```
+
+## Environment Variables
+
+The following environment variables are supported:
+
+| Variable | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `LOKALISE_API_KEY` | string | Yes | - | Your Lokalise API token |
+| `LOKALISE_API_HOSTNAME` | string | No | `https://api.lokalise.com/api2/` | Custom Lokalise API endpoint |
+| `TRANSPORT_MODE` | string | No | `stdio` | Transport mode: `stdio` or `http` |
+| `PORT` | number | No | `3000` | HTTP server port (only for HTTP transport) |
+| `DEBUG` | boolean/string | No | `false` | Debug mode or pattern for selective logging |
+| `NODE_ENV` | string | No | - | Node environment: `development`, `test`, `production` |
+| `MCP_SERVER_MODE` | boolean | No | `false` | Indicates if running as MCP server |
+
+## Configuration Files
+
+### `.env` File
+
+Create a `.env` file in the project root:
+
+```env
+LOKALISE_API_KEY=your_api_key_here
+LOKALISE_API_HOSTNAME=https://api.lokalise.com/api2/
+TRANSPORT_MODE=http
+PORT=3000
+DEBUG=true
+```
+
+### Global Config File
+
+Create `~/.mcp/configs.json` for global configuration:
+
+```json
+{
+  "lokalise-mcp": {
+    "environments": {
+      "LOKALISE_API_KEY": "your_global_api_key",
+      "LOKALISE_API_HOSTNAME": "https://api.lokalise.com/api2/"
+    }
+  }
+}
+```
+
+## Debug Configuration
+
+The `DEBUG` environment variable supports multiple formats:
+
+- `true` or `1` - Enable all debug logging
+- `false` or `0` - Disable debug logging
+- Pattern string - Enable selective logging (e.g., `"controllers/*,services/*"`)
+
+Examples:
+```bash
+DEBUG=true                    # Enable all debug
+DEBUG=controllers/*           # Debug only controllers
+DEBUG=services/*,utils/*      # Debug services and utils
+```
+
+## Type Safety
+
+All configuration is strongly typed using Zod schemas:
+
+```typescript
+// Configuration schema is defined in src/shared/schemas/config.schema.ts
+export const RuntimeConfigSchema = z.object({
+  LOKALISE_API_KEY: z.string().min(1, "LOKALISE_API_KEY is required"),
+  LOKALISE_API_HOSTNAME: z.string().url().default("https://api.lokalise.com/api2/"),
+  TRANSPORT_MODE: z.enum(["stdio", "http"]).default("stdio"),
+  PORT: z.number().int().min(1).max(65535).default(3000),
+  DEBUG: z.union([z.boolean(), z.string()]).default(false),
+  // ... other fields
+});
+```
+
+## Best Practices
+
+1. **Never access `process.env` directly** - Always use the config utility
+2. **Use typed getter methods** - Avoid generic `config.get()` when possible
+3. **Handle configuration errors early** - Validate configuration at startup
+4. **Use appropriate defaults** - Provide sensible defaults for optional values
+5. **Document required variables** - Clearly indicate which variables are required
+
+## Migration Guide
+
+If you're updating code that previously used `process.env` directly:
+
+```typescript
+// ❌ Old way - direct process.env access
+const apiKey = process.env.LOKALISE_API_KEY;
+const isTest = process.env.NODE_ENV === "test";
+
+// ✅ New way - through config utility
+import { config } from "./shared/utils/config.util.js";
+const apiKey = config.getLokaliseApiKey();
+const isTest = config.isTestEnvironment();
+```
+
+## Exceptions
+
+The following cases legitimately use `process.env` directly:
+
+1. **Logger utility** - To avoid circular dependencies
+2. **Test utilities** - When spawning child processes or manipulating test environment
+3. **Build scripts** - Scripts that run outside the main application context
+
+## Smithery Integration
+
+For Smithery deployments, configuration can be passed via HTTP query parameters:
+
+```
+GET /mcp?LOKALISE_API_KEY=key&debug_mode=true
+```
+
+These query parameters have the highest priority and will override all other configuration sources.