feat: add ability to override parameters using HTTP headers MCP-293

Author: gagik

package.json

@@ -65,7 +65,7 @@
     "generate": "npm run generate:api && npm run generate:arguments",
     "generate:api": "./scripts/generate.sh",
     "generate:arguments": "tsx scripts/generateArguments.ts",
-    "test": "vitest --project eslint-rules --project unit-and-integration --coverage",
+    "test": "vitest --project eslint-rules --project unit-and-integration --coverage --run",
     "pretest:accuracy": "npm run build",
     "test:accuracy": "sh ./scripts/accuracy/runAccuracyTests.sh",
     "test:long-running-tests": "vitest --project long-running-tests --coverage",

src/common/config/configOverrides.ts

@@ -0,0 +1,157 @@
+import type { UserConfig } from "./userConfig.js";
+import { UserConfigSchema, configRegistry } from "./userConfig.js";
+import type { RequestContext } from "../../transports/base.js";
+import type { OverrideBehavior } from "./configUtils.js";
+
+export const CONFIG_HEADER_PREFIX = "x-mongodb-mcp-";
+export const CONFIG_QUERY_PREFIX = "mongodbMcp";
+
+/**
+ * Applies config overrides from request context (headers and query parameters).
+ * Query parameters take precedence over headers.
+ *
+ * @param baseConfig - The base user configuration
+ * @param request - The request context containing headers and query parameters
+ * @returns The configuration with overrides applied
+ */
+export function applyConfigOverrides({
+    baseConfig,
+    request,
+}: {
+    baseConfig: UserConfig;
+    request?: RequestContext;
+}): UserConfig {
+    if (!request) {
+        return baseConfig;
+    }
+
+    const result: UserConfig = { ...baseConfig };
+    const overridesFromHeaders = extractConfigOverrides("header", request.headers);
+    const overridesFromQuery = extractConfigOverrides("query", request.query);
+
+    // Merge overrides, with query params taking precedence
+    const allOverrides = { ...overridesFromHeaders, ...overridesFromQuery };
+
+    // Apply each override according to its behavior
+    for (const [key, overrideValue] of Object.entries(allOverrides)) {
+        assertValidConfigKey(key);
+        const behavior = getConfigMeta(key)?.overrideBehavior || "not-allowed";
+        const baseValue = baseConfig[key as keyof UserConfig];
+        const newValue = applyOverride(key, baseValue, overrideValue, behavior);
+        (result as any)[key] = newValue;
+    }
+
+    return result;
+}
+
+/**
+ * Extracts config overrides from HTTP headers or query parameters.
+ */
+function extractConfigOverrides(
+    mode: "header" | "query",
+    source: Record<string, string | string[] | undefined> | undefined
+): Partial<Record<keyof typeof UserConfigSchema.shape, unknown>> {
+    if (!source) {
+        return {};
+    }
+
+    const overrides: Partial<Record<keyof typeof UserConfigSchema.shape, unknown>> = {};
+
+    for (const [name, value] of Object.entries(source)) {
+        const configKey = nameToConfigKey(mode, name);
+        if (!configKey) {
+            continue;
+        }
+        assertValidConfigKey(configKey);
+
+        const behavior = getConfigMeta(configKey)?.overrideBehavior || "not-allowed";
+        if (behavior === "not-allowed") {
+            throw new Error(`Config key ${configKey} is not allowed to be overridden`);
+        }
+
+        const parsedValue = parseConfigValue(configKey, value);
+        if (parsedValue !== undefined) {
+            overrides[configKey] = parsedValue;
+        }
+    }
+
+    return overrides;
+}
+
+function assertValidConfigKey(key: string): asserts key is keyof typeof UserConfigSchema.shape {
+    if (!(key in UserConfigSchema.shape)) {
+        throw new Error(`Invalid config key: ${key}`);
+    }
+}
+
+/**
+ * Gets the schema metadata for a config key.
+ */
+export function getConfigMeta(key: keyof typeof UserConfigSchema.shape) {
+    return configRegistry.get(UserConfigSchema.shape[key]);
+}
+
+/**
+ * Parses a string value to the appropriate type using the Zod schema.
+ */
+function parseConfigValue(key: keyof typeof UserConfigSchema.shape, value: unknown): unknown {
+    const fieldSchema = UserConfigSchema.shape[key as keyof typeof UserConfigSchema.shape];
+    if (!fieldSchema) {
+        throw new Error(`Invalid config key: ${key}`);
+    }
+
+    return fieldSchema.safeParse(value).data;
+}
+
+/**
+ * Converts a header/query name to its config key format.
+ * Example: "x-mongodb-mcp-read-only" -> "readOnly"
+ * Example: "mongodbMcpReadOnly" -> "readOnly"
+ */
+export function nameToConfigKey(mode: "header" | "query", name: string): string | undefined {
+    const lowerCaseName = name.toLowerCase();
+
+    if (mode === "header" && lowerCaseName.startsWith(CONFIG_HEADER_PREFIX)) {
+        const normalized = lowerCaseName.substring(CONFIG_HEADER_PREFIX.length);
+        // Convert kebab-case to camelCase
+        return normalized.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    }
+    if (mode === "query" && name.startsWith(CONFIG_QUERY_PREFIX)) {
+        const withoutPrefix = name.substring(CONFIG_QUERY_PREFIX.length);
+        // Convert first letter to lowercase to get config key
+        return withoutPrefix.charAt(0).toLowerCase() + withoutPrefix.slice(1);
+    }
+
+    return undefined;
+}
+
+function applyOverride(
+    key: keyof typeof UserConfigSchema.shape,
+    baseValue: unknown,
+    overrideValue: unknown,
+    behavior: OverrideBehavior
+): unknown {
+    if (typeof behavior === "function") {
+        const shouldApply = behavior(baseValue, overrideValue);
+        if (!shouldApply) {
+            throw new Error(
+                `Config override validation failed for ${key}: cannot override from ${JSON.stringify(baseValue)} to ${JSON.stringify(overrideValue)}`
+            );
+        }
+        return overrideValue;
+    }
+    switch (behavior) {
+        case "override":
+            return overrideValue;
+
+        case "merge":
+            if (Array.isArray(baseValue) && Array.isArray(overrideValue)) {
+                return [...baseValue, ...overrideValue];
+            }
+            throw new Error("Cannot merge non-array values, did you mean to use the 'override' behavior?");
+
+        case "not-allowed":
+        default:
+            return baseValue;
+    }
+}

