chore: support schema overrides and parserOptions

Author: gagik

MCP_SERVER_LIBRARY.md

@@ -49,7 +49,7 @@ import {
   Session,
   UserConfig,
   UserConfigSchema,
-  parseCliArgumentsAsUserConfig,
+  parseUserConfig,
   StreamableHttpRunner,
   StdioRunner,
   TransportRunnerBase,
@@ -811,26 +811,25 @@ const customConfig = UserConfigSchema.parse({
 
 This approach ensures you get all the default values without having to specify every configuration key manually.
 
-### parseCliArgumentsAsUserConfig
+### parseUserConfig
 
 Utility function to parse command-line arguments and environment variables into a UserConfig object, using the same parsing logic as the MongoDB MCP server CLI.
 
 _Note: This is what MongoDB MCP server uses internally._
 
 ```typescript
-function parseCliArgumentsAsUserConfig(options?: {
+function parseUserConfig(options?: {
   args?: string[];
-  helpers?: CreateUserConfigHelpers;
 }): UserConfig;
 ```
 
 **Example:**
 
 ```typescript
-import { parseCliArgumentsAsUserConfig, StdioRunner } from "mongodb-mcp-server";
+import { parseUserConfig, StdioRunner } from "mongodb-mcp-server";
 
 // Parse config from process.argv and environment variables
-const config = parseCliArgumentsAsUserConfig();
+const config = parseUserConfig();
 
 const runner = new StdioRunner({ userConfig: config });
 await runner.start();

src/common/config/createUserConfig.ts

@@ -4,19 +4,52 @@ import type { Secret } from "../keychain.js";
 import { matchingConfigKey } from "./configUtils.js";
 import { UserConfigSchema, type UserConfig } from "./userConfig.js";
 import {
-    defaultParserOptions,
+    defaultParserOptions as defaultArgParserOptions,
     parseArgsWithCliOptions,
     CliOptionsSchema,
     UnknownArgumentError,
 } from "@mongosh/arg-parser/arg-parser";
-import type { z as z4 } from "zod/v4";
-
-export function createUserConfig({ args }: { args: string[] }): {
+import { z as z4 } from "zod/v4";
+import type yargsParser from "yargs-parser";
+
+export type ParserOptions = Partial<yargsParser.Options>;
+
+export const defaultParserOptions = {
+    // This is the name of key that yargs-parser will look up in CLI
+    // arguments (--config) and ENV variables (MDB_MCP_CONFIG) to load an
+    // initial configuration from.
+    config: "config",
+    // This helps parse the relevant environment variables.
+    envPrefix: "MDB_MCP_",
+    configuration: {
+        ...defaultArgParserOptions.configuration,
+        // To avoid populating `_` with end-of-flag arguments we explicitly
+        // populate `--` variable and altogether ignore them later.
+        "populate--": true,
+    },
+} satisfies ParserOptions;
+
+export function createUserConfig({
+    args,
+    overrides,
+    parserOptions = defaultParserOptions,
+}: {
+    args: string[];
+    overrides?: z4.ZodRawShape;
+    parserOptions?: ParserOptions;
+}): {
     warnings: string[];
     parsed: UserConfig | undefined;
     error: string | undefined;
 } {
-    const { error: parseError, warnings, parsed } = parseUserConfigSources(args);
+    const schema = overrides
+        ? z4.object({
+              ...UserConfigSchema.shape,
+              ...overrides,
+          })
+        : UserConfigSchema;
+
+    const { error: parseError, warnings, parsed } = parseUserConfigSources({ args, schema, parserOptions });
 
     if (parseError) {
         return { error: parseError, warnings, parsed: undefined };
@@ -40,7 +73,7 @@ export function createUserConfig({ args }: { args: string[] }): {
         parsed.connectionString = connectionInfo.connectionString;
     }
 
-    const configParseResult = UserConfigSchema.safeParse(parsed);
+    const configParseResult = schema.safeParse(parsed);
     const mongoshArguments = CliOptionsSchema.safeParse(parsed);
     const error = configParseResult.error || mongoshArguments.error;
     if (error) {
@@ -62,34 +95,29 @@ export function createUserConfig({ args }: { args: string[] }): {
     };
 }
 
-function parseUserConfigSources(cliArguments: string[]): {
+function parseUserConfigSources<T extends typeof UserConfigSchema>({
+    args,
+    schema = UserConfigSchema as T,
+    parserOptions,
+}: {
+    args: string[];
+    schema: T;
+    parserOptions: ParserOptions;
+}): {
     error: string | undefined;
     warnings: string[];
-    parsed: Partial<CliOptions & z4.infer<typeof UserConfigSchema>>;
+    parsed: Partial<CliOptions & z4.infer<T>>;
 } {
-    let parsed: Partial<CliOptions & z4.infer<typeof UserConfigSchema>>;
-    let deprecated: Record<string, keyof UserConfig>;
+    let parsed: Partial<CliOptions & z4.infer<T>>;
+    let deprecated: Record<string, string>;
     try {
         const { parsed: parsedResult, deprecated: deprecatedResult } = parseArgsWithCliOptions({
-            args: cliArguments,
-            schema: UserConfigSchema,
-            parserOptions: {
-                // This is the name of key that yargs-parser will look up in CLI
-                // arguments (--config) and ENV variables (MDB_MCP_CONFIG) to load an
-                // initial configuration from.
-                config: "config",
-                // This helps parse the relevant environment variables.
-                envPrefix: "MDB_MCP_",
-                configuration: {
-                    ...defaultParserOptions.configuration,
-                    // To avoid populating `_` with end-of-flag arguments we explicitly
-                    // populate `--` variable and altogether ignore them later.
-                    "populate--": true,
-                },
-            },
+            args,
+            schema,
+            parserOptions,
         });
         parsed = parsedResult;
-        deprecated = deprecatedResult;
+        deprecated = deprecatedResult as Record<string, string>;
 
         // Delete fileNames - this is a field populated by mongosh but not used by us.
         delete parsed.fileNames;
@@ -112,7 +140,7 @@ function parseUserConfigSources(cliArguments: string[]): {
     }
 
     const deprecationWarnings = [
-        ...getWarnings(parsed, cliArguments),
+        ...getWarnings(parsed, args),
         ...Object.entries(deprecated).map(([deprecated, replacement]) => {
             return `Warning: The --${deprecated} argument is deprecated. Use --${replacement} instead.`;
         }),

src/lib.ts

@@ -1,7 +1,7 @@
 export { Server, type ServerOptions } from "./server.js";
 export { Session, type SessionOptions } from "./common/session.js";
 export { type UserConfig, UserConfigSchema } from "./common/config/userConfig.js";
-export { createUserConfig as parseCliArgumentsAsUserConfig } from "./common/config/createUserConfig.js";
+export { createUserConfig, defaultParserOptions, type ParserOptions } from "./common/config/createUserConfig.js";
 export { LoggerBase, type LogPayload, type LoggerType, type LogLevel } from "./common/logger.js";
 export { StreamableHttpRunner } from "./transports/streamableHttp.js";
 export { StdioRunner } from "./transports/stdio.js";

src/transports/base.ts

@@ -75,7 +75,7 @@ export type TransportRunnerConfig = {
      *
      * To parse CLI arguments and environment variables in order to generate a
      * `UserConfig` object, you can use `createUserConfig` function, also
-     * exported as `parseCliArgumentsAsUserConfig` through MCP server library
+     * exported as `parseUserConfig` through MCP server library
      * exports.
      *
      * Optionally, you can also use `UserConfigSchema` (available through MCP

tests/unit/common/config.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { type UserConfig, UserConfigSchema } from "../../../src/common/config/userConfig.js";
-import { createUserConfig } from "../../../src/common/config/createUserConfig.js";
+import { createUserConfig, defaultParserOptions } from "../../../src/common/config/createUserConfig.js";
 import {
     getLogPath,
     getExportsPath,
@@ -69,6 +69,24 @@ describe("config", () => {
         });
     });
 
+    it("can override defaults in the schema and those are populated instead", () => {
+        expect(
+            createUserConfig({
+                args: [],
+                overrides: {
+                    exportTimeoutMs: UserConfigSchema.shape.exportTimeoutMs.default(123),
+                },
+            })
+        ).toStrictEqual({
+            parsed: {
+                ...expectedDefaults,
+                exportTimeoutMs: 123,
+            },
+            warnings: [],
+            error: undefined,
+        });
+    });
+
     describe("env var parsing", () => {
         const { setVariable, clearVariables } = createEnvironment();
 
@@ -143,6 +161,20 @@ describe("config", () => {
                 });
             }
         });
+
+        it("works with custom prefixes through parserOptions", () => {
+            setVariable("CUSTOM_MCP_DISABLED_TOOLS", "find,export");
+            // Ensure our own ENV doesn't affect it
+            setVariable("MDB_MCP_DISABLED_TOOLS", "explain");
+            const { parsed: actual } = createUserConfig({
+                args: [],
+                parserOptions: {
+                    ...defaultParserOptions,
+                    envPrefix: "CUSTOM_MCP_",
+                },
+            });
+            expect(actual?.disabledTools).toEqual(["find", "export"]);
+        });
     });
 
     describe("cli parsing", () => {