src/common/config/configUtils.ts

@@ -4,6 +4,22 @@ import { ALL_CONFIG_KEYS } from "./argsParserOptions.js";
 import * as levenshteinModule from "ts-levenshtein";
 const levenshtein = levenshteinModule.default;
 
+/// Custom logic function to apply the override value.
+/// Returns true if the override should be applied, false otherwise.
+export type CustomOverrideLogic = (oldValue: unknown, newValue: unknown) => boolean;
+
+/**
+ * Defines how a config field can be overridden via HTTP headers or query parameters.
+ */
+export type OverrideBehavior =
+    /// Cannot be overridden via request
+    | "not-allowed"
+    /// Can be completely replaced
+    | "override"
+    /// Values are merged (for arrays)
+    | "merge"
+    | CustomOverrideLogic;
+
 /**
  * Metadata for config schema fields.
  */
@@ -17,7 +33,11 @@ export type ConfigFieldMeta = {
      * Secret fields will be marked as secret in environment variable definitions.
      */
     isSecret?: boolean;
-
+    /**
+     * Defines how this config field can be overridden via HTTP headers or query parameters.
+     * Defaults to "not-allowed" for security.
+     */
+    overrideBehavior?: OverrideBehavior;
     [key: string]: unknown;
 };
 
@@ -69,8 +89,11 @@ export function commaSeparatedToArray<T extends string[]>(str: string | string[]
         return undefined;
     }
 
-    if (!Array.isArray(str)) {
-        return [str] as T;
+    if (typeof str === "string") {
+        return str
+            .split(",")
+            .map((e) => e.trim())
+            .filter((e) => e.length > 0) as T;
     }
 
     if (str.length === 1) {
@@ -82,3 +105,22 @@ export function commaSeparatedToArray<T extends string[]>(str: string | string[]
 
     return str as T;
 }
+
+/**
+ * Preprocessor for boolean values that handles string "true"/"false" correctly.
+ * Zod's coerce.boolean() treats any non-empty string as true, which is not what we want.
+ */
+export function parseBoolean(val: unknown): unknown {
+    if (typeof val === "string") {
+        const lower = val.toLowerCase().trim();
+        if (lower === "false" || lower === "0") return false;
+        if (lower === "true" || lower === "1") return true;
+    }
+    if (typeof val === "boolean") {
+        return val;
+    }
+    if (typeof val === "number") {
+        return val !== 0;
+    }
+    return false;
+}